commit	30386f82fd0a29ac7d74f186948c7e413166e7fb	[log] [tgz]
author	David Ostrovsky <david@ostrovsky.org>	Fri Apr 09 09:50:39 2021 +0200
committer	David Ostrovsky <david@ostrovsky.org>	Fri Apr 09 09:52:14 2021 +0200
tree	bf65a190c35dda986fe427590850e087f52624a7
parent	8c7bccbd973ee287e18cd2d467f3161d90d02782 [diff]

tree: bf65a190c35dda986fe427590850e087f52624a7

README.md

Audit plugin for Gerrit

Plug into the Gerrit Code Review audit extension and format and forward all the events to an SLF4J appender, the same logging system used internally for the generation of all logs..

How to configure logging?

Audit events are by default stored into the Gerrit error_log under the appender com.googlesource.gerrit.plugins.auditsl4j.LoggerAudit. However, it is possible to generate a separate audit file and having the audit records formatted into CSV or JSON.

For more details, see the configuration guide in the plugin.

Why auditing events on Gerrit?

Audits leave an immutable trace of what happened on Gerrit and allows to answer the question “who did what and when?”.

When aggregated by time, project or user, can give an overall figure on how much the system is utilized and allow to make a better planning of the hardware resources allocation and planning the downtimes to reduce the impact on the people and projects.

Is this a duplicate of Gerrit stream events?

Gerrit stream events are triggered on Git-related operations and reviews, but do not cover most of the actions that happen on Gerrit and do not include all the system information that is typically needed for audit-trail purposes.

Furthermore, stream events are designed to be consumed in near-real-time while audits, are typically archived and consumed off-line.

What the audit events look like?

The format of Gerrit audits changes across the different releases because they reflect the internal representation of the Java objects in memory.

They share an overall basic structure:

type: Audit java class
event: Audit event
- session_id: unique identifier of the user's session
- who: user that generated the event
  - account_id: user unique id
  - access_path: how the user accessed the system
- when: epoch time-stamp of the event
- what: action performed
- result: result of the action
- time_at_start: epoch time-stamp of when the action started
- elapsed: how long the action lasted (msec)
- uuid: audit event UUID

Example audit of a login from a Git client over SSH:

{
  "type": "SshAuditEvent",
  "event": {
    "session_id": "0261c43e",
    "who": {
      "account_id": {
        "id": 1011575
      },
      "access_path": "GIT",
      "last_login_external_id_property_key": {}
    },
    "when": 1539561891898,
    "what": "LOGOUT",
    "params": {},
    "result": "0",
    "time_at_start": 1539561891898,
    "elapsed": 0,
    "uuid": {
      "uuid": "audit:f135cb10-59be-4087-a9e0-571680b93a59"
    }
  }
}

Example audit of a Gerrit changes query over SSH:

{
  "type": "SshAuditEvent",
  "event": {
    "session_id": "22688824",
    "who": {
      "account_id": {
        "id": 1011203
      },
      "access_path": "SSH_COMMAND",
      "last_login_external_id_property_key": {}
    },
    "when": 1539561891503,
    "what": "gerrit.query.--format.json.--current-patch-set.project:mycompany/myproject commit:798b22fcf3614e8575e0ef23019a9706b8acebcc NOT is:draft",
    "params": {},
    "result": "0",
    "time_at_start": 1539561891503,
    "elapsed": 3,
    "uuid": {
      "uuid": "audit:171a9b6f-327a-40a2-9b66-c47a39eba68c"
    }
  }
}

Import old logs

The makes available an ssh command to transform http_logs and ssh_logs into Audit Logs:

ssh -p 29418 admin@localhost audit-sl4j transform --from 2019-01-23 --until 2019-01-24