System Audit Modules ​

This document provides an overview of eCapture's system audit modules, which enable security monitoring of shell commands and database queries without requiring code modifications. Unlike the TLS/SSL capture modules covered in TLS/SSL Capture Modules, these modules focus on auditing user actions and SQL queries rather than network traffic.

For detailed implementation of shell auditing, see Shell Command Auditing. For database query auditing details, see Database Query Auditing.

Purpose and Scope ​

System audit modules use eBPF uprobe technology to intercept function calls in user-space binaries, capturing command-line input/output and SQL query strings. These modules serve security audit, compliance monitoring, and forensic analysis use cases.

Supported Audit Targets:

• Shell Commands: bash (via readline library), zsh (via zle library)
• Database Queries: MySQL/MariaDB (5.6, 5.7, 8.0), PostgreSQL (10+)

All audit modules operate independently of TLS/SSL modules and do not require network interface access or packet capture capabilities.

Sources: README.md:152-161, cli/cmd/bash.go:1-56, cli/cmd/zsh.go:1-58, cli/cmd/mysqld.go:1-50, cli/cmd/postgres.go:1-46

Module Overview ​

The following table summarizes the four system audit modules available in eCapture:

All modules inherit from the IModule interface and follow the standard module lifecycle (Init → Run → Close) described in Module System and Lifecycle.

Sources: README.md:152-161, cli/cmd/bash.go:24-38, cli/cmd/zsh.go:27-41, cli/cmd/mysqld.go:27-42, cli/cmd/postgres.go:27-40

Architecture Integration ​

System audit modules integrate with eCapture's core architecture as specialized implementations of the IModule interface, focusing on uprobe-based event capture without requiring network components.

Audit Module Architecture ​

Key Differences from TLS Modules:

• No network interface (-i) parameter required
• No pcap/keylog output modes
• No Traffic Control (TC) hooks or packet capture
• Simpler event flow: uprobe → decode → log (no protocol parsing)

Sources: cli/cmd/bash.go:1-56, cli/cmd/zsh.go:1-58, cli/cmd/mysqld.go:1-50, cli/cmd/postgres.go:1-46

Command-Line Interface ​

Each audit module is invoked as a subcommand of the ecapture binary with module-specific configuration flags.

Shell Command Audit Commands ​

Bash Module ​

# Basic usage - auto-detect bash binary
sudo ecapture bash

# Specify bash binary path
sudo ecapture bash --bash=/bin/bash

# Specify readline library path
sudo ecapture bash --readlineso=/lib/x86_64-linux-gnu/libreadline.so.8

# Filter by error number (show only failed commands)
sudo ecapture bash --errnumber=1

# Combined flags with logging
sudo ecapture bash -l bash_audit.log --pid=1234

Configuration Structure: BashConfig cli/cmd/bash.go:24

• Bashpath: Path to bash binary (default: auto-detected from $SHELL)
• Readline: Path to readline.so library (default: auto-detected)
• ErrNo: Filter commands by exit code (default: BashErrnoDefault)

Zsh Module ​

# Basic usage - auto-detect zsh binary
sudo ecapture zsh

# Specify zsh binary path
sudo ecapture zsh --zsh=/bin/zsh

# Filter by error number
sudo ecapture zsh --errnumber=127

Configuration Structure: ZshConfig cli/cmd/zsh.go:27

• Zshpath: Path to zsh binary (default: auto-detected from $SHELL)
• ErrNo: Filter commands by exit code (default: ZshErrnoDefault)

Sources: cli/cmd/bash.go:24-56, cli/cmd/zsh.go:27-58

Database Query Audit Commands ​

MySQL/MariaDB Module ​

# Basic usage - default mysqld path
sudo ecapture mysqld

# Specify mysqld binary (MySQL)
sudo ecapture mysqld --mysqld=/usr/sbin/mysqld

# Specify mariadbd binary (MariaDB)
sudo ecapture mysqld --mysqld=/usr/sbin/mariadbd

# Hook specific function by name
sudo ecapture mysqld --funcname=dispatch_command

# Hook by offset (advanced usage)
sudo ecapture mysqld --offset=0x710410

# Combined with logging
sudo ecapture mysqld -l mysql_queries.log --pid=3306

Configuration Structure: MysqldConfig cli/cmd/mysqld.go:27

• Mysqldpath: Path to mysqld/mariadbd binary (default: /usr/sbin/mariadbd)
• FuncName: Specific function name to hook (optional)
• Offset: Memory offset for uprobe attachment (optional, advanced)

Supported Versions: MySQL 5.6/5.7/8.0, MariaDB 10.5+

PostgreSQL Module ​

# Basic usage - default postgres path
sudo ecapture postgres

# Specify postgres binary path
sudo ecapture postgres --postgres=/usr/lib/postgresql/14/bin/postgres

# Hook specific function
sudo ecapture postgres --funcname=exec_simple_query

# Combined with logging
sudo ecapture postgres -l postgres_queries.log --pid=5432

Configuration Structure: PostgresConfig cli/cmd/postgres.go:27

• PostgresPath: Path to postgres binary (default: /usr/bin/postgres)
• FuncName: Specific function name to hook (optional)

