Skip to content

Agent Mode#

Deploy persistent APHIDS agents that register with Hive and execute scans on demand via WebSocket.

Overview#

Agent mode turns APHIDS into a long-running daemon that:

  1. Connects to Hive via WebSocket (WSS)
  2. Registers itself with a name, hostname, and capabilities
  3. Waits for scan commands dispatched from the Hive UI
  4. Executes scans using up to 3 concurrent threads
  5. Uploads results directly to Hive
  6. Maintains connection with heartbeats and auto-reconnect

Quick Start#

# Basic agent
aphids-cli --agent --agent-name prod-scanner-01

# With explicit API key
aphids-cli --agent \
  --agent-name prod-scanner-01 \
  --api-key YOUR_HIVE_API_KEY

# CI/CD agent that exits after 5 minutes idle
aphids-cli --agent \
  --agent-name ci-scanner \
  --exit-on-idle 300

Configuration#

Flag Environment Variable Description
--agent — Enable agent mode
--agent-name NAME — Friendly agent identifier
--api-key KEY APHIDS_API_KEY Hive API key
--ws-url URL APHIDS_WS_URL WebSocket URL override
--exit-on-idle SECONDS — Auto-exit after N seconds with no scans

How It Works#

Registration#

When started, the agent sends a registration message to Hive:

Agent "prod-scanner-01" registered
  Hostname: scanner.internal
  Platform: linux
  Tools: 40 available

The agent appears in the Hive UI under Attack Platform, where operators can dispatch scans to it.

Heartbeat#

The agent sends a heartbeat every 30 seconds to maintain the WebSocket connection. If the connection drops, it auto-reconnects with exponential backoff:

  • Base delay: 1 second
  • Max delay: 60 seconds
  • Max attempts: 10

Concurrency#

Agents support up to 3 concurrent scan threads. Multiple scan jobs can execute simultaneously, each with independent timeout tracking.

Graceful Shutdown#

Press Ctrl+C to initiate graceful shutdown:

  1. Stops accepting new scan jobs
  2. Waits for running scans to complete
  3. Uploads final results
  4. Disconnects from WebSocket

Deployment Patterns#

Persistent Server Agent#

Run on a dedicated scanning server:

# Using systemd, screen, tmux, etc.
aphids-cli --agent \
  --agent-name datacenter-scanner \
  --api-key $APHIDS_API_KEY

CI/CD Pipeline Agent#

Spin up an agent for pipeline duration:

# Exit after 5 minutes idle
aphids-cli --agent \
  --agent-name ci-pipeline-$CI_JOB_ID \
  --exit-on-idle 300

Docker Agent#

docker run -d --name aphids-agent \
  -e APHIDS_API_KEY="your-key" \
  ghcr.io/darksidesecurity/aphids:latest \
  --agent --agent-name docker-scanner-01

Multiple Agents#

Deploy multiple agents for parallel scanning capacity:

# Scanner fleet
for i in 1 2 3; do
  aphids-cli --agent --agent-name scanner-$i &
done

Dispatching Scans#

Scans are dispatched to agents from the Hive UI:

  1. Navigate to Attack Platform > Scan Executions
  2. Create or select an execution
  3. Choose the target agent
  4. The agent receives the scan command via WebSocket and begins execution

Results appear in real-time in the Hive dashboard.

Resuming Interrupted Scans#

If an agent is interrupted mid-scan, resume with:

aphids-cli --resume EXECUTION_ID -o options.yaml -c config.yaml

Only remaining modules will execute. Completed modules are skipped.