PentestMgr

Features

Everything you need to run a professional penetration testing engagement from scope definition to client delivery.

Tech Stack

Installation

git clone https://github.com/saherm0hamed/PentestMgr.git
# or: unzip PentestMgr.zip
cd PentestMgr

python3 -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
pip install -r requirements.txt
npm install -g pptxgenjs           # for PPTX export

cp .env.example .env
# Edit .env and set strong secrets:
SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))")
JWT_SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))")

python manage.py seed   # admin/admin123 + tester/tester123
python run.py           # → http://localhost:5000

The first account you register automatically becomes admin if no seed was run.

Docker

cp .env.example .env              # set secrets first
docker-compose up -d
docker-compose exec pentest-mgr python manage.py seed

Data persists in the pentest_data Docker volume. The container runs gunicorn with 2 workers on port 5000.

Configuration

CLI & manage.py

The manage.py script provides administrative commands for managing the platform.

Engagements

An engagement represents a single penetration testing project. Each engagement has its own scope, finding list, notes, evidence, and report settings.

Status workflow

Engagement types

Web Application, Network, Mobile, Red Team, Social Engineering, Cloud, Physical, API, Other.

Scope format

Enter one target per line. Supports IPs, CIDR ranges, domains, and wildcard domains. The scope validator checks targets in real-time against these entries.

Findings

Findings are automatically sorted by severity. Each finding tracks the full lifecycle from discovery to remediation.

Severity levels

Status pipeline

Fields

Finding Templates

15 pre-built finding templates covering the most common vulnerabilities. Apply any template to an engagement with one click — it pre-fills title, severity, CVSS, description, impact, recommendation, and references. You only need to customise the PoC and affected hosts.

Scope Validator

Paste any list of targets and validate them instantly against the engagement's in-scope and out-of-scope lists.

Supported target types

API endpoint

POST /scope/engagement/{id}/check
Content-Type: application/json

{"targets": ["10.10.10.1", "192.168.1.0/24", "api.corp.com"]}

Evidence Upload

Attach evidence files directly to an engagement or to a specific finding. Files are stored in instance/uploads/ with unique names to prevent collisions.

Supported types: PNG, JPG, GIF, WebP, PDF, TXT, XML, JSON, LOG, ZIP, PCAP, HAR · Max 20 MB per file.

Export Formats

Every engagement can be exported in three professional formats from the engagement detail page or the report preview.

Branding & Fonts

Each engagement has independent branding settings saved in instance/branding/<id>.json. Changes apply immediately to all export formats.

Auto contrast

Text colour is automatically selected based on background luminance — no manual text colour setting needed. Dark backgrounds receive light text (#E6EDF3), light backgrounds receive dark text (#1F2328).

Available fonts

Remediation Tracker

Set a remediation deadline and responsible owner for each finding in an engagement. This data is stored in instance/remediation/<id>.json and automatically included in DOCX and PPTX exports as a tracker table.

Access via Engagement Detail → ↓ Export → ✅ Remediation.

Authentication

The REST API uses JWT Bearer tokens. Session cookies are used for the web UI — the API is completely independent.

curl -X POST http://localhost:5000/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "yourpassword"}'

# Response
{"access_token": "eyJ...", "user": {"username": "admin", ...}}

curl http://localhost:5000/api/v1/engagements \
  -H "Authorization: Bearer eyJ..."

Endpoints

Auth

Engagements

Findings

Notes & Evidence

Stats

Code Examples

Push findings from a Python script

import requests

BASE  = "http://localhost:5000/api/v1"
token = requests.post(
    f"{BASE}/auth/token",
    json={"username": "admin", "password": "yourpassword"}
).json()["access_token"]

H = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

# Create a finding from your recon script
requests.post(f"{BASE}/engagements/1/findings", headers=H, json={
    "title":           "SQL Injection in /api/search",
    "severity":        "Critical",
    "cvss_score":      9.8,
    "cve":             "CVE-2024-1234",
    "description":    "Unsanitised input allows UNION-based SQLi",
    "impact":          "Full database read/write access",
    "recommendation": "Use parameterised queries",
    "proof_of_concept":"' OR 1=1--",
    "affected_hosts":  "app.target.com",
})

Update finding status

curl -X PUT http://localhost:5000/api/v1/findings/1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "Remediated"}'

Test Suite

82 pytest tests covering every module. Run from the project root with the virtual environment active.

pytest tests/test_app.py -v

# Run a specific class
pytest tests/test_app.py::TestJWTApi -v
pytest tests/test_app.py::TestScopeValidator -v
pytest tests/test_app.py::TestBrandingAndFont -v

Project Structure

PentestMgr/
├── run.py                     ← Flask dev server
├── manage.py                  ← CLI tool
├── pytest.ini
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .env.example
├── docs/
│   └── index.html             ← GitHub Pages site
│
├── app/
│   ├── __init__.py            ← App factory + error handlers
│   ├── models.py              ← User, Engagement, Finding, Evidence, Note
│   │
│   ├── blueprints/
│   │   ├── auth.py            ← Login / logout / register
│   │   ├── dashboard.py       ← Stats overview
│   │   ├── engagements.py     ← Engagement CRUD + notes
│   │   ├── findings.py        ← Finding CRUD
│   │   ├── findings_list.py   ← Global search + filter
│   │   ├── reports.py         ← PDF / DOCX / PPTX + branding
│   │   ├── api.py             ← JWT REST API v1
│   │   ├── evidence.py        ← File upload / serve
│   │   ├── scope.py           ← Scope validator
│   │   ├── templates_bp.py    ← Finding templates
│   │   ├── export.py          ← JSON export / import / duplicate
│   │   ├── users.py           ← Admin user management
│   │   └── profile.py         ← Self-service profile
│   │
│   ├── templates/
│   │   ├── base.html          ← Dark/light layout + sidebar
│   │   ├── auth/
│   │   ├── dashboard/
│   │   ├── engagements/
│   │   ├── findings/
│   │   ├── reports/           ← preview, branding, remediation
│   │   ├── scope/
│   │   ├── templates/
│   │   ├── users/
│   │   ├── profile/
│   │   └── errors/            ← 403, 404, 500
│   │
│   └── static/
│       └── img/               ← favicon.ico, favicon-32.png, apple-touch-icon.png
│
└── tests/
    ├── conftest.py
    └── test_app.py            
            

Release Guide

git init && git add .
git commit -m "feat: initial release v1.0.0"
git tag -a v1.0.0 -m "PentestMgr v1.0.0"

git remote add origin https://github.com/saherm0hamed/PentestMgr.git
git push -u origin main --tags

gh release create v1.0.0 \
  --title "PentestMgr v1.1.1" \
  --notes "Initial release"