Supported Versions: PostgreSQL 10+

Sources: cli/cmd/mysqld.go:27-50, cli/cmd/postgres.go:27-46

Module Execution Flow ​

All audit modules follow the standard eCapture module lifecycle with simplified event processing compared to TLS modules.

Audit Module Lifecycle ​

Key Differences from TLS Modules:

1. No network interface binding or TC classifier setup
2. No EventProcessor/IWorker pool (simpler event flow)
3. No protocol parsing (IParser not used)
4. Direct event decode → log pipeline
5. No master key extraction or pcap file generation

Sources: cli/cmd/bash.go:52-55, cli/cmd/mysqld.go:46-49

Common Configuration Parameters ​

All audit modules support the standard global flags inherited from the root command, in addition to their module-specific flags.

Global Flags (Inherited) ​

Module Detection Logic ​

Each audit module implements binary/library detection logic:

1. Bash Module cli/cmd/bash.go:36-37

   • Auto-detects bash from $SHELL environment variable
   • Auto-locates readline.so from bash's linked libraries

2. Zsh Module cli/cmd/zsh.go:39

   • Auto-detects zsh from $SHELL environment variable

3. MySQL Module cli/cmd/mysqld.go:40

   • Default path: /usr/sbin/mariadbd
   • Can specify /usr/sbin/mysqld for MySQL installations

4. PostgreSQL Module cli/cmd/postgres.go:37

   • Default path: /usr/bin/postgres
   • Version-agnostic detection (works with PG 10+)

Sources: cli/cmd/bash.go:36-37, cli/cmd/zsh.go:39, cli/cmd/mysqld.go:40, cli/cmd/postgres.go:37

Use Cases and Examples ​

Security Audit Scenarios ​

Command History Auditing ​

Scenario: Monitor all bash commands executed by a specific user without modifying shell configuration or requiring user cooperation.

# Monitor all commands from user ID 1000
sudo ecapture bash --uid=1000 -l /var/log/audit/bash_commands.log

# Monitor specific bash process
sudo ecapture bash --pid=12345 -l /var/log/audit/process_12345.log

# Show only failed commands (non-zero exit codes)
sudo ecapture bash --errnumber=1

Output Format: Captures command text, PID, UID, timestamp, and exit code.

Database Query Auditing ​

Scenario: Audit all SQL queries executed on a production MySQL server for compliance monitoring.

# Monitor all MySQL queries
sudo ecapture mysqld --mysqld=/usr/sbin/mysqld -l /var/log/audit/mysql_queries.log

# Monitor specific MySQL instance by PID
sudo ecapture mysqld --pid=3306 -l /var/log/audit/mysql_3306.log

Output Format: Captures SQL query strings with connection metadata (PID, timestamp).

Forensic Analysis ​

Scenario: Investigate suspicious activity by capturing all shell commands and database queries during an incident response.

# Terminal 1: Monitor bash commands
sudo ecapture bash -l /tmp/forensics/bash.log

# Terminal 2: Monitor PostgreSQL queries
sudo ecapture postgres -l /tmp/forensics/postgres.log

# Terminal 3: Monitor zsh commands
sudo ecapture zsh -l /tmp/forensics/zsh.log

Sources: README.md:152-161, cli/cmd/bash.go:30-32, cli/cmd/mysqld.go:32-36

Comparison with TLS Modules ​

The following table highlights architectural differences between audit modules and TLS capture modules:

Audit modules are significantly simpler than TLS modules, as they do not require:

• Network packet reassembly
• Connection tracking (4-tuple mapping)
• Protocol state machines
• Master secret extraction
• PCAP file generation with DSB blocks

For TLS module details, see TLS/SSL Capture Modules.

Sources: README.md:38-43, README.md:152-161

Module Registration ​

All audit modules are registered in the CLI command structure through the init() functions in their respective command files:

Command Registration: cli/cmd/bash.go:35-55, cli/cmd/zsh.go:38-52, cli/cmd/mysqld.go:39-44, cli/cmd/postgres.go:36-40

Module Execution: All commands invoke runModule(moduleName, config) which:

1. Calls setModConfig(globalConf, moduleConfig)
2. Instantiates the module implementation
3. Executes the standard lifecycle: Init() → Run() → Close()

For detailed module lifecycle information, see Module System and Lifecycle.

Sources: cli/cmd/bash.go:52-55, cli/cmd/zsh.go:54-57, cli/cmd/mysqld.go:46-49, cli/cmd/postgres.go:42-45

Build Configuration ​

System audit modules are conditionally compiled based on build tags:

• Bash Module: Available on all platforms
• Zsh Module: Excluded on Android (!androidgki build tag) cli/cmd/zsh.go:1-2
• MySQL Module: Excluded on Android (!androidgki build tag) cli/cmd/mysqld.go:1-2
• PostgreSQL Module: Excluded on Android (!androidgki build tag) cli/cmd/postgres.go:1-2

This conditional compilation reduces binary size for Android deployments where these audit capabilities are typically not needed.

For build system details, see Build System.

Sources: cli/cmd/zsh.go:1-2, cli/cmd/mysqld.go:1-2, cli/cmd/postgres.go:1-2