Skip to content

🚀 Quick Start#

Get APHIDS running in under 5 minutes.

Prerequisites#

  • Container runtime: Docker (recommended), Podman, or nerdctl
  • Python 3.10+: For the CLI wrapper (not needed for container-direct mode)

Installation#

# Install the CLI
pip install git+https://github.com/darksidesecurity/aphids.git

# Pull the container
docker pull ghcr.io/darksidesecurity/aphids:latest

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the CLI
uv pip install git+https://github.com/darksidesecurity/aphids.git

# Pull the container
docker pull ghcr.io/darksidesecurity/aphids:latest

# Install as an isolated CLI tool
pipx install git+https://github.com/darksidesecurity/aphids.git

# Pull the container
docker pull ghcr.io/darksidesecurity/aphids:latest

# No Python needed — run directly
docker pull ghcr.io/darksidesecurity/aphids:latest

Your First Scan (Offline)#

Create an options.yaml file:

global_variables:
  target: 'https://your-target.com'

configuration:
  online: disabled
  network: public

modules:
  nmap-quick:
    module: nmap
    target: '##TARGET##'
    args:
      - '-sV'
      - '-T4'

  whatweb-fingerprint:
    module: whatweb
    target: '##TARGET##'
    args:
      - '-a'
      - '3'

  nuclei-scan:
    module: nuclei
    target: '##TARGET##'

Run it:

aphids-cli -o options.yaml

Results are written to the current directory as JSON.

🐝 Your First Scan (Online with Hive)#

No config.yaml needed — just set your API key as an environment variable:

Update your options.yaml to enable online mode:

configuration:
  online: enabled    # Send results to Hive
  network: public
  scan_group: my-first-scan
  engagements:
    - My Engagement Name

modules:
  nmap-quick:
    module: nmap
    target: '##TARGET##'
    args: ['-sV', '-T4']

export APHIDS_API_KEY="your-key-here"
aphids-cli -o options.yaml

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

Results appear in your Hive dashboard in real-time.

No config.yaml required

When APHIDS_API_KEY is set, APHIDS automatically connects to the Hive API with sensible defaults. You only need a config.yaml if you're using custom endpoint paths. See Configuration for details.

Try MCP Mode#

Expose all 40+ tools to your AI assistant:

# Offline (no Hive)
aphids-cli --mcp

# With Hive integration
export APHIDS_API_KEY="your-key"
aphids-cli --mcp

Then configure your AI client (Claude Desktop, Windsurf, Cursor) to use APHIDS as an MCP server. See MCP Mode for client-specific setup.

Try Agent Mode#

Deploy a persistent scanning agent:

export APHIDS_API_KEY="your-key"
aphids-cli --agent --agent-name prod-scanner-01

Or with Docker:

docker run --rm \
  -e APHIDS_API_KEY="your-key" \
  -v $(pwd)/output:/output \
  ghcr.io/darksidesecurity/aphids:latest \
  --agent --agent-name prod-scanner-01

The agent registers with Hive and waits for scan commands from the UI. See Agent Mode for details.

🧭 Next Steps#