👻 SpectreWeb AI v7.0.0

AI-Assisted Manual Web Penetration Testing

🎯 Manual Testing First | WAF Bypass | Context-Aware | Bug Bounty Ready

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

SpectreWeb is an MCP server that exposes a curated set of penetration-testing tools to AI agents (Windsurf, Claude Desktop, or any MCP-compatible client). It is designed for operator-driven manual testing — the AI helps you recon, fuzz, generate payloads, and analyze responses, while you stay in control of the testing strategy.

🎯 Philosophy

┌─────────────────────────────────────────────────────────────────────┐
│  ❌ Blind auto-scan → Blocked by WAF → Fail                         │
│  ✅ AI analyzes → Operator decides → Smart targeted tests → Success │
└─────────────────────────────────────────────────────────────────────┘

🏗️ Architecture

┌──────────────┐       ┌──────────────────┐       ┌──────────────────┐
│  AI Agent    │──MCP──▶│  mcp_client.py   │──HTTP─▶│  server.py       │
│ (Windsurf...)│       │  (47 MCP tools)  │       │  (Flask API)     │
└──────────────┘       └──────────────────┘       └────────┬─────────┘
                                                            │
                          ┌─────────────────────────────────┼─────────────────────┐
                          ▼                 ▼                ▼                      ▼
                     core/plugin.py    core/analyzer.py  web/secrets.py     web/exploits.py
                     (tool wrappers)   (tech fingerprint)(secret scanning)  (payload gen)

• mcp_client.py — MCP server exposing 47 tools, forwards to the HTTP API.
• server.py — Flask app hosting the REST API.
• api/routes.py — All HTTP endpoints.
• core/ — Command execution, tech analysis, reporting, context, plugins.
• web/ — HTTP client, payload generation, secret scanning, exploit helpers, origin IP finder.

🚀 Quick Start

1. Clone & Install

git clone https://github.com/tuannguyen14/SpectreWeb-AI
cd SpectreWeb-AI

python3 -m venv venv
source venv/bin/activate      # Windows: venv\Scripts\activate

pip install -r requirements.txt

2. Install Security Tools (optional, for tool wrappers)

# ProjectDiscovery tools
go install github.com/projectdiscovery/httpx/cmd/httpx@latest
go install github.com/projectdiscovery/subfinder/cmd/subfinder@latest
go install github.com/projectdiscovery/katana/cmd/katana@latest
go install github.com/projectdiscovery/naabu/v2/cmd/naabu@latest

# Other tools
go install github.com/tomnomnom/waybackurls@latest
go install github.com/lc/gau/v2/cmd/gau@latest
go install github.com/hahwul/dalfox/v2@latest

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.zshrc

Tools that are not installed simply report "not installed"; the rest keep working.

3. Configure Environment (optional)

Copy the example env file and fill in your API keys:

cp .env.example .env        # Windows: copy .env.example .env
# Edit .env with your favorite editor

.env is auto-loaded by python-dotenv (included in requirements.txt). You can also set env vars manually — see Environment Variables below.

4. Start the Server

python server.py
# 👻 SpectreWeb AI v7.0.0 - Starting...
# ✅ Server running at http://127.0.0.1:8888

5. Configure MCP

{
  "mcpServers": {
    "spectreweb-ai": {
      "command": "python",
      "args": ["/path/to/SpectreWeb-AI/mcp_client.py", "--server", "http://127.0.0.1:8888"],
      "timeout": 1500,
      "alwaysAllow": []
    }
  }
}

🔐 Authentication

API authentication is disabled by default (local-use friendly). To enable it, set an API key before starting the server:

export SPECTREWEB_API_KEY="your-secret-key"   # Windows: set SPECTREWEB_API_KEY=...
python server.py

When enabled, send the key via the X-API-Key header or Authorization: Bearer <key>.

🔧 Environment Variables

All configuration is done via environment variables. No hardcoded keys.

💡 Tip: Copy .env.example to .env and fill in your keys. The server auto-loads .env via python-dotenv.

Core

Origin IP Finder (optional API keys)

All Origin IP Finder techniques work without any API key. The following env vars enable optional enhanced data sources:

Setup (Linux):

export SPECTREWEB_SECURITYTRAILS_API_KEY="your-key"
export SPECTREWEB_SHODAN_API_KEY="your-key"
export SPECTREWEB_CENSYS_API_ID="your-id"
export SPECTREWEB_CENSYS_API_SECRET="your-secret"
export SPECTREWEB_QUAKE_API_KEY="your-quake-key"  # free tier works!
# export SPECTREWEB_FOFA_EMAIL="your-email"          # paid only (F-points)
# export SPECTREWEB_FOFA_API_KEY="your-fofa-key"      # paid only (F-points)
python server.py

