spaf 1.5.0

_{AI engines  ·  Google Gemini  ·  Anthropic Claude  ·  Ollama  ·  LM Studio  ·  Shodan}

Point SPAF at a target and it runs the engagement. The AI plans the recon, SPAF runs the tools on your machine, and you get the findings plus a written assessment — built for Kali, bug bounty, and red-team work.

pip install "spaf[ai]"        # SPAF + the AI providers
spaf setup                    # pick your AI + database (SQLite = zero setup)
spaf agent target.com         # the AI plans → runs → reports, end to end

_{⚠️ Authorized testing only — see the Legal Disclaimer.}

What you get

• spaf agent — an autonomous agent: the AI chooses which modules to run, chains them, and writes the assessment.
• Recon toolkit — one pipeline wrapping subfinder, httpx, nuclei, katana, dnsx, ffuf and more.
• AI threat analysis after every scan — Gemini, Claude, Ollama, or LM Studio — plus PoC and remediation code on demand.
• Full attack surface — recon, network + CVE mapping, web audit, crawler, passive Shodan intel.
• Scope-safe & stealthy — engagement-scope enforcement, TOR, proxy rotation, UA randomization.
• Zero-setup storage — MongoDB, or a local SQLite file with nothing to install.
• Share it — dark-mode HTML/JSON reports, CSV export, and scan diffing.

◇ How it works

One target in, a written assessment out. The agent plans the steps, scope-gates anything active, runs the modules on your machine, then lets the AI write it up.

%%{init: {'theme':'base','themeVariables':{'fontFamily':'JetBrains Mono, ui-monospace, monospace','primaryColor':'#04150a','primaryTextColor':'#39FF41','primaryBorderColor':'#2ea043','lineColor':'#2ea043','clusterBkg':'#0d1117','clusterBorder':'#1f6f33'}}}%%
flowchart TD
  T([ target ]):::hot --> A{{ AI plans the assessment }}:::hot
  A --> SC[/ scope check /]:::dim

  SC --> R[recon<br/>subdomains · DNS · WHOIS]:::box
  SC --> TK
  SC --> W[web audit<br/>headers · TLS · paths]:::box
  SC --> N[network<br/>nmap · CVE mapping]:::box

  subgraph TK [recon toolkit]
    direction LR
    s1[subfinder<br/>assetfinder] --> s2[dnsx] --> s3[httpx] --> s4[katana<br/>hakrawler] --> s5[wayback<br/>gau] --> s6[ffuf] --> s7[nuclei]
  end

  R --> F[( findings )]:::hot
  TK --> F
  W --> F
  N --> F

  F --> DB[( MongoDB / SQLite )]:::dim
  F --> AI[[ AI assessment ]]:::hot
  AI --> REP[report<br/>HTML · JSON · CSV]:::hot

  classDef hot fill:#04150a,stroke:#39FF41,color:#39FF41,stroke-width:1px;
  classDef box fill:#0d1117,stroke:#2ea043,color:#8CF5A0;
  classDef dim fill:#0d1117,stroke:#1f6f33,color:#5CE47A;

_{Run the whole chain with spaf agent target.com, or any single stage on its own (spaf recon, spaf toolkit, spaf scan, …).}

◇ Core feature set

subfinder / assetfinder  →  dnsx  →  httpx  →  katana / hakrawler
                                             →  waybackurls / gau  →  ffuf  →  nuclei

◇ Demo

A 60-second tour — safe to run offline against example.com:

spaf tools                       # see which recon binaries are installed
spaf tools --install             # install the Go recon suite (requires Go)
spaf scope add example.com       # define engagement scope
spaf toolkit example.com         # subfinder → httpx → katana → nuclei pipeline
spaf report example.com --format html --with-ai   # shareable HTML report + AI analysis

▶️ Generate a walkthrough GIF for your fork with scripts/demo.sh — recipe in docs/demo.md.

◇ Installation

From PyPI (recommended)

pip install spaf                 # core
pip install "spaf[ai]"           # + Google / Claude / OpenAI-compatible providers
pip install "spaf[intel]"        # + Shodan passive intelligence
pip install "spaf[ai,intel]"     # everything

From source (for development)

git clone https://github.com/geevarghesekthomas84-sys/spaf.git
cd spaf
python -m venv venv
source venv/bin/activate         # Windows: venv\Scripts\activate
pip install -e ".[ai,intel,dev]" # editable install with all extras + test tools

First run

cp .env.example .env             # configure providers / MongoDB / stealth
spaf --install-completion        # shell tab-completion (optional)
spaf tools --install             # install the recon toolkit binaries (needs Go)
spaf setup                       # interactive configuration wizard

Requirements: Python 3.11+, Nmap, MongoDB (local or remote)

Optional: RustScan for ultra-fast port discovery · the recon toolkit binaries (spaf tools to check) · Shodan via the intel extra above

◇ Docker

The fastest way to get running — no manual setup of MongoDB or Python environment needed.

# 1. Start MongoDB + SPAF in one command
docker-compose up -d

# 2. Run any scan
docker-compose run spaf recon target.com
docker-compose run spaf scan target.com --scanner rustscan --ports 1-65535

