Web platform for managing and documenting penetration tests, from scope definition to automated report generation. Final undergraduate thesis project (TCC).
Pentest Flow centralizes the entire pentest workflow: the client describes the scope, the pentester models the tested infrastructure (networks, hosts, services, vulnerabilities, and evidence), imports results from tools such as Metasploit, and finally generates a PDF report written with AI assistance — all with real-time progress tracking.
- Role-based access control (RBAC):
ADMIN,PENTESTER, andCLIENT, each with its own permissions. - Scope management: the client registers the scope (type, methodology, and details) that originates the pentest.
- Attack-surface modeling: Pentest → Networks → Hosts (IP/MAC/OS) → Services (port/protocol/state) → Vulnerabilities (severity/type) → Evidence (file uploads).
- Metasploit report import: an XML parser that automatically populates networks, hosts, services, and vulnerabilities from a scan.
- AI-assisted report generation: technical/executive PDF reports generated asynchronously by an AWS Lambda function (OpenAI + FPDF) and stored in S3.
- Real-time tracking: report-generation progress is streamed over WebSocket (Socket.IO).
- Authentication and password recovery: JWT login and an email-based password reset flow.
- Dual API: REST endpoints (Zod validation) and GraphQL (Apollo) — the pentest dashboard is served via GraphQL.
The backend follows Clean Architecture / DDD, with responsibilities split into layers and the domain organized by context (scope, pentest, network, host, OS, service, protocol, vulnerability, evidence, report, and users):
api/src/
├── core/ # building blocks: Entity, UniqueEntityId, Either (error handling), generic repositories
├── domain/ # pure business rules: entities, use-cases, and repository interfaces per context
│ └── pentest/parsers/ # Metasploit XML parser
├── application/ # queue and storage contracts
└── infra/ # implementations: Prisma, GraphQL, HTTP, WebSocket, queue (SQS), storage (S3), auth, email
Report generation is fully decoupled: the API publishes a message to the SQS queue → the Lambda consumes it, generates the PDF (narrative via OpenAI + layout via FPDF) and saves it to S3 → the client is notified over WebSocket.
User (role) → Scope → Pentest → Network → Host (→ OS) → Service (→ Protocol) → Vulnerability → Evidence, with Report linked to the pentest.
| Layer | Technologies |
|---|---|
| Backend | NestJS 11, TypeScript, GraphQL (Apollo), REST, Prisma ORM, PostgreSQL, Passport/JWT, Socket.IO, Zod, Nodemailer |
| Frontend | React 18, Vite, TypeScript, Ant Design, React Router 7, Socket.IO Client, Zod |
| Cloud/Infra | AWS S3 (evidence/reports), AWS SQS (queue), AWS Lambda + SAM (PDF generation), OpenAI, Docker / Docker Compose |
| Quality | Vitest, e2e tests, in-memory repositories and fakes for the use-cases |
pentest-flow/
├── api/ # NestJS backend (Clean Architecture + Prisma)
├── web/ # React + Vite + Ant Design frontend
├── infra/ # AWS Lambda (PDF report generation) + SAM template
└── docker/ # docker-compose (dev and production)
Prerequisites: Docker and Docker Compose.
# 1. Clone the repository
git clone https://github.com/jronca/pentest-flow.git
cd pentest-flow
# 2. Configure the API environment variables
cp api/.env.example api/.env
# Adjust JWT_SECRET and DATABASE_URL as needed
# 3. Start the API + PostgreSQL database
cd api
yarn docker:dev:up # start the containers
yarn docker:dev:build # build the image
yarn docker:dev:start # start the API in watch mode
# 4. Migrations and seed (creates the Admin user and default protocols)
yarn db:migrate:dev
yarn db:seedDefault user created by the seed: admin@admin.com / admin123 (role ADMIN).
# 5. Frontend
cd ../web
cp .env.example .env # set VITE_API_URL pointing to the API
yarn && yarn devThe function in infra/ is packaged and deployed via AWS SAM. It requires OPENAI_API_KEY and access to the S3 bucket (see infra/.env.example and infra/template.yaml).
Developed as a final undergraduate thesis project (TCC). Educational use.