A self-hosted workspace for pentesters, red teamers, bug bounty hunters, and certification grinds (OSCP / OSEP / CRTP / PNPT / HTB). Run your tools from the UI, auto-import findings, track methodology phases, share results with clients, and generate a report when you're done — all from one place, on infrastructure you control.

No cloud. No SaaS. Your data stays on your server.

git clone https://github.com/Poellie01/PentestCompanion.git
cd PentestCompanion
cp .env.example .env

# Generate a real SECRET_KEY
python3 -c "import secrets; print(secrets.token_hex(32))" \
    | xargs -I {} sed -i 's/^SECRET_KEY=$/SECRET_KEY={}/' .env

# Set ADMIN_PASSWORD (and SMTP/Resend if you want email)
$EDITOR .env

docker compose up -d
docker compose logs -f app

First run bootstraps an admin account and prints the credentials:

============================================================
  Bootstrapped admin account.
    username: admin
    password: changeme
  !!  CHANGE THIS PASSWORD or set ADMIN_PASSWORD in .env
============================================================

Hit http://localhost:5000, sign in, change your password under Account → Update Password.

git clone https://github.com/Poellie01/PentestCompanion.git
cd PentestCompanion
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python app.py

Full engagement management — targets, ports, credentials, attack steps, PTES checklist, timeline, and time tracking in one view. Export any engagement as a .pcbundle and restore it on any Pentest Companion instance.

CVSS v3.1 scoring, evidence uploads, CVE lookup, remediation tracking, and a 40+ template library. Import findings from Nessus (.nessus) and Burp Suite (XML export) in one click.

The tools hub discovers what's installed on the host and gives you a point-and-click interface for 50+ common tools. Running Pentest Companion on Kali Linux gives you the full set out of the box.

Categories: Network · Web · AD/Windows · Impacket · Password Attacks · DNS · SSL/TLS · OSINT · Linux Enumeration · Custom

When you add a target to an engagement, expand Auto-Scan in the modal and tick the tools you want. Each selected tool runs in the background — findings land in the engagement automatically when the job completes.

Passive scanner — fires a small, fixed set of HTTP requests.

Deep scan adds directory enumeration and JS endpoint extraction. Scan diffing lets you compare two scans side-by-side. Auto-promote pushes scan findings into an engagement in one click.

Pipe any command output into an engagement session and replay it later with full ANSI colour.

Step 1 — get a token: Account → API Tokens → New Token

Step 2 — add to your shell config:

PCLOG_TOKEN="pcsk_your_token_here"
PCLOG_BASE="http://localhost:5000"

pclog() {
    local eid=$1; shift
    local name="${*:-$(date +%H:%M:%S)}"
    local sid
    sid=$(curl -sf -X POST "$PCLOG_BASE/api/v1/terminal/start" \
        -H "Authorization: Bearer $PCLOG_TOKEN" \
        -H "Content-Type: application/json" \
        -d "{\"engagement_id\":$eid,\"name\":\"$name\"}" \
        | python3 -c "import sys,json; print(json.load(sys.stdin)['session_id'])")
    while IFS= read -r line; do
        printf '%s\n' "$line"
        printf '%s\n' "$line" | curl -sf -X POST "$PCLOG_BASE/api/v1/terminal/append/$sid" \
            -H "Authorization: Bearer $PCLOG_TOKEN" \
            -H "Content-Type: application/octet-stream" --data-binary @- > /dev/null
    done
    curl -sf -X POST "$PCLOG_BASE/api/v1/terminal/close/$sid" \
        -H "Authorization: Bearer $PCLOG_TOKEN" > /dev/null
}

Step 3 — use it:

nmap -sV 10.10.10.1 | pclog 42 "nmap initial"
gobuster dir -u http://10.10.10.1 -w /usr/share/wordlists/dirb/common.txt | pclog 42 "gobuster web"

Run a sequenced chain of tools against a target in one click. Each step waits for the previous one to finish before launching.

Built-in playbooks:

Navigate to Playbooks in the nav bar, pick a playbook, select a target, and watch each step advance in real time. You can cancel mid-run and create custom playbooks through the same UI.

Set a tool to run against a target on a recurring schedule — every hour, every 6 hours, daily, or weekly. A background daemon claims and runs due jobs every 60 seconds; findings land in the engagement automatically.

Target page → Scheduled Scans → Add Schedule → pick tool + interval

Get notified in Slack, Discord, or Teams whenever a finding is created — either by an auto-import job or manually.