# 3. Drop into interactive AI shell
docker-compose run spaf shell

# Override the entire command
docker-compose run spaf export target.com --format csv

Note: docker-compose.yml uses network_mode: host so Nmap/RustScan can reach real targets.
.env is automatically mounted from the project root — add your API keys there.

◇ Configuration

Copy .env.example to .env and configure your providers:

# ─── AI Provider (choose one) ────────────────────────────────────
AI_PROVIDER=google            # google | claude | ollama | lmstudio

# Remote providers
GOOGLE_API_KEY=your_key
ANTHROPIC_API_KEY=your_key

# Model overrides (optional — defaults shown)
GOOGLE_MODEL=gemini-2.0-flash
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022

# Local providers
OLLAMA_URL=http://localhost:11434/v1
OLLAMA_MODEL=llama3.2             # optional, auto-detected
LM_STUDIO_URL=http://localhost:1234/v1
LM_STUDIO_MODEL=your-model        # optional, auto-detected from loaded model

# ─── APIs ────────────────────────────────────────────────────────
NIST_API_KEY=your_key             # free: https://nvd.nist.gov/developers/request-an-api-key
SHODAN_API_KEY=your_key           # free: https://account.shodan.io/register

# ─── Stealth / OpsSec ────────────────────────────────────────────
USE_TOR=false
PROXY_FILE=./proxies.txt
RANDOM_USER_AGENT=true

# ─── Database ────────────────────────────────────────────────────
SPAF_DB_BACKEND=mongo                      # mongo (default) | sqlite
SPAF_MONGO_URI=mongodb://localhost:27017   # used when backend = mongo
SPAF_SQLITE_PATH=spaf.db                   # used when backend = sqlite

No MongoDB? Use the SQLite fallback. Set SPAF_DB_BACKEND=sqlite (or pick it in spaf setup) and SPAF stores everything in a local file — no database server needed. Great for quick/offline use.

◇ Usage

📖 Full command reference with all flags and examples → COMMANDS.md

# ─── Autonomous Agent (AI plans & chains the modules) ────────────
spaf agent target.com                                # plan → confirm → run → AI assessment
spaf agent target.com --goal "find web vulns" -y     # steer it, skip the prompt
spaf agent target.com --dry-run                      # preview the plan only

# ─── Reconnaissance ──────────────────────────────────────────────
spaf recon target.com                                # Recon + AI + Shodan (if key set)
spaf recon target.com --passive --no-ai              # Passive OSINT only

# ─── Network Scanning ────────────────────────────────────────────
spaf scan target.com                                 # Nmap + AI analysis
spaf scan target.com --scanner rustscan --ports 1-65535  # RustScan → Nmap
spaf scan target.com --intensity aggressive          # Deep scan (-sV -sC -O -A)

# ─── Web Security ────────────────────────────────────────────────
spaf webscan https://target.com                      # Full web audit + AI
spaf crawl https://target.com --depth 3              # Spider + AI

# ─── External Recon Toolkit ──────────────────────────────────────
spaf tools                                           # Show which recon tools are installed
spaf toolkit target.com                              # Full pipeline: subfinder→httpx→katana→nuclei
spaf toolkit target.com --no-nuclei --no-crawl       # Passive recon only (no active scan)
spaf toolkit target.com --fuzz --wordlist wl.txt     # Add ffuf content fuzzing
spaf toolkit target.com --nuclei-severity critical,high --output recon.json

# ─── AI Provider Shortcuts (all context-safe) ────────────────────
spaf test-ai                                         # Health check + status table
spaf chat "How do I bypass a WAF?"                   # Configured provider
spaf gemini "Explain CVE-2024-1234"                  # Google Gemini
spaf claude "Write an Ansible remediation task"      # Anthropic Claude
spaf ollama "List SMB exploitation paths"            # Ollama — live streaming
spaf lmstudio "Analyze these HTTP headers"           # LM Studio — live streaming

# ─── AI Analysis on past scans ───────────────────────────────────
spaf ai <scan_id>                                    # Re-analyze (no re-scan)
spaf ai <scan_id> --provider ollama                  # Use Ollama for this run

# ─── Exploit & Remediation ───────────────────────────────────────
spaf poc <finding_id>                                # Generate Python exploit script
spaf poc <finding_id> --output exploit.py
spaf remediate <finding_id> --format ansible         # Fix code (ansible/terraform/bash)

# ─── Operations ──────────────────────────────────────────────────
spaf export target.com --format csv                  # Export findings to CSV
spaf export target.com --format json                 # Export findings to JSON
spaf diff <scan_id_1> <scan_id_2>                    # Compare two scans
spaf scope show                                      # View engagement scope
spaf scope add target.com                            # Add to scope
spaf scope remove target.com                         # Remove from scope
spaf watch target.com --interval 3600 --module webscan   # 24/7 monitoring
spaf report target.com --format html                 # Premium HTML report
spaf history                                         # Past scan records
spaf shell                                           # Interactive AI shell
spaf update                                          # Update SPAF to latest

◇ MCP server ^{new in 1.5}

