# hustinfseclabs/pentestassistant architecture

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

- Interactive diagram: https://gitdiagram.com/hustinfseclabs/pentestassistant
- Repository: https://github.com/hustinfseclabs/pentestassistant

## Overview

##### Project type and purpose
- PentestAssistant is an open-source, LLM-driven automation framework for web penetration testing.
- It uses a multi-agent workflow (planner, executor, refiner) plus function-call techniques to orchestrate pentest tools (nmap, sqlmap, etc.).
- It’s not a classic full-stack web app, but rather a CLI/daemon tool that integrates LLM APIs, local models, retrieval/reranking, and plugins.

##### File structure
- app.py: the CLI entrypoint and main orchestration bootstrap.
- config/: configuration loader (config.ini, config.py).
- log/: centralized logging module.
- agent/: definitions of the three LLM agents (Planner, Executor, Refiner, plus Analyst and Checker helpers).
- model/: adapters for ChatGPT, Qwen, Deepseek, Wenxin plus base classes.
- retrieval/: embedding and reranking modules (bge embedding, reranker, large multi reranker).
- planner/: internal planners and capability checkers, tool suggestion/shortening logic.
- plugin/: JSONL metadata for each pentest tool plus a plugin loader and executor interface.
- requirements.txt & LICENSE: dependencies and licensing.

##### Key README insights
- Multi-agent workflow:
- Planner proposes a plan and tool sequence.
- Executor invokes tools/plugins and processes results.
- Refiner iteratively improves or verifies results.
- Supports multiple LLM backends configured in config.ini.
- Uses a retriever/reranker model to pick the best API calls.
- Invokes external binaries (nmap, sqlmap, etc.) via plugin adapters.