Supported formats: Slack Block Kit · Discord embeds · Teams MessageCard · Generic JSON

Team Settings → Webhooks → New Webhook → paste URL → Test

Each delivery is logged with status code and response body. Webhook URLs are validated against the SSRF block-list before saving.

Select one or more findings with the row checkboxes (or Select All), then use the sticky bulk action bar to:

• Set severity, status, or assignee across all selected findings in one click
• Mark selected findings as False Positive
• Delete selected findings

Two read endpoints are available for external tooling and integrations. All requests require a Bearer token (create one under Team Settings → API Tokens).

curl -H "Authorization: Bearer pcsk_yourtoken" \
     http://localhost:5000/api/v1/engagements/1/findings?severity=critical&page=1

Export any engagement as a .pcbundle file (a versioned ZIP containing all data and evidence files). Import it on any Pentest Companion instance — useful for sharing engagements between team members, archiving, or moving between instances.

Engagement → Export Bundle  →  client-engagement.pcbundle
                                        ↓
                          Dashboard → Import Bundle
                              (drag-and-drop, live preview)

Full format reference at /bundle/help when running the app.

Share findings with clients without giving them access to the app. Each portal link is token-based, optionally password-protected, and optionally set to expire.

Engagement → #portal → New Portal Link → send link to client

Clients see: finding title, severity, description, remediation, CVSS score, and CVE ID. Nothing internal (credentials, attack steps, notes) is exposed.

Each target gets a structured checklist organised around PTES pentest phases:

Supports: OSCP · OSEP · OSED · CRTP · PNPT · CPTS · Custom

• Live countdown baked into the navbar
• Per-machine tracking: type, points, flags, and screenshot slots
• Pass/fail badge updates in real time as flags come in
• Generate exam-style DOCX/PDF report when done

Without email config, reset links are printed to the server log — fine for local use.

app.py                    # Flask application — core routes, models, init_db
config.py                 # All env config + shared constants
database.py               # DB layer: get_db(), init_db(), migrations, CVE sync
helpers.py                # Auth guards, row fetchers, audit(), token_required
scheduler.py              # Consolidated kali + web-scanner scheduler daemon
scanner.py                # Web security scanner (pure stdlib)
reporting.py              # Report helpers: MITRE map, risk score, diff, roadmap
commands.py               # Renderable pentest command templates
requirements.txt
Dockerfile
docker-compose.yml
.env.example

blueprints/               # Route blueprints (refactor in progress)
  auth.py                 # 20 auth routes
  team.py                 # 32 team + webhook + API-token routes
  reports.py              # 23 report + bundle + client-portal routes
  scanner.py              # Web scanner + terminal + playbooks + scheduled scans
  engagements.py          # Engagements, targets, findings, sub-resources

tools/                    # Kali tool integration package
  manifest.py             # 90+ tool definitions
  profiles.py             # ScanProfile dataclass + build/parse logic
  generic_runner.py       # subprocess + SSE streaming + auto-import
  generic_parser.py       # Universal finding extractor (regex + JSON)
  base.py                 # ToolJobRunner ABC + job persistence
  playbook_engine.py      # Sequential multi-step playbook executor
  webhooks.py             # Slack / Discord / Teams / JSON notifier
  trigger_engine.py       # Finding triggers + FP triage
  auto_orchestrator.py    # Auto-scan orchestration
  auto_discover.py        # Host/service auto-discovery

templates/                # Jinja2 templates
static/
  style.css               # Single stylesheet
  app.js

tests/                    # 258 tests
  conftest.py             # App fixtures, auth helpers
  test_auth.py            # Login, registration, SSRF guard
  test_routes.py          # Route smoke tests
  test_leakage.py         # Cross-team isolation on every <int:id> endpoint
  test_team.py            # Role enforcement, invite flow, member management
  test_security.py        # Security controls
  test_reporting.py       # Reporting helpers
  test_webhooks.py        # Webhook delivery + formatting
  test_playbook_engine.py # Playbook executor
  test_trigger_engine.py  # Finding triggers
  test_generic_parser.py  # Universal parser (97% coverage)
  test_auto_orchestrator.py # Auto-orchestration (73% coverage)

pip install pytest
pytest                        # all tests
pytest tests/test_leakage.py  # cross-team isolation
pytest -v                     # verbose

Licensed under the GNU Affero General Public License v3.0.

For commercial licensing (white-label, proprietary redistribution, or enterprise use) contact: info@ceretrix.net