youngsecurity/pentest-agent-system

1. This repository is a multi-part security tooling workspace, not a single app. The main production system described by the README is the “Nmap Real-time Visualization System,” but the tree also contains a separate Python-based security analyst/agent package and a small Deno area for experiments/tests.

2. The core runtime architecture is split into a FastAPI backend and a Svelte frontend. The backend owns scan execution, parsing, progress state, and WebSocket delivery; the frontend owns the interactive UI, real-time rendering, and client-side connection management.

3. In the backend, app/main.py is the application entrypoint and app/core/config.py holds runtime configuration. API routes are separated by responsibility: health.py for liveness checks, nmap.py for scan control and scan-related REST endpoints, and websocket.py for push-based scan updates.

4. The backend is organized as a service-oriented pipeline for Nmap processing. app/services/nmap/runner.py executes Nmap, parser.py turns raw output into structured data, locator.py handles discovery of the Nmap binary or related environment details, and service.py acts as the orchestration layer between routes and the lower-level execution/parsing logic.

5. The Nmap data model boundary is explicit. app/models/nmap.py defines the structured scan result objects that travel between parsing, API responses, and client-side visualization, keeping raw process output isolated from structured scan state.

6. Real-time delivery is handled by a dedicated WebSocket subsystem in app/services/ws/manager.py. This manager is the boundary between backend scan progress and connected clients: it tracks sessions/connections and broadcasts incremental updates as scans run, which is what enables live visualization instead of polling.

7. Progress and operational state are supported by utility modules rather than embedded in the routes. app/utils/progress_tracker.py and app/utils/logging_utils.py suggest centralized tracking/logging concerns, while app/services/interfaces.py and exceptions.py define service contracts and error boundaries. The tests in backend/tests/unit/services/... mirror this layering and verify the nmap and websocket subsystems independently.

8. The frontend is a Svelte application with a very small composition surface: src/main.ts bootstraps App.svelte, and the project-level README indicates the UI is built around real-time terminal-style output plus structured progress/port/vulnerability views. Vite is the build/runtime toolchain (vite.config.js, package.json), which matters because the frontend is a separate SPA served to the browser and connected back to FastAPI over WebSockets.

9. There is a second, distinct Python package under python/src/pentest_agent_system focused on AI-assisted security analysis rather than live Nmap visualization. Its architecture includes agents (modules/agents), a model handler, tool integration, a database manager, Metasploit integration, and UI components built around a chat/pentest/testing workflow.

10. The Python package is also layered around orchestration. security_analyst_orchestrator_agent.py, security_analyst_agent.py, vulnerability_extractor_agent.py, mitre_attack_mapper_agent.py, and attack_plan_generator_agent.py indicate an agent pipeline that transforms scan or exploit data into analysis, mapping, and attack planning outputs; callbacks/, utils/, and models/ support that flow with reusable infrastructure.

11. External process and tool boundaries are important in both subsystems. The backend wraps the Nmap CLI as an external subprocess, while the Python security-analyst package appears to integrate with model inference and Metasploit as external dependencies. Those integrations are isolated behind service/module boundaries so the rest of the code can work with structured results rather than raw tool output.

12. Persistence appears lightweight and file-based in the main backend, with storage/data.json suggesting local state or result storage rather than a heavy database layer. This fits the README’s “stateless design with file-based progress tracking” and means the architecture is centered on streaming updates plus structured scan results, not on long-term backend persistence.

13. The test layout reinforces the system boundaries. Backend tests focus on websocket behavior and Nmap service internals; Python tests cover agent behavior, parsing, vulnerability detection, and end-to-end security analyst flows. For an architecture diagram, the key edges are: browser/UI ↔ WebSocket/API ↔ FastAPI service layer ↔ Nmap subprocess/parsers, plus a separate Python agent pipeline that consumes security data and produces analysis outputs.