# nbshenxm/pentest-agent architecture

> Architecture diagram of the GitHub repository nbshenxm/pentest-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nbshenxm/pentest-agent
- Repository: https://github.com/nbshenxm/pentest-agent

## Overview

##### Project type and purpose
- PentestAgent is an LLM-driven, modular penetration-testing framework. It orchestrates three distinct “agents” (Reconnaissance, Planning, Execution) to automate intel gathering, vulnerability scoring, and controlled exploit attempts.
- It uses Python 3.12, a YAML-based config, RAG (vector indexes on disk), and Docker Compose for service isolation.

##### File structure
- Top level:
- agents/ – three scripts (recon_agent.py, planning_agent.py, execution_agent.py)
- configs/config.yaml – models, CVE scoring, runtime parameters
- utils/ – shared code (LLM factory, CVE info parser, prompt templates, searcher plugins, merge & voting logic)
- data/benchmark/ – sample CVE score data
- docker/ – one Dockerfile per agent + docker-compose.yaml
- requirements.txt, .env patterns, versioning & update scripts
- Pattern: each agent is a self-contained microservice with shared libs in utils, configured by YAML/.env, writing to/reading from local volumes (indexes, logs, planning output).

##### README insights
- Describes each agent’s function, required environment variables, dependency on ProjectDiscovery’s CVEMAP, and Docker deployment steps.
- Emphasizes multi-source intelligence (GitHub, ExploitDB, Google) aggregated via searcher plugins.

- Reconnaissance Agent Service
- Planning Agent Service
- Execution Agent Service
- Shared Utils Library (LLM Factory, Prompt Manager, CVE scoring, Searcher plugins)
- Configuration Store (config.yaml + .env)
- Data Volumes (Vector Index Store, Planning Output Dir, Logs)
- External Services:
– CVE API (ProjectDiscovery/CVEMAP)
– GitHub API
– ExploitDB (via GitLab token or searchsploit)
– Google Search
– LLM Providers (OpenAI, HuggingFace, etc.)

- Recon Agent ← config, .env → invokes utils/llm_factory + searchers → queries CVE API & LLM → writes raw intel to Vector Index Store
- Planning Agent ← config + Vector Index Store → loads intel → calls utils/searchers (GitHub, ExploitDB, Google) & LLM → runs merge_scores & vote → writes analysis to Planning Output Dir
- Execution Agent ← config + Planning Output Dir → loads chosen exploit docs → calls LLM for execution guidance → triggers CVEMAP-driven exploit scripts against Target IP:Port → logs to Logs Dir

c. Architectural patterns/design principles
- Agent-based microservices: each agent is isolated, containerized, configurable.
- Pipeline pattern: sequential Recon → Plan → Execute stages.
- Plugin/strategy pattern: searchers under utils/searchers implement a common interface.
- RAG pattern: vector store + LLM as retrieval-augmented component.
- Separation of concerns: core logic in utils, orchestration in agent scripts.

