A Next.js web application, engagement-mgr gives authorized penetration testing teams a shared workspace for engagements, clients, contacts, findings, review workflows, and immutable PDF report issuance.
| Tool | leebaird/engagement-mgr — a web application for tracking offensive security engagements, built with Next.js, Prisma, and PostgreSQL |
| Category | Engagement management and reporting platform (TypeScript) |
| Primary Use | Documenting authorized penetration test engagements: clients, contacts, operators, calendar scheduling, findings authoring, independent review, and final PDF report issuance |
| Safe Use | Designed for authorized security assessments, internal consulting teams, and lab environments; imports never execute scans or contact targets |
| Telemetry Note | Non-offensive by design: it performs no network interaction with targets, leaves database-backed sessions and content-free audit events on its own server, and emits immutable SHA-256-digested PDF artifacts |
engagement-mgr is a TypeScript web application from Lee Baird (@discoverscripts, best known for discover scripts) and Jay Townsend, purpose-built for the operational back office of offensive security work: tracking engagements, clients, contacts, operators, findings, and a calendar in a single modern UI. The stack is contemporary and deliberate — Next.js for the front end and Server Actions, Prisma as the ORM over PostgreSQL, with Node.js ^22.12.0 or >=24.0.0 required. It targets Ubuntu deployments and treats production hardening as a first-class concern rather than an afterthought. At roughly 24 stars, it is a young project, but the README's depth signals serious engineering intent rather than a weekend prototype.
The most substantial subsystem is the reporting workflow. Findings are written in a dedicated Markdown workspace with a safe preview, where private drafts save automatically after 15 seconds of inactivity and are stored server-side, explicitly not in browser local storage. Conflicting saves are resolved in favor of the editor's text, forcing an explicit comparison with the current revision, and text revisions can be inspected and restored. This is the kind of edge-case handling that separates tools written by people who have actually lost report content from those who have not. The revision history is bounded — findings retain at most 1000 revisions and 500 comments, and hitting the limit fails visibly rather than overwriting history.
Report language is templatized: approved wording is searchable by title, category, or severity, users can propose templates, and administrators curate and approve them. Critically, applying a template creates an independent engagement finding with empty observations, affected hosts, and evidence — a design decision that prevents the classic reporting failure of accidentally inheriting another engagement's proof material. Evidence handling shows similar care: up to four PNG/JPEG images can be uploaded or pasted together, are decoded, stripped of metadata, resized to at most 2000 × 2000 pixels, and saved as PNG. The README explicitly warns operators to keep original forensic evidence separately if original bytes or metadata matter, which is the correct guidance for anything that might end up in dispute.
The review workflow enforces separation of duties: findings move from Draft or Changes Requested to Ready, and an assigned reviewer or administrator — other than the current author — must approve or request changes. Any change to text, evidence, or a restored revision clears approval, forcing re-review. Administrators assign reviewers, and the review queue, comments, readiness checklist, and revision history support hand-off between operators. This mirrors how mature consulting shops already operate, but encodes it in the application's permission model rather than in tribal knowledge and shared drives.
PDF issuance is where integrity guarantees get interesting. Draft PDFs are visibly marked; only administrators can issue a final PDF, and every selected finding must be approved and pass readiness checks. Each issued version stores its PDF, an explicit content snapshot, and a SHA-256 digest — later edits do not regenerate it, so what a client received remains verifiable. The README is honest about the limits: the digest detects accidental corruption, not malicious tampering by a database administrator, and it is not a digital signature. Issuance is capped at 50 versions per engagement and 1 GB of issued PDFs application-wide, with per-user rate limits and a single admitted PDF render per application process.
Scanner imports are a standout feature for teams drowning in tool output. The application accepts exports from Burp Suite (Issues XML), Nessus/Tenable v2 XML, Nmap XML, OpenVAS/Greenbone native XML or GMP get_reports_response, OWASP ZAP traditional JSON, Nuclei JSON Lines, Qualys scan-result XML, and SARIF producers like Semgrep and CodeQL. Imports are preview-and-confirm only, never execute scans, never contact targets, and never fetch or execute referenced URLs, HTML, or embedded remote images — the README states this flatly. Imports are limited to 2 MB and 500 findings, everything arrives as Draft requiring operator review, and unknown export layouts fail visibly rather than being silently treated as success. Nmap open ports become informational observations, not inferred vulnerabilities, and server-side fingerprinting deduplicates against existing findings in the same engagement.
The security architecture section reads like a checklist against the OWASP Top 10:2025, and the README maps each item — access checks (A01), private no-store responses for confidential PDFs and existing CSP/CSRF controls (A02), pinned dependencies and CI (A03), session and secret protections with report integrity checks (A04/A08), inert Markdown/XML processing and parameterized database access (A05), bounded processing and independent review (A06), live database-backed session checks (A07), content-free audit events (A09), and transactional changes with cleanup on failure (A10). The authors are refreshingly explicit that this is not a compliance certification and that production still requires HTTPS, protected database and backup storage, and operational monitoring.
Session and network posture details reveal further hardening. Login uses a dedicated same-origin URL-encoded route with a 4 KB streaming limit before authentication or database work is performed. Next.js Server Actions share a single 25mb body size limit in next.config.ts. The TRUST_PROXY variable exists specifically to prevent header spoofing: when unset, forwarded headers are ignored entirely and login falls back to a higher one-minute shared budget so a single client cannot impose a 15-minute global lockout. A migration (20260906194500_add_revocable_sessions) moves the app to server-backed session IDs, invalidating legacy cookies on upgrade.
Verification is unusually rigorous for a tool in this category. Beyond npm test, npm run lint, npx tsc --noEmit, npm run build, and npm audit, the project ships dedicated database regression tests against an isolated reporting_tests database, plus a Playwright browser suite that starts its own loopback development server on port 3317 with a test-only session secret. The browser suite explicitly tests draft privacy, conflicting edits, evidence upload, independent review, PDF permissions and immutability, and template creation without JavaScript. Integration tests exercise real transactional conflicts and rollback rather than mocking them away.
Operational deployment is well covered: an automated Ubuntu setup.sh, manual setup instructions, pg_dump/pg_restore-based backup and restore with strict archive entry and size validation, and a production checklist. The .env file carries DATABASE_URL and a JWT_SECRET that must be at least 32 characters, with the application refusing to start in production without it. Backup automation uses an owner-only temporary pgpass file so the database password never appears in subprocess arguments — a small detail that tells you the authors think like attackers when designing defenses.
For defenders and blue teams, engagement-mgr is interesting precisely because of what it is not: it performs no reconnaissance, no scanning, and no exploitation. It is purely a documentation and workflow layer, which makes it useful not only to offensive consultancies but arguably to internal security teams who want structured, review-controlled vulnerability reporting with evidence sanitization and immutable issuance. A managed detection team that finds this on a consultant's workstation is looking at an operations log, not an attack tool.
The project's fit in the ecosystem is clear: it occupies the space between ad-hoc Markdown reports scattered across a shared drive and heavyweight commercial platforms. Its DejaVu fonts are bundled in assets/fonts with redistribution handled, migration is additive, and existing databases are explicitly not to be reset. For authorized assessment teams wanting a self-hosted, security-conscious, opinionated reporting pipeline — with the operator hygiene of independent review, template curation, and digested final artifacts baked in — engagement-mgr is one of the more thoughtful open-source entries in this niche.
leebaird/engagement-mgr.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.