spaf 1.0.0

███████╗██████╗  █████╗ ███████╗
██╔════╝██╔══██╗██╔══██╗██╔════╝
███████╗██████╔╝███████║█████╗  
╚════██║██╔═══╝ ██╔══██║██╔══╝  
███████║██║     ██║  ██║██║     
╚══════╝╚═╝     ╚═╝  ╚═╝╚═╝     

📌 What is SPAF?

SPAF is a professional, asynchronous offensive security framework that acts as an AI-powered Red Team brain. It goes beyond traditional scanners by automatically transforming vulnerability data into weaponized attack intelligence.

• 🎯 Run multi-vector scans against any target
• 🧠 AI threat analysis runs automatically after every scan (Google, Claude, Ollama, LM Studio)
• 🚀 Auto-generate Proof-of-Concept exploit scripts in Python
• 🛠️ Receive production-ready remediation code in Ansible, Terraform, or Bash
• 🕵️ Operate with full anonymity via TOR, proxy rotation, and fingerprint randomization
• ⏱️ 24/7 shadow monitoring with intelligent alerting
• 📡 Passive Shodan intelligence — open ports & org info without touching the target
• 📊 Export findings to CSV/JSON for client deliverables
• 🔍 Diff two scans — instantly see what changed (new/fixed/unchanged)
• 🐳 Docker-ready — one command to spin up the full stack

✨ 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 Deployment

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_MONGO_URI=mongodb://localhost:27017

💻 Usage

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

# ─── 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

🤖 AI Provider Setup

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 Integration

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

🔍 Scan 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
│   ├── 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.