Documentation

Agent Installation & Configuration

The SOCWarden agent is a lightweight agent binary that monitors your Linux servers for SSH access, file integrity changes, process execution, container events and more. All events are shipped to the same ingestor API as your application SDKs.

Quick Install

One command installs the binary, creates the config directory and sets up a systemd service.

Terminal

curl -sSL https://install.socwarden.com | sudo bash

The installer detects your architecture (amd64/arm64), downloads the latest release, places the binary at /usr/local/bin/socwarden-agent and enables the systemd service.

Manual Install

If you prefer manual setup, follow these steps.

Terminal

# 1. Download the latest release
curl -sSL -o /usr/local/bin/socwarden-agent \
  https://releases.socwarden.com/agent/latest/socwarden-agent-linux-amd64
chmod +x /usr/local/bin/socwarden-agent

# 2. Create config directory
sudo mkdir -p /etc/socwarden
sudo cp agent.yml.example /etc/socwarden/agent.yml

# 3. Edit the config
sudo nano /etc/socwarden/agent.yml

# 4. Create the systemd service
sudo tee /etc/systemd/system/socwarden-agent.service > /dev/null << 'EOF'
[Unit]
Description=SOCWarden Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/socwarden-agent -config /etc/socwarden/agent.yml
Restart=always
RestartSec=5
User=root

[Install]
WantedBy=multi-user.target
EOF

# 5. Enable and start
sudo systemctl daemon-reload
sudo systemctl enable socwarden-agent
sudo systemctl start socwarden-agent

# 6. Verify
sudo systemctl status socwarden-agent
sudo journalctl -u socwarden-agent -f

Configuration

Full agent.yml reference. The file lives at /etc/socwarden/agent.yml.

/etc/socwarden/agent.yml

# API key from your SOCWarden dashboard (required).
api_key: "sw_live_xxxxxxxxxxxxxxxxxxxx"

# Ingestor endpoint URL (required).
endpoint: "https://ingest.socwarden.com"

# Unique identifier for this server (required).
# Use a slug like "web-prod-01" or a UUID.
server_id: "web-prod-01"

# Files to monitor for integrity changes.
# Leave empty to disable file integrity monitoring.
watch_paths:
  - /etc/passwd
  - /etc/shadow
  - /etc/ssh/sshd_config
  - /etc/sudoers
  - /etc/crontab

# How often to send heartbeats (default: 60s).
heartbeat_interval: 60s

# Local buffer for offline event storage.
buffer_path: /var/lib/socwarden/buffer.db

# Brute-force detection: N failures within the sliding
# window triggers an alert.
brute_force_window: 5m
brute_force_max: 5

Configuration Options

Key	Default	Description
api_key	(required)	Bearer token for the ingestor API
endpoint	(required)	Ingestor base URL
server_id	(required)	Unique identifier for this server
watch_paths	[]	File paths to monitor for integrity changes
heartbeat_interval	60s	Interval between heartbeat pings
buffer_path	/var/lib/socwarden/buffer.db	Buffer for offline events
brute_force_window	5m	Sliding window for brute-force detection
brute_force_max	5	Max failures before brute-force alert
auto_update.enabled	true	Enable automatic agent updates
auto_update.interval	6h	How often to check for updates
auto_update.channel	stable	Release channel: stable or beta
auto_update.pinned_version	(optional)	Pin to a specific version, skipping auto-updates

Monitored Events

The agent monitors 28 event types across 11 categories. All events follow the server.* namespace convention.

SSH4 events

server.ssh.login.successSuccessful SSH authentication

server.ssh.login.failureFailed SSH authentication attempt

server.ssh.key_acceptedPublic key authentication accepted

server.ssh.brute_forceBrute-force detected (N failures in window)

File Integrity3 events

server.file.modifiedWatched file content changed

server.file.deletedWatched file was deleted

server.file.permission_changedWatched file permissions changed

Process2 events

server.process.executedNew process started

server.process.suspiciousSuspicious binary detected (cryptominers, reverse shells)

User4 events

server.user.createdNew user account created

server.user.deletedUser account deleted

server.user.sudoSudo command executed

server.user.suUser switch (su) executed

Service2 events

server.service.startedSystemd service started

server.service.stoppedSystemd service stopped

Package2 events

server.package.installedPackage installed via apt/yum

server.package.removedPackage removed

Cron2 events

server.cron.addedNew cron job added

server.cron.modifiedExisting cron job modified

Firewall2 events

server.firewall.rule_addedFirewall rule added (iptables/nftables)

server.firewall.rule_removedFirewall rule removed

Network2 events

server.network.connectionNew outbound connection detected

server.network.port_scan_detectedPort scan pattern detected

Container3 events

server.container.startedDocker container started

server.container.stoppedDocker container stopped

server.container.escape_attemptContainer escape attempt detected

Log Integrity2 events

server.log.tamperedLog file tampered or truncated

server.log.clearedLog file cleared

File Integrity Monitoring

The watch_paths config option specifies which files to monitor. The agent computes SHA-256 hashes on startup and checks for changes on every heartbeat cycle.

agent.yml

watch_paths:
  # Critical system files
  - /etc/passwd
  - /etc/shadow
  - /etc/group

  # SSH configuration
  - /etc/ssh/sshd_config
  - /etc/ssh/ssh_config

  # Privilege escalation
  - /etc/sudoers

  # Scheduled tasks
  - /etc/crontab
  - /etc/cron.d

  # Application configs
  - /var/www/app/.env
  - /var/www/app/config/auth.php

When a watched file is modified, deleted, or has its permissions changed, the agent immediately sends an event to SOCWarden. Each event includes the old and new hash, file owner, permissions, and modification timestamp.

Troubleshooting

Agent fails to start: "permission denied"

The agent needs root access to read /var/log/auth.log, /etc/shadow, and monitor Docker. Run as root or use the systemd service (which runs as root by default).

No SSH events appearing

Verify the auth log path. The agent reads from /var/log/auth.log (Debian/Ubuntu) or /var/log/secure (RHEL/CentOS). Check that the log file exists and is not empty.

Events are delayed or missing

Check the buffer at /var/lib/socwarden/buffer.db. If the ingestor is unreachable, events are buffered locally and sent when connectivity is restored. Verify your endpoint URL and API key.

High memory usage

If monitoring many watch_paths, reduce the list to critical files only. The agent itself uses minimal memory (~15MB) but file hashing on large directories can spike temporarily.

Docker events not appearing

Ensure the Docker socket is accessible at /var/run/docker.sock. The agent needs read access to the Docker API. Docker event monitoring is available on Pro and Business plans.

Checking agent logs

Use journalctl -u socwarden-agent -f to tail the agent logs in real time. The agent logs all event submissions, errors, and heartbeat status.

Offline Buffer

The agent stores events in a local database when the ingestor is unreachable. Events are retried with exponential backoff. The buffer path defaults to /var/lib/socwarden/buffer.db and can be changed via the buffer_path config option. On reconnection, buffered events are flushed in order with their original timestamps preserved.

← PreviousSDK Guides Next →Forensic Drawer