d. Key technologies/frameworks/libraries
- Python 3.12, PyPI dependencies (see requirements.txt)
- Docker / Docker Compose
- ProjectDiscovery CVEMAP CLI
- LLM Providers via utils/llm_factory
- YAML for config, .env for secrets
- Vector index storage (local FS)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Agents
    subgraph "Agent Services"
        Recon["Reconnaissance Agent Service"]:::service
        Planning["Planning Agent Service"]:::service
        Execution["Execution Agent Service"]:::service
    end

    %% Shared Libraries and Config
    subgraph "Shared Utilities" 
        LLFactory["llm_factory.py"]:::shared
        CVEInfo["cve_info.py"]:::shared
        MergeScores["merge_scores.py"]:::shared
        PromptMgr["prompt.py"]:::shared
        ModelMgr["model_manager.py"]:::shared
        DocHandler["doc_handler.py"]:::shared
        DirClass["dir_class.py"]:::shared
        VerLimit["version_limit.py"]:::shared
        Vote["vote.py"]:::shared
        Prompts["prompts/"]:::shared
        Searchers["searchers/"]:::shared
    end

    subgraph "Configuration Store"
        ConfigYAML["config.yaml"]:::config
        ConfigInit["__init__.py"]:::config
    end

    %% Data Stores
    VectorIndex["Vector Index Store"]:::store
    PlanningOutput["Planning Output Dir"]:::store
    LogsDir["Logs Dir"]:::store
    BenchmarkData["cve_scores.json"]:::store

    %% Orchestration
    Compose["docker-compose.yaml"]:::config

    %% External Services
    subgraph "External Services"
        CVEAPI["CVE API (ProjectDiscovery/CVEMAP)"]:::external
        GitHubAPI["GitHub API"]:::external
        ExploitDB["ExploitDB / searchsploit"]:::external
        GoogleSearch["Google Search"]:::external
        LLMProviders["LLM Providers"]:::external
    end

    %% Dependency & Docs
    subgraph "Dependencies & Scripts"
        Req["requirements.txt"]:::dep
        GenReq["generate_requirements.py"]:::dep
        UpdDeps["update_dependencies.sh"]:::dep
    end

    subgraph "Project Docs"
        Readme["README.md"]:::docs
        License["LICENSE"]:::docs
        Gitignore[".gitignore"]:::docs
        IssueBug["bug_report.md"]:::docs
        IssueFeat["feature_request.md"]:::docs
    end

    %% Config and Utils to Agents
    ConfigYAML --> Recon
    ConfigInit --> Recon
    LLFactory --> Recon
    CVEInfo --> Recon
    Prompts --> Recon
    Searchers --> Recon

    ConfigYAML --> Planning
    ConfigInit --> Planning
    LLFactory --> Planning
    CVEInfo --> Planning
    MergeScores --> Planning
    Vote --> Planning
    Prompts --> Planning
    Searchers --> Planning

    ConfigYAML --> Execution
    ConfigInit --> Execution
    LLFactory --> Execution
    DocHandler --> Execution
    Prompts --> Execution
    Searchers --> Execution

    %% Pipeline flow
    Recon -->|"writes raw intel"| VectorIndex
    VectorIndex --> Planning
    Planning -->|"writes analysis"| PlanningOutput
    PlanningOutput --> Execution
    Execution -->|"writes logs"| LogsDir

    %% Benchmark data
    BenchmarkData --> Recon

    %% Orchestration
    Compose --> Recon
    Compose --> Planning
    Compose --> Execution

    %% Agents call external
    Recon -->|queries| CVEAPI
    Recon -->|queries| LLMProviders

    Planning -->|queries| GitHubAPI
    Planning -->|queries| ExploitDB
    Planning -->|queries| GoogleSearch
    Planning -->|queries| LLMProviders

    Execution -->|calls| CVEAPI
    Execution -->|guidance from| LLMProviders

    %% Dependencies & Docs links
    Req --> Compose
    GenReq --> Req
    UpdDeps --> Req
    Readme --> Compose
    License --> Readme
    Gitignore --> Readme
    IssueBug --> Readme
    IssueFeat --> Readme

    %% Click events
    click Recon "https://github.com/nbshenxm/pentest-agent/blob/main/agents/recon_agent.py"
    click Recon "https://github.com/nbshenxm/pentest-agent/blob/main/agents/ollama_recon_agent.py"
    click Recon "https://github.com/nbshenxm/pentest-agent/blob/main/docker/recon.Dockerfile"
    click Planning "https://github.com/nbshenxm/pentest-agent/blob/main/agents/planning_agent.py"
    click Planning "https://github.com/nbshenxm/pentest-agent/blob/main/docker/planning.Dockerfile"
    click Execution "https://github.com/nbshenxm/pentest-agent/blob/main/agents/execution_agent.py"
    click Execution "https://github.com/nbshenxm/pentest-agent/blob/main/docker/execution.Dockerfile"
    click LLFactory "https://github.com/nbshenxm/pentest-agent/blob/main/utils/llm_factory.py"
    click CVEInfo "https://github.com/nbshenxm/pentest-agent/blob/main/utils/cve_info.py"
    click MergeScores "https://github.com/nbshenxm/pentest-agent/blob/main/utils/merge_scores.py"
    click PromptMgr "https://github.com/nbshenxm/pentest-agent/blob/main/utils/prompt.py"
    click ModelMgr "https://github.com/nbshenxm/pentest-agent/blob/main/utils/model_manager.py"
    click DocHandler "https://github.com/nbshenxm/pentest-agent/blob/main/utils/doc_handler.py"
    click DirClass "https://github.com/nbshenxm/pentest-agent/blob/main/utils/dir_class.py"
    click VerLimit "https://github.com/nbshenxm/pentest-agent/blob/main/utils/version_limit.py"
    click Vote "https://github.com/nbshenxm/pentest-agent/blob/main/utils/vote.py"
    click Prompts "https://github.com/nbshenxm/pentest-agent/tree/main/utils/prompts/"
    click Searchers "https://github.com/nbshenxm/pentest-agent/tree/main/utils/searchers/"
    click ConfigYAML "https://github.com/nbshenxm/pentest-agent/blob/main/configs/config.yaml"
    click ConfigInit "https://github.com/nbshenxm/pentest-agent/blob/main/configs/__init__.py"
    click BenchmarkData "https://github.com/nbshenxm/pentest-agent/blob/main/data/benchmark/cve_scores.json"
    click Compose "https://github.com/nbshenxm/pentest-agent/blob/main/docker/docker-compose.yaml"
    click Req "https://github.com/nbshenxm/pentest-agent/blob/main/requirements.txt"
    click GenReq "https://github.com/nbshenxm/pentest-agent/blob/main/generate_requirements.py"
    click UpdDeps "https://github.com/nbshenxm/pentest-agent/blob/main/update_dependencies.sh"
    click Readme "https://github.com/nbshenxm/pentest-agent/blob/main/README.md"
    click License "https://github.com/nbshenxm/pentest-agent/tree/main/LICENSE"
    click Gitignore "https://github.com/nbshenxm/pentest-agent/blob/main/.gitignore"
    click IssueBug "https://github.com/nbshenxm/pentest-agent/blob/main/.github/ISSUE_TEMPLATE/bug_report.md"
    click IssueFeat "https://github.com/nbshenxm/pentest-agent/blob/main/.github/ISSUE_TEMPLATE/feature_request.md"

    %% Styles
    classDef service fill:#D0E8FF,stroke:#0366d6,color:#000
    classDef shared fill:#D6FFD6,stroke:#28a745,color:#000
    classDef config fill:#D6E0FF,stroke:#005cc5,color:#000
    classDef store fill:#FFF4AA,stroke:#735c0f,color:#000
    classDef external fill:#E0E0E0,stroke:#6a737d,color:#000
    classDef dep fill:#FFEBCC,stroke:#994500,color:#000
    classDef docs fill:#F0F0F0,stroke:#444,color:#000
```
