CLI Mode#

The primary way to use APHIDS — run security scans from YAML configuration files.

Basic Usage#

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

This reads your scan definitions from options.yaml, connects to Hive using config.yaml, and executes each module sequentially in the containerized runtime.

Command Reference#

Scan Configuration#

Flag	Long Form	Description
`-o`	`--options FILE`	Options YAML file (required for CLI mode)
`-c`	`--config FILE`	Config YAML file for Hive connectivity
`-sp`	`--static-path DIR`	Mount a directory for static analysis tools
`-i`	`--image IMAGE`	Custom container image
	`--runtime RUNTIME`	Container runtime: `docker`, `podman`, `nerdctl`
	`--unattended`	Auto-approve all prompts (CI/CD)
`-d`	`--debug`	Enable debug logging

Online Mode (Hive)#

Flag	Long Form	Description
`-k`	`--api-key KEY`	Hive API key (prefer `APHIDS_API_KEY` env var)
`-u`	`--api-url URL`	Hive API base URL
`-uw`	`--wsapi-url URL`	WebSocket URL
`-e`	`--engagement ID`	Associate scans with an engagement
`-n`	`--network NAME`	Network name (default: `public`)
`-r`	`--runbook ID`	Execute a Hive runbook by ID
`-at`	`--attack-tree ID`	Execute an attack tree by ID
`-ats`	`--attack-tree-scope SCOPE`	Scope restrictions for attack trees
`-se`	`--scan-execution ID`	Execute a pre-configured scan execution

Targeting#

Flag	Long Form	Description
	`--target-url URL`	Target URL (e.g., `https://example.com`)
	`--target-host HOST`	Target host, IP, or CIDR
	`--target-domain DOMAIN`	Target domain for subdomain enumeration
	`--target-dir DIR`	Local directory for SAST/secret scanning

Modes#

Flag	Description
`--mcp`	Start as MCP server
`--agent`	Start as persistent agent
`--resume ID`	Resume an interrupted scan

Inline JSON#

Flag	Description
`-jo`	Options as inline JSON
`-jc`	Config as inline JSON

Examples#

CLI Examples#

# Offline scan — no config needed
aphids-cli -o options.yaml

# Online scan — env var for auth (preferred, no config.yaml needed)
export APHIDS_API_KEY="your-key"
aphids-cli -o options.yaml

# Online scan — explicit flags
aphids-cli -o options.yaml -k "your-key" -u "https://api.hive.darksidesecurity.io/"

# Static analysis on a local project
aphids-cli -o options.yaml -sp /path/to/your/code

# Execute a Hive runbook
aphids-cli -r RUNBOOK_UUID --target-url https://example.com

# Execute an attack tree with scope
aphids-cli -at ATTACK_TREE_UUID \
  --target-domain example.com \
  --attack-tree-scope "*.example.com,10.0.0.0/24"

# Resume an interrupted scan
aphids-cli --resume EXECUTION_ID -o options.yaml

# Unattended mode for CI/CD
aphids-cli -o options.yaml --unattended

# Custom container image
aphids-cli -o options.yaml -i my-aphids:latest

Docker Examples#

When running the container directly, use -e for environment variables and -v for volume mounts. No config.yaml is needed — just set APHIDS_API_KEY.

Offline scanOnline scan (env vars)SAST with source codeFully inline (no files)

docker run --rm \
  -v $(pwd)/options.yaml:/output/options.yaml:ro \
  -v $(pwd)/output:/output \
  ghcr.io/darksidesecurity/aphids:latest \
  -o options.yaml

docker run --rm \
  -e APHIDS_API_KEY="your-key" \
  -v $(pwd)/options.yaml:/output/options.yaml:ro \
  -v $(pwd)/output:/output \
  ghcr.io/darksidesecurity/aphids:latest \
  -o options.yaml

docker run --rm \
  -e APHIDS_API_KEY="your-key" \
  -v $(pwd)/options.yaml:/output/options.yaml:ro \
  -v $(pwd)/output:/output \
  -v /path/to/source:/workspace:ro \
  ghcr.io/darksidesecurity/aphids:latest \
  -o options.yaml

docker run --rm \
  -e APHIDS_API_KEY="your-key" \
  -v $(pwd)/output:/output \
  ghcr.io/darksidesecurity/aphids:latest \
  -jo '{"configuration":{"online":"enabled"},"modules":{"nmap-scan":{"module":"nmap","target":"10.0.0.1"}}}'

Volume Mount Reference#

Host Path	Container Path	Mode	Purpose
`options.yaml`	`/output/options.yaml`	`:ro`	Scan configuration
`./output/`	`/output/`	read-write	Results, checkpoints
`/path/to/code/`	`/workspace/`	`:ro`	Source code for SAST

Always mount /output/

Without an output volume mount, scan results are lost when the container exits.

Signal Handling#

APHIDS supports keyboard signals for scan control:

Signal	Shortcut	Effect
SIGINT	`Ctrl+C`	Graceful shutdown — finishes current tool, uploads results
SIGTSTP	`Ctrl+Z`	Pause/resume — saves checkpoint for later resumption
SIGQUIT	`Ctrl+\`	Global abort — immediate stop

Pause and Resume#

Press Ctrl+Z during a scan to pause. APHIDS saves a checkpoint with completed modules. Resume later:

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

Only remaining modules will execute.

Exit Codes#

Code	Meaning
`0`	Success — all modules completed
`1`	Error or findings above threshold
`2`	Configuration error