How nbshenxm/pentest-agent works
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)