Overview

The System Audit integration collects various security-related information about a system. All data streams send both periodic state information (e.g. all currently installed packages) and real-time changes (e.g. when a new package is installed/uninstalled or an existing package is updated). Currently, the only implemented data stream is the package data stream, which collects various information about system packages. In the future, more data streams like (process, socket, hosts .. etc) will be added.

How it works

Each data stream sends two kinds of information: state and events.

State information is sent periodically. A state update will consist of events for each package that is installed or has had its state change in the polling period. All events belonging to the same state update will share the same UUID in event.id.

The frequency of state updates can be controlled for all data streams using the state.period configuration option. The default is 12h.

Event information is sent as the events occur (e.g. a package is installed, uninstalled or updated). All data streams are currently using a poll model to retrieve their data. The frequency of these polls is controlled by the period configuration parameter.

Entity IDs

This module populates entity_id fields to uniquely identify entities (packages) within a host. This requires the module to obtain a unique identifier for the host:

• macOS: Uses the value returned by gethostuuid(2) system call.
• Linux: Uses the content of one of the following files, created by either systemd or dbus:

• /etc/machine-id
• /var/lib/dbus/machine-id
• /var/db/dbus/machine-id

NOTE: Under CentOS 6.x, it's possible that none of the files above exist. In that case, running dbus-uuidgen --ensure (provided by the dbus package) will generate one for you. One more thing to consider is that at the moment this integration is not supported on Windows systems.

Requirements

You need Elasticsearch for storing and searching your data and Kibana for visualizing and managing it. You can use our hosted Elasticsearch Service on Elastic Cloud, which is recommended, or self-manage the Elastic Stack on your own hardware.

Setup

For step-by-step instructions on how to set up an integration, see the Getting Started guide.

NOTE: If you want to supress host related information, please consider adding the tag: forwarded. Adding this tag to the tag list will remove any host-related data from the output, this will also stop certain dashboards from displaying host/os-related information/charts.

Data Streams

The data streams which are currently supported are:-

• package

Package helps you keep a record of events and changes happening to different packages on your system. The fields & events associated with the data stream are as follows:-

Exported fields

An example event for package looks as following:

{
    "@timestamp": "2023-01-31T11:44:38.695Z",
    "agent": {
        "ephemeral_id": "c9a6d8c0-780c-4b96-81f2-5a8c850bd0cc",
        "id": "027bc354-85a6-40d6-be9d-7eb4533fbd18",
        "name": "docker-fleet-agent",
        "type": "auditbeat",
        "version": "8.5.1"
    },
    "data_stream": {
        "dataset": "system_audit.package",
        "namespace": "ep",
        "type": "logs"
    },
    "ecs": {
        "version": "8.11.0"
    },
    "elastic_agent": {
        "id": "027bc354-85a6-40d6-be9d-7eb4533fbd18",
        "snapshot": false,
        "version": "8.5.1"
    },
    "event": {
        "action": "existing_package",
        "agent_id_status": "verified",
        "category": [
            "package"
        ],
        "dataset": "system_audit.package",
        "id": "f2b5baf6-fd22-490a-82fd-a044ff7075cb",
        "ingested": "2023-01-31T11:44:40Z",
        "kind": "state",
        "module": "system",
        "type": [
            "info"
        ]
    },
    "host": {
        "architecture": "x86_64",
        "containerized": false,
        "hostname": "docker-fleet-agent",
        "id": "75e38940166b4dbc90b6f5610e8e9c39",
        "ip": [
            "192.168.80.7"
        ],
        "mac": [
            "02-42-C0-A8-50-07"
        ],
        "name": "docker-fleet-agent",
        "os": {
            "codename": "focal",
            "family": "debian",
            "kernel": "5.15.49-linuxkit",
            "name": "Ubuntu",
            "platform": "ubuntu",
            "type": "linux",
            "version": "20.04.5 LTS (Focal Fossa)"
        }
    },
    "input": {
        "type": "audit/system"
    },
    "message": "Package adduser (3.118ubuntu2) is already installed",
    "package": {
        "architecture": "all",
        "description": "add and remove users and groups",
        "name": "adduser",
        "size": 624,
        "type": "dpkg",
        "version": "3.118ubuntu2"
    },
    "system_audit": {
        "package": {
            "arch": "all",
            "entity_id": "OnUSNhuUQkyYgoKf",
            "name": "adduser",
            "size": 624,
            "summary": "add and remove users and groups",
            "version": "3.118ubuntu2"
        }
    },
    "tags": [
        "audit-system-package"
    ]
}

Example dashboard

The integration comes with a package & audit system dashboard for easy identification of events and data overview :

Package Dashboard:

— Click to open this image in fullscreen mode

System Audit Dashboard:

— Click to open this image in fullscreen mode

Reference

For further information, please look at the Auditbeat System Module documentation.

Changelog