Setup (Windows PowerShell):

$env:SPECTREWEB_SECURITYTRAILS_API_KEY = "your-key"
$env:SPECTREWEB_SHODAN_API_KEY = "your-key"
$env:SPECTREWEB_QUAKE_API_KEY = "your-quake-key"  # free tier works!
# $env:SPECTREWEB_FOFA_EMAIL = "your-email"          # paid only (F-points)
# $env:SPECTREWEB_FOFA_API_KEY = "your-fofa-key"      # paid only (F-points)
python server.py

⚠️ Never commit API keys to git. Use a .env file (add to .gitignore) or inject via CI/CD secrets.

📚 SecLists Configuration

SpectreWeb uses SecLists as its wordlist provider. The server auto-detects SecLists from common paths:

Option A: Install SecLists (recommended)

# Linux
git clone https://github.com/danielmiessler/SecLists /usr/share/SecLists

# Windows
git clone https://github.com/danielmiessler/SecLists D:\SecLists

Option B: Custom path

If SecLists is installed elsewhere, set the environment variable before starting the server:

# Linux
export SPECTREWEB_SECLISTS_PATH="/your/custom/SecLists"

# Windows (PowerShell)
$env:SPECTREWEB_SECLISTS_PATH = "E:\Tools\SecLists"

Available wordlists (42)

SpectreWeb ships with 42 pre-configured wordlists across 8 categories:

Using wordlists in MCP tools

# Pass wordlist name to ffuf_scan
ffuf_scan(url="https://target.com", wordlist="common")

# Or use a custom path
ffuf_scan(url="https://target.com", wordlist="/path/to/custom.txt")

# Get wordlist info
get_wordlist(name="api_wild")

# Get suggestions based on task
suggest_wordlist(task="nosql injection testing")

🛠️ MCP Tools (47 total)

Core (3)

Reconnaissance (8)

Content Discovery (3)

Vulnerability Testing (3)

Payloads & Bypass (4)

Secrets (3)

JavaScript & Web Analysis (2)

Access Control & Logic (3)

Specialized Attacks (4)

Analysis (2)

Reporting & Context (2)

Wordlists (2)

Origin IP Finder (8)

💡 Example Workflow

You: "Test target.com for vulnerabilities"

SpectreWeb AI:
1. load_context("target.com")        → Recall any prior findings
2. httpx_probe / whatweb_scan         → Cloudflare WAF detected
3. generate_bypass("waf", payload)    → Build evasion variants
4. vuln_test("xss", url)              → Probe with context-aware payloads
5. report("add_finding", ...)         → Persist the result

📁 Project Structure

SpectreWeb-AI/
├── server.py              # Flask server
├── mcp_client.py          # MCP client (47 tools)
├── config/
│   ├── settings.py        # Configuration
│   └── wordlists.py       # SecLists (auto-resolve)
├── core/
│   ├── executor.py        # Command execution
│   ├── plugin.py          # Tool plugins (nmap, ffuf, httpx, ...)
│   ├── analyzer.py        # Tech fingerprint & heuristic analysis
│   ├── reporter.py        # Persistent reporting
│   ├── context.py         # Per-target session persistence
│   ├── learning_store.py  # SQLite findings store
│   ├── middleware.py      # Auth, rate limiting, error handling
│   ├── job_queue.py       # Background job queue
│   └── file_manager.py    # Sandboxed file ops
├── web/
│   ├── client.py          # HTTP client with retry & rate limiting
│   ├── manual_testing.py  # Manual testing helpers
│   ├── deep_secrets.py    # Multi-stage secret hunting
│   ├── origin_finder.py  # Origin IP discovery (bypass CDN/WAF)
│   ├── advanced_scanner.py# Vuln scanners
│   ├── exploits.py        # Exploitation / payload helpers
│   ├── secrets.py         # Secret pattern scanning
│   └── payloads.py        # Payload generation
└── api/
    └── routes.py          # HTTP API endpoints

🔒 Legal & Ethical Use

⚠️ Only test systems you are explicitly authorized to test.

• Obtain written permission before any assessment.
• Respect scope, rate limits, and rules of engagement.
• Follow responsible disclosure practices.

📝 License

MIT License — Use responsibly.

Built for bug bounty hunters and security engineers who think, not just scan.