# mordavid/externalattacker-mcp architecture

> Architecture diagram of the GitHub repository mordavid/externalattacker-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mordavid/externalattacker-mcp
- Repository: https://github.com/mordavid/externalattacker-mcp

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        Browser["User Browser"]:::frontend
        Templates["Jinja2 Templates"]:::frontend
        App["ExternalAttacker-App.py\n(port 6991)"]:::backend
        Dependencies["Python Dependencies\nrequirements.txt"]:::frontend
        Docs["Documentation & Static Assets"]:::frontend
        Config["Project Config & Metadata"]:::frontend
    end

    %% Service Layer
    subgraph "Service Layer"
        MCP["ExternalAttacker-MCP.py"]:::service
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        Tools["Go Scan Tools\n(subfinder, naabu, httpx, cdncheck,\n tlsx, ffuf, gobuster, dnsx)"]:::infra
        Targets["External Targets\n(domains, IPs)"]:::cloud
    end

    %% Data Flow
    Browser -->|"HTTP/JSON"| App
    App -->|"renders"| Templates
    App -->|"MCP JSON-RPC\n(stdin/stdout)"| MCP
    MCP -->|"subprocess CLI calls"| Tools
    Tools -->|"scan results (stdout)"| MCP
    MCP -.-|"JSON response"| App
    App -->|"render template"| Browser

    %% Legend
    subgraph "Legend"
        L1["Blue Rectangle = Web Components"]:::frontend
        L2["Green Rounded = MCP Service"]:::service
        L3["Orange Parallelogram = External Tools"]:::infra
        L4["Cloud = External Targets"]:::cloud
    end

    %% Click Events
    click Templates "https://github.com/mordavid/externalattacker-mcp/tree/main/templates/"
    click App "https://github.com/mordavid/externalattacker-mcp/blob/main/ExternalAttacker-App.py"
    click MCP "https://github.com/mordavid/externalattacker-mcp/blob/main/ExternalAttacker-MCP.py"
    click Dependencies "https://github.com/mordavid/externalattacker-mcp/blob/main/requirements.txt"
    click Docs "https://github.com/mordavid/externalattacker-mcp/blob/main/README.md"
    click Config "https://github.com/mordavid/externalattacker-mcp/blob/main/.github/FUNDING.yml"

    %% Styles
    classDef frontend fill:#D6E9FE,stroke:#4A90E2,color:#000;
    classDef backend fill:#E8F4D9,stroke:#7FB800,color:#000;
    classDef service fill:#E8F9D8,stroke:#7FA800,color:#000;
    classDef infra fill:#FFE1E1,stroke:#E25C5C,color:#000;
    classDef cloud fill:#F0F8FF,stroke:#0000FF,color:#000;
```
