auditmon

README

Auditmon

A simple host it yourself audit trail system

Anatomy of an Event

Auditmon events look like this

{
    "event_time": "2006-01-02T15:04:05Z07:00",
    "event_name": "loginSuccessful",
    "username": "sample_user",
    "resource": "my_resource",
    "event_source": "my_application",
    "source_ip_address": "127.0.0.1",
    "event_id": "aaaa-bbbb-cccc-eeee-dddd-ffff",
    "request_id": "aaaa-bbbb-cccc-eeee-dddd-ffff",
    "read_only": false,
    "event_data": {"any": "extraFields", "count": 123}
}

When creating an event the required fields are:

• username
• event_name

Optional fields are:

• event_time (Set to the current time if one is not provided)
• source_ip_address (Set to "-" if empty)
• read_only (Set to false by default)
• event_data (Set to nil if empty)
• request_id (Set to nil if empty)
• resource (Name of resource event relates to, set to nil if empty)

Generated fields:

• event_id (Generated by Auditmon to track this event)
• event_source (Set to name of API key that requested the event be inserted)

Field Tips

• Standardize across your event emitting applications on standard event_name keywords
• Providing a request ID makes it easy to trace a request back through application and network logs
• Keep interesting and helpful data in event_data, while you cannot query for this data it can be helpful when performing an audit

Configuring Auditmon

Auditmon is configured through a configuration file as well as environment variables. A sample configuration file is available in config/auditmon.yaml

By default, Auditmon will look for a configuration file at config/auditmon.yaml, you may specify a different path with -c path/to/config.yaml

Each section of the configuration file can be overridden with an environment variable like the below

database:
  username: postgres
 
export AUDITMON_DATABASE_USERNAME="notPostgres"

The pattern to follow for environment variables is AUDITMON_$CONFIG_SECTION_CONFIG_ITEM

Developing Locally

Auditmon can be run without any modification locally by running

go run cmd/server/main.go

If you would like to use postgres instead of sqlite3 you can start a postgres server using the docker command below and have Auditmon connect to it

docker run -it -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=auditmon -p 5432:5432 docker.io/postgres:14
AUDITMON_DATABASE_BACKEND=postgres go run cmd/server/main.go