##### Final recommendations
- Trace every interaction path: planner’s tool selection → executor’s tool invocation → refiner’s feedback loop.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Infrastructure Layer
    subgraph "Infrastructure" 
        direction TB
        CLI["CLI / app.py"]:::infra
        ConfigLoader["Configuration Loader\n(config/config.py, config.ini)"]:::infra
        Logging["Logging Service\n(log/log.py)"]:::infra
    end

    %% Agent Manager and Sub-agents
    subgraph "Agent Manager" 
        direction TB
        Manager["Agent Manager"]:::agent
        PlannerAgent["Planner Agent"]:::agent
        ExecutorAgent["Executor Agent"]:::agent
        RefinerAgent["Refiner Agent"]:::agent
        AnalystAgent["Analyst Helper"]:::agent
        CheckerAgent["Checker Helper"]:::agent
    end

    %% Model & Retrieval Layer
    subgraph "Intelligence Layer" 
        direction TB
        subgraph "Model Layer"
            direction TB
            BaseModel["Base Adapter"]:::model
            ChatGPT["ChatGPT Adapter"]:::model
            Qwen["Qwen Adapter"]:::model
            Wenxin["Wenxin Adapter"]:::model
            Deepseek["Deepseek Adapter"]:::model
        end
        subgraph "Retrieval Layer"
            direction TB
            BaseRetrieval["Base Retrieval"]:::model
            Embedding["Embedding Service"]:::model
            RerankerStd["Standard Reranker"]:::model
            RerankerLarge["Large-Multi Reranker"]:::model
        end
    end

    %% Plugin Framework
    subgraph "Plugin Framework" 
        direction TB
        PluginLoader["Plugin Loader & Interface"]:::plugin
        PluginMetadata["Plugin Metadata\n(JSONL)"]:::plugin
        PluginExec["Plugin Executors"]:::plugin
    end

    %% External Tools
    subgraph "External Tools" 
        direction TB
        Nmap["Nmap"]:::external
        Sqlmap["Sqlmap"]:::external
        Hydra["Hydra"]:::external
        CMSeek["CMSeek"]:::external
        Dirsearch["Dirsearch"]:::external
    end

    %% Connections
    CLI -->|loads| ConfigLoader
    CLI -->|bootstraps| Manager
    Manager --> PlannerAgent
    Manager --> ExecutorAgent
    Manager --> RefinerAgent
    Manager --> AnalystAgent
    Manager --> CheckerAgent

    PlannerAgent -->|requests plan| BaseModel
    PlannerAgent -->|requests plan| ChatGPT
    PlannerAgent -->|requests plan| Qwen
    PlannerAgent -->|requests plan| Wenxin
    PlannerAgent -->|requests plan| Deepseek
    BaseModel --> BaseRetrieval
    ChatGPT --> Embedding
    Qwen --> Embedding
    Wenxin --> Embedding
    Deepseek --> Embedding
    Embedding --> RerankerStd
    Embedding --> RerankerLarge
    PlannerAgent -->|selects tools| PluginLoader

    ExecutorAgent -->|invoke| PluginExec
    PluginExec --> Nmap
    PluginExec --> Sqlmap
    PluginExec --> Hydra
    PluginExec --> CMSeek
    PluginExec --> Dirsearch
    ExecutorAgent -->|process results| BaseModel

    RefinerAgent -->|feedback loop| PlannerAgent
    RefinerAgent -->|feedback loop| ExecutorAgent

    %% Logging
    Manager --> Logging
    PlannerAgent --> Logging
    ExecutorAgent --> Logging
    RefinerAgent --> Logging
    AnalystAgent --> Logging
    CheckerAgent --> Logging

    %% Click Events
    click CLI "https://github.com/hustinfseclabs/pentestassistant/blob/main/app.py"
    click ConfigLoader "https://github.com/hustinfseclabs/pentestassistant/blob/main/config/config.py"
    click Logging "https://github.com/hustinfseclabs/pentestassistant/blob/main/log/log.py"
    click Manager "https://github.com/hustinfseclabs/pentestassistant/blob/main/agent/base.py"
    click PlannerAgent "https://github.com/hustinfseclabs/pentestassistant/blob/main/agent/planner.py"
    click ExecutorAgent "https://github.com/hustinfseclabs/pentestassistant/blob/main/agent/executor.py"
    click RefinerAgent "https://github.com/hustinfseclabs/pentestassistant/blob/main/agent/refiner.py"
    click AnalystAgent "https://github.com/hustinfseclabs/pentestassistant/blob/main/agent/analyst.py"
    click CheckerAgent "https://github.com/hustinfseclabs/pentestassistant/blob/main/agent/checker.py"
    click BaseModel "https://github.com/hustinfseclabs/pentestassistant/blob/main/model/base.py"
    click ChatGPT "https://github.com/hustinfseclabs/pentestassistant/blob/main/model/chatgpt.py"
    click Qwen "https://github.com/hustinfseclabs/pentestassistant/blob/main/model/qwen.py"
    click Wenxin "https://github.com/hustinfseclabs/pentestassistant/blob/main/model/wenxin.py"
    click Deepseek "https://github.com/hustinfseclabs/pentestassistant/blob/main/model/deepseek.py"
    click BaseRetrieval "https://github.com/hustinfseclabs/pentestassistant/blob/main/retrieval/base.py"
    click Embedding "https://github.com/hustinfseclabs/pentestassistant/blob/main/retrieval/bge_embedding.py"
    click RerankerStd "https://github.com/hustinfseclabs/pentestassistant/blob/main/retrieval/bge_reranker.py"
    click RerankerLarge "https://github.com/hustinfseclabs/pentestassistant/blob/main/retrieval/bge_reranker_large_multi.py"
    click PluginLoader "https://github.com/hustinfseclabs/pentestassistant/blob/main/plugin/plugin.py"
    click PluginMetadata "https://github.com/hustinfseclabs/pentestassistant/blob/main/plugin/CMSeek/CMSeek.jsonl"
    click PluginMetadata "https://github.com/hustinfseclabs/pentestassistant/blob/main/plugin/Certipy/Certipy.jsonl"
    click PluginMetadata "https://github.com/hustinfseclabs/pentestassistant/blob/main/plugin/Dirsearch/Dirsearch.jsonl"
    click PluginMetadata "https://github.com/hustinfseclabs/pentestassistant/blob/main/plugin/Dnsenum/Dnsenum.jsonl"
    click PluginMetadata "https://github.com/hustinfseclabs/pentestassistant/blob/main/plugin/Hydra/Hydra.jsonl"
    click PluginMetadata "https://github.com/hustinfseclabs/pentestassistant/blob/main/plugin/Nmap/Nmap.jsonl"
    click PluginMetadata "https://github.com/hustinfseclabs/pentestassistant/blob/main/plugin/Smbclient/Smbclient.jsonl"
    click PluginMetadata "https://github.com/hustinfseclabs/pentestassistant/blob/main/plugin/Sqlmap/Sqlmap.jsonl"
    click PluginMetadata "https://github.com/hustinfseclabs/pentestassistant/blob/main/plugin/Tplmap/Tplmap.jsonl"
    click PluginMetadata "https://github.com/hustinfseclabs/pentestassistant/blob/main/plugin/XSStrike/XSStrike.jsonl"

    %% Styles
    classDef infra fill:#DDDDDD,stroke:#333,stroke-width:1px
    classDef agent fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef model fill:#90EE90,stroke:#333,stroke-width:1px
    classDef plugin fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#F4A460,stroke:#333,stroke-width:1px
```
