Audit Trail Scope

Background and reasoning behind design decisions in splam. This page won’t tell you how to do something. See the How-To Guides for that.

What the audit trail does and doesn’t capture

The audit trail (audit_log.jsonl) records every Start/Stop/Restart attempted through this app: timestamp, user, service, action, reason, and result. Attempts rejected by the app (an unknown service, a missing reason, or an auditor account attempting an action) are recorded too, with a rejected: result, so the trail shows what was tried and not only what succeeded. Login and logout attempts are recorded the same way: failed logins carry the username that was submitted, lockouts are recorded once an account has failed too many times, and a session ended by the idle timeout is recorded as a logout with the result idle timeout.

The boundary is the app itself, not the machine. Everything that reaches audit_log.jsonl passed through a form in this app; everything that didn’t, didn’t.

%%{init: {'theme': 'dark', 'themeVariables': { 'fontFamily': 'monospace', "fontSize":"20px", "darkMode":true}}}%%

flowchart LR
    subgraph Cap["<strong>Captured</strong>"]
        Svc["Start / Stop / Restart<br>(rejected or not)"]
        Login["login attempts<br>success, failure, lockout"]
        Out["logout<br>deliberate or idle timeout"]
    end

    Log[("audit_log.jsonl")]

    subgraph Not["<strong>Not captured</strong>"]
        Shell["systemctl from a shell,<br>other tools"]
        Conf["config edits: crontab,<br>sshd_config, firewall rules"]
    end

    Svc ==> Log
    Login ==> Log
    Out ==> Log
    Shell --x Log
    Conf --x Log

    style Svc fill:#4CBB9D,color:#FFFFFF,rx:5,ry:5
    style Login fill:#4CBB9D,color:#FFFFFF,rx:5,ry:5
    style Out fill:#4CBB9D,color:#FFFFFF,rx:5,ry:5
    style Log fill:#4CBB9D,color:#FFFFFF,rx:5,ry:5
    style Shell fill:#FFFFFF,color:#000000,stroke:#333,stroke-width:1px,rx:5,ry:5
    style Conf fill:#FFFFFF,color:#000000,stroke:#333,stroke-width:1px,rx:5,ry:5
    style Cap fill:#FFFFFF,color:#000000,stroke:#333,stroke-width:1px,rx:10,ry:10
    style Not fill:#FFFFFF,color:#000000,stroke:#333,stroke-width:1px,rx:10,ry:10

Of the two blocked paths, configuration changes are the one worth naming twice. Several SERVICE_INFO entries call it out explicitly, because it’s the gap admins are most likely to assume is covered when it isn’t.

Treat it as a record of this app’s actions, not a general-purpose system audit log. That’s what auditd and centralized syslog forwarding are for (see the auditd.service and rsyslog.service entries on the Tasks tab).