audito-maldito

README

audito-maldito

audito-maldito is a daemon that monitors OpenSSH server logins and produces structured audit events describing what authenticated users did while logged in (e.g., what programs they executed).

audito-maldito monitors OpenSSH logins and then attempts to correlate authenticated user sessions with Linux kernel audit sessions. Once an audit session has been identified, new audito-maldito events are generated each time the Linux audit session receives a new event. This allows the application to tie an OpenSSH user's identity to their Linux audit session. For example, if a user authenticates using an SSH certificate, certificate details like the fingerprint and key ID will appear in each resulting audito-maldito audit event. These resulting events are written to a customizable file path.

Sysadmins define audit policy using auditd's audit.rules. audito-maldito simply honors whatever Linux audit events appear in the Linux auditd event stream.

For more information about configuring audito-maldito, please refer to the Configuration section.

System requirements

• Linux
• auditd
• OpenSSH server (sshd)

Audit event types

The following subsections detail the different types of audit events generated by audito-maldito. For more information about the structure of these events, please refer to the auditevent library.

UserLogin

Occurs when a user logs in via sshd.

Example:

{
  "component": "sshd",
  "data": {
    "Alg": "ECDSA-CERT SHA256",
    "CA": "CA ED25519 SHA256:JKH45TJj6tNHO/E/VtWZGunEY7C8VLFjVFv6bDq/5VY=",
    "SSHKeySum": "JKH45TJj6tNHO/E/VtWZGunEY7C8VLFjVFv6bDq/5VY",
    "Serial": "350"
  },
  "loggedAt": "2023-03-17T13:37:01.952459Z",
  "metadata": {
    "auditId": "ffffffff-ffff-ffff-ffff-ffffffffffff"
  },
  "outcome": "succeeded",
  "source": {
    "extra": {
      "port": "59145"
    },
    "type": "IP",
    "value": "6.6.6.2"
  },
  "subjects": {
    "loggedAs": "core",
    "pid": "3076344",
    "userID": "user@foo.com"
  },
  "target": {
    "host": "blam",
    "machine-id": "deadbeef"
  },
  "type": "UserLogin"
}

UserAction

Occurs when an authenticated sshd user does something (example: the user executes rizin).

Example:

{
  "component": "auditd",
  "loggedAt": "2023-03-17T13:37:38.126Z",
  "metadata": {
    "auditId": "67",
    "extra": {
      "action": "executed",
      "how": "bash",
      "object": {
        "primary": "/usr/local/bin/rizin",
        "type": "file"
      }
    }
  },
  "outcome": "failed",
  "source": {
    "extra": {
      "port": "56734"
    },
    "type": "IP",
    "value": "6.6.6.2"
  },
  "subjects": {
    "loggedAs": "core",
    "pid": "2868326",
    "userID": "user@foo.com"
  },
  "target": {
    "host": "the-best-computer",
    "machine-id": "deadbeef"
  },
  "type": "UserAction"
}

Installation and deployment

audito-maldito can be run as a standalone application (such as a systemd unit) or as a Kubernetes Daemonset. At Equinix Metal, we deploy the application in Kubernetes using a Helm chart. The chart relies on rsyslog, which is responsible for passing OpenSSH daemon logs and Linux audit logs to audito-maldito using named pipes. audito-maldito reads from these named pipes and then writes its audit events to a named pipe or file.

The following subsections discuss several installation and deployment methods.

Standalone (from source or as a container)

If you would like to run audito-maldito as a standalone application (i.e., outside of Kubernetes), you can build it from source or use a pre-built container image.

While not required, we recommend using rsyslog to pass OpenSSH logs and Linux audit logs into audito-maldito. An example rsyslog container image and rsyslog configuration can be found under:

• contrib/rsyslog

To build audito-maldito from source, execute the following command at the root of the repository:

go build

Pre-built container images for both audito-maldito and rsyslog can be found in GitHub's container registry:

• https://github.com/metal-toolbox/audito-maldito/pkgs/container/audito-maldito%2Faudito-maldito

Kubernetes

A Helm chart can be found in the equinixmetal-helm GitHub organization:

• https://github.com/equinixmetal-helm/audito-maldito

Configuration

The following subsections discuss audito-maldito's configuration.

Required data sources

audito-maldito reads input data from named pipes (FIFOs). It expects these data sources to be specified using the following arguments:

• -auditd-pipe-path - The file path to a named pipe that produces Linux auditd events (i.e., events from "/var/log/audit/audit.log")
• -sshd-pipe-path - The file path to a named pipe that produces OpenSSH sshd logs

Required files

The following files are required by audito-maldito to run:

• /etc/os-release - Many Linux distributions provide this file. It specifies details such as the distribution name and version
• /etc/machine-id - This file is managed by systemd. It contains an identifier for the computer

Output data

Audit events produced by audito-maldito are written to the file path specified by the -app-events-output argument. This file path can be a regular file or a named pipe.

Development

If you are a developer or looking to contribute, the following automation may come in handy.

Building a container image

To build the binary in a container, run:

make image

Note that you'll need to have Docker installed.

Documentation

Overview

audito-maldito is a daemon that monitors OpenSSH server logins and produces structured audit events describing what authenticated users did while logged in (e.g., what programs they executed).