How mordavid/externalattacker-mcp works
Project Type & Purpose
• This is a small full-stack Python web application (“ExternalAttacker-App.py”) combined with a Model Context Protocol (MCP) server (“ExternalAttacker-MCP.py”).
• It provides a natural-language interface for orchestrating external attack surface scans using ProjectDiscovery Go tools.
File Structure & Key Indicators
• Top-level scripts:
• ExternalAttacker-App.py – the HTTP server & MCP client interface
• ExternalAttacker-MCP.py – standalone MCP server handling scan requests
• templates/ – Jinja2 HTML views (base.html, index.html, result.html)
• requirements.txt – Python deps (Flask or built-in HTTP server, mcp-proto, etc.)
• version.txt, README.md, images/ – static assets & docs
• No separate “backend” or “services” folder: two main Python processes communicate via MCP protocol.
Main Architectural Components
a. User Browser (Frontend)
• Renders index.html for query input; submits to App.py via HTTP.
b. ExternalAttacker-App.py (Web Server & MCP Client)
• Receives HTTP requests, processes natural-language queries, invokes MCP client API.
• Renders result.html with scan outcomes.
c. ExternalAttacker-MCP.py (MCP Server)
• Listens on stdin/stdout for MCP JSON-RPC commands.
• Implements scan handlers that map to specific scanning tools.
d. External Scanning Tools (Infrastructure)
• subfinder, naabu, httpx, cdncheck, tlsx, ffuf, gobuster, dnsx
• Invoked as subprocesses; their stdout/stderr are parsed and returned as structured results.
e. External Targets & Services
• Domains, IPs, HTTP endpoints to be scanned.
• Optional third-party MCP clients can also connect to the MCP server.
Data Flow & Interactions
1. Browser → (HTTP POST / GET) → App.py route
2. App.py → (MCP JSON-RPC over stdin/stdout) → MCP Server
3. MCP Server → (subprocess call) → individual scan tools → results back to MCP Server
4. MCP Server → (JSON response) → App.py
5. App.py → (render template) → Browser
Architectural Patterns & Principles
• Layered design: Presentation (Jinja2 templates), Application (Flask/HTTP handlers), Service (MCP server), Infrastructure (Go tools).
• MVC flavor in App.py:
• Controllers = Flask routes
• Views = Jinja2 templates
• Model = normalized scan result objects
• Adapter/Facade: MCP Server normalizes heterogeneous CLI outputs behind a unified protocol.
• Single Responsibility: Web UI vs. scan orchestration separated into two processes.
• Extensibility: New scan modules added by extending MCP handler logic and subprocess mappings.