Run SPAF as an MCP server so Claude Desktop (or any MCP host) can drive it with natural language — recon, the toolkit, scans, and the autonomous agent, all as native tools, locally.

pip install "spaf[mcp]"           # installs the MCP support
spaf scope add target.com         # authorize a target first
spaf mcp                          # serve over stdio

Add it to Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "spaf": { "command": "spaf", "args": ["mcp"] }
  }
}

Then ask Claude things like "recon target.com and summarize the risks."

Safety model (a model is calling these):

• Scope is enforced inside every tool — out-of-scope targets are refused, and there is no bypass flag exposed to the model.
• agent_run is plan-only by default; active execution needs an explicit dry_run=false and an in-scope target.
• No raw-command tool — the model only selects SPAF's fixed modules.
• Every active call is written to an audit log (logs/audit.jsonl).

See docs/ROADMAP_V2.md for the full platform plan (HTTP API, model router, secure gateway, dashboard).

◇ AI providers

Quick Comparison

Ollama Setup

# 1. Install Ollama → https://ollama.com
# 2. Pull a model
ollama pull llama3.2
ollama pull qwen2.5-coder   # great for exploit/remediation code

# 3. Set in .env
AI_PROVIDER=ollama
OLLAMA_URL=http://localhost:11434/v1   # default, change if remote
OLLAMA_MODEL=llama3.2                  # optional — auto-detected if not set

# 4. Test connection
spaf test-ai

# 5. Use shortcut (tokens stream in real-time)
spaf ollama "List exploitation paths for open SMB ports"

LM Studio Setup

# 1. Download LM Studio → https://lmstudio.ai
# 2. Load any GGUF model in the app
# 3. Go to: Local Server tab → Start Server

# 4. Set in .env
AI_PROVIDER=lmstudio
LM_STUDIO_URL=http://localhost:1234/v1  # default
LM_STUDIO_MODEL=your-model-name         # optional — auto-detected from loaded model

# 5. Test connection
spaf test-ai

# 6. Use shortcut (tokens stream in real-time)
spaf lmstudio "Analyze these HTTP headers for security risks"

All AI name variants accepted: lmstudio, lm-studio, lm_studio all work as AI_PROVIDER values.

◇ Shodan intel

Enrich every spaf recon scan with passive Shodan intelligence — open ports, org, ISP, and country — without sending any packets to the target.

# 1. Get a free API key → https://account.shodan.io/register
# 2. Add to .env
SHODAN_API_KEY=your_api_key

# 3. Install the Shodan library
pip install shodan

# 4. Run recon — Shodan data is fetched automatically
spaf recon target.com

◇ Diff & export

# View scan history to get IDs
spaf history

# Compare two scans — see what's new, fixed, or unchanged
spaf diff <older_scan_id> <newer_scan_id>

# Export all findings for a target to CSV (for clients)
spaf export target.com --format csv
spaf export target.com --format json --output /tmp/findings.json

◇ Engagement scope

# Initialise scope (creates scope.json in current directory)
spaf scope add target.com
spaf scope add 10.0.0.0/24

# View current scope
spaf scope show

# Remove a target
spaf scope remove 10.0.0.0/24

# Use a custom scope file
spaf scope show --file engagement_scope.json

◇ Project structure

spaf/
├── spaf/
│   ├── cli/          # Typer CLI — all commands
│   ├── core/         # Async engine & BaseModule
│   ├── agent/        # autonomous AI orchestrator (spaf agent)
│   ├── modules/      # recon, network, webscan, crawler, toolkit
│   ├── utils/        # AI orchestrator, proxy, risk, validator, scope, logger
│   ├── database/     # MongoDB async driver (Motor) with full indexes
│   └── reports/      # HTML & JSON report generator
├── tests/            # Pytest test suite
├── scripts/          # demo.sh and helper scripts
├── docs/             # Demo recipe and extra docs
├── .github/          # CI + release workflows, issue/PR templates
├── Dockerfile        # Python 3.12-slim + nmap + Go recon suite
├── docker-compose.yml # MongoDB 7 + SPAF with healthcheck
├── scope.json        # Engagement scope (auto-created)
├── COMMANDS.md       # Full command reference
└── .env.example      # Configuration template

◇ Contributing & releasing

Contributions are welcome — see CONTRIBUTING.md and the Code of Conduct. In short:

pip install -e ".[dev]"
pytest -q                 # tests
ruff check spaf tests     # lint
python -m build           # wheel

CI runs these on every push and pull request. Notable changes go in CHANGELOG.md.

Releasing to PyPI is automated via Trusted Publishing: tag a version and push, and the Release workflow builds and publishes it.

git tag v1.0.1
git push origin v1.0.1        # → builds, checks, and publishes to PyPI

One-time setup: on PyPI, add a trusted publisher for this repo pointing at the release.yml workflow and the pypi environment.

◇ Stealth & OpsSec

◇ Legal disclaimer

This tool is intended strictly for authorized security testing, research, and educational purposes only. The developer assumes no liability for any misuse or damage caused. Always obtain explicit written permission from the target organization before conducting any security tests.