PurpleTeam Suite

An integrated deterministic AI framework for vulnerability discovery, prioritisation and remediation guidance.

CST3590 Individual Project · Middlesex University London · 2026

---

About

PurpleTeam Suite is an Electron desktop application that automates the purple-team lifecycle in a single pipeline: Nmap scanning, deterministic OWASP Top 10 classification, exploitability-aware scoring, AI-assisted analysis, hallucination validation, delta comparison and exportable PDF reporting.

Requirements

Runtime (installed app / EXE)

• Nmap on the system PATH (Kali Linux already includes it; Windows: install from https://nmap.org/download.html; macOS: brew install nmap; Ubuntu/Debian: sudo apt install nmap)
• A Google Gemini API key (set GEMINI_API_KEY in frontend/.env or as an environment variable)

Development

• Node.js 18+

Gemini API key setup

Create frontend/.env (copy frontend/.env.example) with:

GEMINI_API_KEY=your_key_here

If you are using the prebuilt EXE without rebuilding, set GEMINI_API_KEY in your OS environment before launching.

Quick start

git clone https://github.com/umfhero/PurpleTeamAI.git
cd PurpleTeamAI/frontend
npm install

npm run dev

To run the vulnerable testbed (optional, for end-to-end testing against a local target):

cd ../test-site
npm install
node server.js

To build a standalone installer:

cd ../frontend
npm run build

Repository structure

PurpleTeamAI/
├── frontend/                    # Electron + React application
│   ├── electron/                # Main process (backend)
│   │   ├── scanner/             # Nmap orchestration, XML parsing
│   │   ├── analysis/            # OWASP mapping, scoring, hallucination guard,
│   │   │                        #   delta comparison, feature toggles
│   │   ├── llm/                 # Gemini integration with schema enforcement
│   │   ├── reports/             # PDF generators (pentest + delta)
│   │   ├── main.ts              # Electron entry point + IPC handlers
│   │   └── preload.ts           # IPC bridge (context-isolated)
│   ├── src/                     # React renderer (frontend)
│   │   ├── components/          # UI components
│   │   ├── pages/               # Scan, Results, Reports pages
│   │   └── store/               # Shared state
│   ├── public/                  # Static assets
│   └── allowed-targets.json     # Scan allowlist (safety enforcement)
│
├── test-site/                   # Controlled vulnerable testbed
│   ├── server.js                # Vulnerable server (12 intentional issues)
│   ├── server-fixed.js          # Remediated server (for delta testing)
│   └── public/                  # Test pages and assets
│
├── data/                        # Generated at runtime
│   ├── scans/                   # Scan results (JSON, newest first)
│   ├── reports/                 # Exported PDF reports
│   └── hallucination-metrics.json
│
└── README.md

Usage

1. Launch the app with npm run dev.
2. Enter an allowlisted target on the Scan page and click Start.
3. Phase 1 (top 100 ports) returns early; Phase 2 (full sweep) continues in the background.
4. Review findings, AI analysis and trust score on the Results page.
5. Export a PDF report or run a second scan to generate a delta comparison.

Ethics and authorised use

Active network scanning is regulated under the Computer Misuse Act 1990. The allowlist in frontend/allowed-targets.json is enforced in the main process before Nmap is invoked. Do not modify the allowlist to target systems you do not own or have explicit written permission to scan.