Gwyliwr

A multi-threaded Python service that monitors log streams from the Laurel auditd plugin, filters for specific events (EXECVE), and publishes JSON payloads via a secure ZeroMQ (REQ/REP) connection using CURVE encryption to a server endpoint. Designed to be used with Laurel plugin for auditd.

Prerequisites

• Python 3.x
• PostgreSQL Server

Security Considerations

This script does not yet implement authentication. Whilst content is encrypted, an attacker could generate their own key pair to communicate with the server. Consider additional security measures such as firewall rules.

The encryption method here may not be safe against future quantum decryption methods. Consider whether this fits your threat model, or whether you need to tunnel traffic over a quantum safe VPN layer.

Environment Variables

Environment Variable	Example Value	Required for	Description
ARCHIVE_THRESHOLD_MINUTES	1440	Server	The age of an audit event in minutes before the archive.py script considers it for archiving (moving from audit_event to audit_event_archive table)
METRICS_PORT	8080	Server	The port to run the server web service which publishes metrics data relating to queues (e.g http://localhost:8080/metrics)
SERVER_LOG_FILE_PATH	/home/user/server.log	Server	The log path for the server.py/archive.py script
ZMQ_LISTEN_URL	tcp://127.0.0.1:5555	Server	The URL & port for the server.py to listen on for auditd events
ZMQ_SERVER_SEC_KEY	keys/server.key_secret	Server	The file path to the CURVE secret key for the server - generate keys with https://git.server.wales/thomas/ZMQ-Key-Management
DB_NAME	Gwyliwr	Server	The name of the database to publish audit events
DB_USER	Gwyliwr	Server	The name of the database user for the database
DB_PASS	Set your own	Server	The password for the database
DB_HOST	localhost	Server	The PostgreSQL server address
DB_PORT	5432	Server	The port of the PostgreSQL server
HOSTNAME	example.server.com	Publisher	The hostname of the publisher host to include in audit event data
QUEUE_LIMIT	1000000	Publisher	The queue limit for unpublished audit events (WARNING: Setting this too low will cause backpressure on the auditd service and likely cause high server load)
PUBLISHER_LOG_FILE_PATH	/home/user/publisher.log	Publisher	The file path for the publish.py script
ZMQ_CLIENT_PUB_KEY	keys/client.key	Publisher	The file path to the CURVE public key for the client - generate keys with https://git.server.wales/thomas/ZMQ-Key-Management
ZMQ_CLIENT_SEC_KEY	keys/client.key_secret	Publisher	The file path to the CURVE secret key for the client - generate keys with https://git.server.wales/thomas/ZMQ-Key-Management
ZMQ_PUBLISH_URL	tcp://127.0.0.1:5555	Publisher	The URL & port where publish.py will send events
ZMQ_SERVER_PUB_KEY	keys/server.key	Server & Publisher	The file path to the CURVE public key for the server - generate keys with https://git.server.wales/thomas/ZMQ-Key-Management

Installation

1. Clone the repository.
2. Install required dependencies:

   pip install -r requirements.txt
   

Laurel/Auditd notes

Laurel cannot pipe directly into this script. You will need some wrapper script. Example:

#!/bin/bash
exec /home/laurel/.venv/bin/python /home/laurel/publish.py

Once you have the wrapper script setup to pipe into publish.py, set the config line in laurel config.toml file. Example:

file = "| /home/laurel/wrapper.sh"