Skip to content

Configuration#

APHIDS uses options.yaml for scan definitions and optionally config.yaml for Hive platform connectivity. The preferred method is to use environment variables instead of a config file.

Environment Variables (Preferred)#

Environment variables are the recommended way to configure APHIDS, especially for CI/CD and container deployments. When set, no config.yaml is needed — APHIDS builds the configuration automatically.

Variable Purpose Default
APHIDS_API_KEY Hive API key (required for online mode) —
APHIDS_API_URL Hive REST API base URL https://api.hive.darksidesecurity.io/
APHIDS_WS_URL WebSocket URL for agents and notifications Auto-derived from APHIDS_API_URL
APHIDS_CONTAINER_RUNTIME Container runtime (docker, podman, nerdctl) Auto-detect
APHIDS_TOOL_TIMEOUT Default per-tool timeout in seconds 1800 (30 min)
APHIDS_DEBUG Enable debug logging (true/false) false
APHIDS_SCAN_GROUP Scan group name (MCP mode) Auto-generated

CLI without config.yaml#

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

# Online scan — just set your API key
export APHIDS_API_KEY="your-key-here"
aphids-cli -o options.yaml

# Override the API URL if needed
export APHIDS_API_KEY="your-key-here"
export APHIDS_API_URL="https://api.hive.darksidesecurity.io/"
aphids-cli -o options.yaml

Docker without config.yaml#

Pass environment variables with -e flags — no config file mounting required:

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

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

No config.yaml, no problem

When APHIDS_API_KEY is set, APHIDS automatically builds the Hive configuration with sensible defaults. You only need config.yaml if you need to customize endpoint paths.

config.yaml (Optional)#

For advanced configurations or when you need custom endpoint paths, you can use a config file. Environment variables always take precedence over config file values.

authorization:
  apiKey: YOUR_HIVE_API_KEY

baseUrl: https://api.hive.darksidesecurity.io/
baseWsUrl: wss://ws.continuity.hive.darksidesecurity.io/

endpoints:
  valis:
    path: valis/
  continuity:
    path: continuity/
  valis-cli:
    path: executions-cli/

debug: false

Fields#

Field Env Var Override Description
authorization.apiKey APHIDS_API_KEY Hive API key
baseUrl APHIDS_API_URL Hive REST API base URL
baseWsUrl APHIDS_WS_URL WebSocket URL for agent mode
endpoints.* — Custom endpoint paths (rarely needed)
debug APHIDS_DEBUG Enable debug logging

API Key Security

Never commit API keys to source control. Always use the APHIDS_API_KEY environment variable.

Inline JSON Configuration#

For one-off runs or scripting, pass configuration as inline JSON — no files needed:

# Inline options + config
aphids-cli \
  -jo '{"configuration":{"online":"enabled"},"modules":{"nmap-scan":{"module":"nmap","target":"10.0.0.1"}}}' \
  -jc '{"authorization":{"apiKey":"YOUR_KEY"},"baseUrl":"https://api.hive.darksidesecurity.io/"}'

# Or mix: inline options + env var for auth
export APHIDS_API_KEY="your-key"
aphids-cli -jo '{"configuration":{"online":"enabled"},"modules":{"nmap-scan":{"module":"nmap","target":"10.0.0.1"}}}'

Docker Volume Mounts#

Understanding volume mounts is essential for running APHIDS in containers.

Mount Paths#

Container Path Purpose Mode
/output/ Options file, scan results, checkpoints, tool output Read-write
/workspace/ Source code for SAST tools Read-only (:ro)

Common Patterns#

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 '{"modules":{"nmap-scan":{"module":"nmap","target":"10.0.0.1"}}}'

Output directory

Always mount a local directory to /output/ to persist scan results. Without this mount, results are lost when the container exits.

Logging#

Configure local logging in config.yaml or via environment variables:

logging:
  enabled: true
  output: file
  path: output.json
Field Values Description
enabled true / false Enable local log output
output file / stdout Output destination
path filepath Log file path (when output is file)