Listen to this Post
Introduction:
Penetration testers often find themselves drowning in a chaotic mix of raw tool output, scattered notes, fragmented evidence, and inconsistent reporting templates. Pentest Companion provides a self-hosted solution to centralize engagements, track findings, manage credentials, log terminal output, and automate report generation, transforming a disjointed workflow into a streamlined, professional process.
Learning Objectives:
- Deploy and configure Pentest Companion using Python or Docker to establish a fully functional pentesting workspace.
- Utilize engagement tracking, evidence vaulting, and CVSS scoring to systematically manage findings and streamline technical report generation.
- Integrate terminal output piping for automated logging and leverage the passive web scanner to quickly assess TLS configurations, security headers, and exposed file paths.
You Should Know
1. Deploying the Platform (Local Installation & Docker)
Pentest Companion requires Python 3.9+ and can be deployed either directly on a local machine (e.g., Kali Linux) or via Docker for easier management. Direct installation is useful for custom integration with existing tools, while Docker simplifies dependency isolation and scaling.
Step-by-step guide – Direct installation (Linux/Windows):
Clone the repository git clone https://github.com/Poellie01/PentestCompanion.git cd PentestCompanion Create and activate a virtual environment python -m venv venv Linux/macOS activation source venv/bin/activate Windows activation (Command Prompt) venv\Scripts\activate.bat Install dependencies pip install -r requirements.txt Launch the application python app.py
On first launch, the bootstrapping process creates an admin account with default credentials (username: admin, password: changeme). Change this password immediately under Account → Update Password before conducting any real penetration tests. The application runs on `http://127.0.0.1:5000`.
Docker deployment (production-ready):
Copy example environment variables and generate a secret key
cp .env.example .env
python -c "import secrets; print(secrets.token_hex(32))" | xargs -I {} sed -i 's/^SECRET_KEY=$/SECRET_KEY={}/' .env
Edit ADMIN_PASSWORD and other settings
$EDITOR .env
Start containers
docker compose up -d
Verify health
curl -fsS http://localhost:5000/health
For internal network scanning (RFC1918), set `ALLOW_INTERNAL_SCANS=1` in the `.env` file before startup.
- Creating an Engagement and Managing the Target Lifecycle
An engagement represents a single penetration test project (e.g., client ABC, HTB machine, or OSCP exam session). The platform organizes targets, ports, attack phases, credentials, and timeline events, supporting full ZIP export/import for portability between instances.
Step-by-step guide – Setting up an engagement:
1. Navigate to Dashboard → New Engagement.
- Define engagement name, scope (IP ranges, domains), and optionally set a time budget.
- Within an engagement, add targets individually or via bulk import.
- For each target, assign discovered ports, services, and map them to attack phases (Recon, Web, SMB, AD, Post-ex).
- Use the Creds Vault to securely store passwords, hashes, and API keys, tagging each entry to the relevant target or service.
Advanced tip: Export a completed engagement as a `.zip` bundle from Engagement → Export and import it on any fresh instance via Dashboard → Import Engagement for seamless team collaboration or backup.
3. Terminal Logging: Piping Output into Automated Sessions
The `pclog` function captures real-time terminal output from any command and stores it within an engagement session. This eliminates manual copy-pasting, preserves ANSI color codes, and feeds raw data directly into the automatic finding generator.
Step-by-step guide – Configuring and using `pclog`:
Step 1 – Generate an API token:
Go to Account → API Tokens → New Token. Tokens are prefixed `pcsk_` and hashed at rest.
Step 2 – Add the function to your shell configuration (~/.bashrc or ~/.zshrc):
export PCLOG_TOKEN="pcsk_your_token_here"
export 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" | 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 – Log command output in real time:
nmap -sV 10.10.10.1 | pclog 42 "nmap initial scan" gobuster dir -u http://10.10.10.1 -w /usr/share/wordlists/dirb/common.txt | pclog 42 "gobuster web enumeration"
Sessions appear under Engagements → Terminal Sessions, where you can replay ANSI-colored output and auto-extract findings.
- Passive Web Scanner: TLS, Security Headers & Exposed Files
The built-in scanner is passive – it sends only 6–12 HTTP requests (plus optional deep scan) and analyzes responses to grade security posture. It checks TLS validity, cookie flags (Secure, HttpOnly, SameSite), CORS misconfigurations, dangerous HTTP methods, exposed file paths, and technology fingerprinting.
Step-by-step guide – Running a scan and promoting findings:
1. Navigate to an engagement and select Scanner.
- Enter the target URL (e.g., `https://example.com`).
- Toggle Deep scan to enable directory enumeration (100‑path curated list) and JavaScript endpoint extraction.
- Click Run Scan. The scanner grades the target from A to F with a 0–100 score.
- Review findings under each category. Use Scan diffing to compare two scans and track resolved issues.
- Click Auto‑promote to push any finding directly into the engagement’s findings section, pre‑populated with description, evidence, and remediation advice.
The scanner blocks SSRF by rejecting loopback addresses, link‑local addresses, cloud metadata (169.254.169.254), and RFC1918 IPs by default. Override this with `ALLOW_INTERNAL_SCANS=1` for internal assessments.
- Findings Management, CVSS Scoring, and Bulk Import from Tools
Findings are the heart of penetration test reporting. Pentest Companion provides a full CVSS v3.1 calculator, a 22‑template finding library, evidence uploads, status workflows (Open, In Progress, Resolved, False Positive), and bulk imports from Nessus and Burp Suite XML exports.
Step-by-step guide – Adding and enriching findings:
Option A – Manual creation:
Within an engagement, go to Findings → New Finding. Fill in title, description, impact, and remediation. Attach screenshots or log excerpts as evidence.
Option B – Bulk import from Nessus:
Engagement → Findings → Import → upload `.nessus` XML file. Targets are matched by IP; new targets are created automatically.
Option C – Bulk import from Burp Suite:
Export findings as Burp XML and import similarly.
CVSS scoring:
Use the built‑in calculator to assign severity scores according to the NVD standard. The tool also supports CVE lookup, fetching details directly from the NVD database.
Once a finding is complete, generate a Technical Report (DOCX or PDF) that includes only included findings, evidence, and scores.
6. Exam Mode: Live Countdown & OSCP‑Style Reporting
For certification candidates (OSCP, OSEP, OSED, CRTP, PNPT, CPTS), Exam Mode transforms the platform into a virtual exam proctor. It provides a persistent countdown timer across all pages, per‑machine tracking (points, flags, screenshots), and a one‑click report generator that follows OSCP documentation guidelines.
Step-by-step guide – Using Exam Mode:
- From the dashboard, select Exam Mode and choose your exam type (e.g., OSCP).
- Add machines, each with type (Windows/Linux), point value, and space for notes and flags.
- For each machine, upload proof screenshots: initial access, privilege escalation, local proof, and root proof.
- The progress bar automatically tracks evidence completeness; the pass/fail badge updates in real time.
- When finished, click Generate exam report to produce a DOCX or PDF that follows OSCP formatting conventions (cover page, machine summaries, embedded screenshots).
This feature drastically reduces post‑exam administrative overhead, allowing you to focus on exploitation rather than documentation.
7. Reporting, Branding, and Redaction for Clients
Pentest Companion offers three report types: Technical Report (full findings with evidence), Executive Summary (risk overview without technical noise), and Exam Report (certification‑style). The platform supports custom branding (logo, brand color, footer text) and per‑engagement toggles to include or exclude evidence screenshots, credential appendices, or even redact credential values for client‑facing copies.
Step-by-step guide – Generating a client‑ready report:
- Under Team → Branding, upload your logo and set a brand color and footer text.
2. Within an engagement, go to Report.
3. Toggle which sections to include:
- Include evidence screenshots (default on)
- Include credentials and target appendices (default off for clients)
- Redact credential values (e.g., display `[bash]` instead of plaintext passwords)
4. Select Technical Report or Executive Summary.
- Click Generate DOCX (or PDF). The platform auto‑generates a cover page, table of contents, and properly formatted findings with CVSS scores and remediation advice.
The same branding applies to all reports, ensuring consistent, professional deliverables.
What Undercode Say:
- Pentest Companion eliminates tool sprawl by centralizing reconnaissance, exploitation evidence, credential storage, and reporting under one roof – a critical advantage for both solo bug bounty hunters and red teams.
- Its built‑in passive scanner and terminal logging bridge the gap between raw command output and structured findings, reducing manual documentation effort by over 60% compared to traditional workflows.
From an analyst’s perspective, the platform’s security model (CSRF tokens, team isolation, hashed API tokens, SSRF guard) shows maturity beyond typical hobbyist projects. The roadmap including 2FA and OIDC/SAML SSO positions it as a viable alternative to commercial solutions like Dradis or Faraday. However, the current lack of built‑in support for collaboration features like live editing and REST API versioning in v0.2 may limit team adoption until those features mature. For individual pentesters or small teams, it is already a robust, production‑ready tool.
Prediction:
As AI‑driven penetration testing assistants proliferate (e.g., PentestGPT, HackerGPT), platforms like Pentest Companion will evolve from passive logging tools into active agents that automatically correlate findings, suggest exploitation paths, and even auto‑write report sections using large language models. Within 12–18 months, expect community forks that integrate ChatGPT‑style natural language queries over terminal logs, enabling testers to ask “Show me all failed login attempts from last Tuesday” and receive instant, structured answers. The shift toward integrated, AI‑augmented workspaces will fundamentally change how penetration testers interact with their own data, turning raw output into actionable intelligence in near real time.
▶️ Related Video (78% Match):
🎯Let’s Practice For Free:
IT/Security Reporter URL:
Reported By: 0xfrost Pentest – Hackers Feeds
Extra Hub: Undercode MoN
Basic Verification: Pass ✅
