Audit Trail
An audit trail (also called an audit log) is a security-relevant chronological record, set of records, and/or destination and source of records that provide documentary evidence of the sequence of activities that have affected at any time a specific operation, procedure, event, or device.
In Pro Mosquitto, the audit trail feature has two components - the in-broker functionality which provides a mechanism for the broker and plugins to send audit events and which can be configured to filter which events are accepted. The second part is a reporting plugin which sends the filtered events on to their final destination. At present, the syslog reporting plugin is available.
Audit trail configuration
The Audit Trail feature in Mosquitto can be configured to allow control over which event are reported. There are two mechanisms to achieve this. The first is through the use of a log threshold, which only reports events which are greater than or equal to an importance threshold set by the administrator. The second is through the use of fine grained filters.
All configuration is done through a configuration file audit-trail.json
,
which must located in the persistence_location
directory.
If the audit-trail.json
file is not found, no audit events will be reported.
An example of the file is given below:
{
"filters": [
{
"filterType": "include",
"module": "dynamic-security"
},
{
"filterType": "include",
"module": "ha",
"operation": "createCluster"
},
{
"filterType": "exclude",
"operationType": "read"
}
]
"logThreshold": "debug"
}
Log threshold
The logThreshold
option can be set to one of debug
, info
, notice
,
warning
, and error
, which relate to the corresponding syslog log levels.o
Any audit events which have a lower importance than the log threshold will not
be logged. For example, setting the log threshold to warning
, means that only
events with importance of warning
and error
will be logged.
The default threshold is info
.
Filters
All audit events have an associated module
, operationType
, and operation
property. The filters functionality allows events to be filtered using all of
those properties.
The filters
part of the configuration file is a list of individual filters
that are to be applied to each event to determine whether it is to be reported.
The filters are evaluated in order and the final result applies. This means it
is straightforward to arrange very specific filters to pick out or exclude
certain events.
Each filter has a filterType
property which is the only required property,
and must be set to either include
, or exclude
. If the final result of
evaluating the filter list is include
, then the event will be reported. If
the final result is exclude
then the event will not be reported.
It is recommended to order the filters from most general to most specific.
The default behaviour is exclude reporting of events, so at least one include
filter must be provided.
The module
, operationType
, and operation
properties are used to match
events. All of these properties are optional. If the property is not present
then any property of that type will match. If the property is present, then an
event must match that property for the filter to be applied to the event.
The module
property is used to match against the provider of the event. This
will be core
for events coming from the core Mosquitto broker, or the name of
a plugin, e.g. dynamic-security
, ha
.
The operationType
property is used to match against the CRUD type of the
operation. If present, this property must be one of create
, read
, update
,
delete
, or other
. The other
type includes operation types that are not
well covered by the first four types, such as client connection/disconnection.
The operation
property is used to match against a specific operation by a
module. The list of available properties for each module is provided below. If
this property is available, the event operation must match exactly.
Filter example - exclude all
This is the default behaviour if audit-trail.json
is missing or empty, or if
no include
filters are defined.
Filter example - include all
Because only the filterType
property is used, this matches against every
event.
{
"filters": [
{
"filterType": "include"
}
]
}
Filter example - dynamic security module only
This matches against the dynamic security plugin events and reports all of them.
{
"filters": [
{
"filterType": "include",
"module": "dynamic-security"
}
]
}
Filter example - dynamic security excluding some operations
This matches against the dynamic security plugin events and reports all of
them apart from the disableClient
operation.
{
"filters": [
{
"filterType": "include",
"module": "dynamic-security"
},
{
"filterType": "exclude",
"module": "dynamic-security",
"operation": "disableClient"
}
]
}
Filter example - core broker excluding other operation types
This matches against the core broker events and reports all of
them apart from the other
operation type.
{
"filters": [
{
"filterType": "include",
"module": "core"
},
{
"filterType": "exclude",
"operationType": "other"
}
]
}
Filter example - multiple types
This is a more realistic setup that addresses multiple modules.
All core
events match and are reported.
All dynamic-security
events match, apart from those that are read
operation
All ha
events match, except the specific getRaftStatus
and isLeader
operations.
For the getRaftStatus
and isLeader
operations, the module
isn't
specifically set to ha
, however in this case those operations are only
available on that module.
{
"filters": [
{
"filterType": "include",
"module": "core"
},
{
"filterType": "include",
"module": "dynamic-security"
},
{
"filterType": "include",
"module": "ha"
},
{
"filterType": "exclude",
"module": "dynamic-security"
"operationType": "read"
},
{
"filterType": "exclude",
"operation": "getRaftStatus"
},
{
"filterType": "exclude",
"operation": "isLeader"
}
]
}
Audit trail syslog plugin configuration
To configure the syslog plugin, add the following to your Mosquitto configuration file:
global_plugin /path/to/cedalo_audit_trail_syslog.so
The plugin has some options which can be configured.
Log ident
By default, the log ident will be the program name, i.e. mosquitto
. This can
be changed with the plugin_opt_log_ident
option:
plugin_opt_log_ident audittrail
Log facility
By default, logging will use the daemon
facility. This can be changed to one
of local0
to local7
if required.
plugin_opt_log_facility local2
Log timestamp
By default the event timestamp in the payload is a Unix timestamp with
millisecond resolution. Alternatively, the plugin_opt_iso8601_timestamp
option may be used to have an ISO-8601 format timestamp.
plugin_opt_iso8601_timestamp true
Exclude IP address
By default the IP address of the client which originated the request will be
included in the audit event. If this is not wanted, the
plugin_opt_exclude_ip_address
option can be set to true.
plugin_opt_exclude_ip_address true
List of audit events
module | operation | operationType | log level |
---|---|---|---|
core | brokerStart | other | notice |
core | brokerStop | other | notice |
core | brokerReload | other | notice |
core | clientConnect | other | notice |
core | clientDisconnect | other | notice |
dynamic-security | createClient | create | notice |
dynamic-security | deleteClient | delete | notice |
dynamic-security | enableClient | update | notice |
dynamic-security | disableClient | update | notice |
dynamic-security | setClientId | update | info |
dynamic-security | setClientPassword | update | info |
dynamic-security | getClient | read | debug |
dynamic-security | listClients | read | debug |
dynamic-security | addClientRole | update | info |
dynamic-security | removeClientRole | update | info |
dynamic-security | modifyClient | update | info |
dynamic-security | createGroup | create | notice |
dynamic-security | getGroup | read | debug |
dynamic-security | listGroups | read | debug |
dynamic-security | addGroupClient | update | info |
dynamic-security | removeGroupClient | update | info |
dynamic-security | addGroupRole | update | info |
dynamic-security | removeGroupRole | update | info |
dynamic-security | modifyGroup | update | info |
dynamic-security | setAnonymousGroup | update | info |
dynamic-security | getAnonymousGroup | update | info |
dynamic-security | createRole | create | notice |
dynamic-security | deleteRole | delete | notice |
dynamic-security | getRole | read | debug |
dynamic-security | listRoles | read | debug |
dynamic-security | addRoleAcl | update | info |
dynamic-security | removeRoleAcl | update | info |
dynamic-security | modifyRole | update | info |
dynamic-security | getDefaultAcl | read | debug |
dynamic-security | setDefaultAcl | update | notice |
ha | createCluster | create | notice |
ha | joinCluster | create | notice |
ha | leaveCluster | update | notice |
ha | deleteCluster | delete | notice |
ha | addNode | update | notice |
ha | removeNode | update | notice |
ha | isLeader | read | debug |
ha | setLeader | update | notice |
ha | getNode | read | debug |
ha | getCluster | read | debug |
ha | getRaftStatus | read | debug |