Read me first

A plain-language introduction to this software: who it is for, what it does, and how to get going with it. No technical background assumed. If a term is unfamiliar, check the glossary near the end.

---

1. Who this is for

This is built for a security testing firm — a consultancy, a managed security provider, or an in-house team that tests its own organisation's systems.

Four kinds of people use it:

• Testers and analysts do the hands-on work. They record what they found, score how serious it is, and attach the proof. They are in the tool daily and it is designed around them first.
• Engagement leads keep an eye on progress across jobs, and produce the reports that go to clients.
• Administrators decide who is on the team and what each person may see.
• Clients — the organisations being tested — get a read-only view of their own results, and nothing else.

2. What it does

Security testing produces findings: "this system has this weakness, here is the proof, here is how serious it is, here is how to fix it." A firm may have dozens of these in flight across several clients at once.

This software is where that work lives. It holds the jobs, the findings, the evidence, and the reports, and it tracks each finding from first discovery through to confirmed fix. It replaces the spreadsheets and shared documents that firms otherwise end up using.

3. The domain, briefly

Penetration testing is authorised, deliberate attempts to break into a system in order to find weaknesses before someone hostile does. A client hires a firm, agrees exactly what may be tested and when, and receives a report of what was found.

The work is bound by conventions this software follows:

• Severity is scored, not guessed. The industry standard is CVSS — a formula that turns the characteristics of a weakness into a number and a band from informational up to critical. This tool uses CVSS version 4.0 and records the full working, so a rating can be defended when a client questions it.
• Findings are classified against public catalogues. CWE names the type of weakness, CVE names a specific known vulnerability, and MITRE ATT&CK describes the techniques an attacker uses. Speaking these languages lets a client's own tooling line up with your report.
• Testing follows a published method. OWASP, PTES and NIST SP 800-115 are the common ones. Saying which you used is part of the deliverable.
• Evidence matters. A finding without proof is an opinion.

4. Where it fits

The software is single-tenant: one installation serves one firm. Your data sits in your own deployment rather than sharing a system with other firms. For work this sensitive, that separation is often a requirement rather than a preference.

It expects to sit alongside:

• Your identity provider. Staff sign in with your existing company accounts through standard single sign-on, rather than yet another password to manage.
• Your scanning tools. Output from common scanners can be imported so machine-found issues start in the same place as hand-found ones.
• Your clients. They get the portal rather than an emailed spreadsheet.

5. Your very first run

The quickest way to see it is the preview image — a self-contained package containing the software and a fully populated example firm. Nothing to configure and nothing to connect.

docker run --rm -p 8080:8080 pentest-management-core:preview

Then open http://localhost:8080.

You will find a fictional firm, "Northwind Security", with four clients, four engagements in different stages, and a dozen findings complete with evidence and reports. Click into a finding, look at how it is scored, open the remediation board, and try the client portal. None of this data is real — it exists so you can judge the software with something realistic in front of you.

See preview/README.md for options such as choosing a different port or keeping data between restarts.

6. Setting up for real

When you move past evaluating:

1. Deploy your own instance. One deployment, your firm, your data. See production-setup.md.
2. Initialise it. A first-run script creates the essentials — your organisation, the first administrator, roles, and reference data — and nothing fictional. It is deliberately guarded, because it clears the database first: it refuses to touch a database that already has data unless you explicitly force it, and asks you to confirm by typing the destination name.
3. Connect your sign-on. Point it at your identity provider so staff use their normal company accounts.
4. Add your team. Invite people and give each a role. Restrict analysts to named clients where that is appropriate — the restriction is enforced by the server, not merely hidden from view.
5. Add your clients and their systems. For each client, record the hosts and applications you will be testing.

7. Day to day

A typical engagement runs like this:

1. Set it up. Create the engagement for the client, choose the method, and agree the scope — precisely which systems are in bounds.
2. Move it to scoping, then to in-progress. Statuses follow a fixed order; the software will not let a job skip ahead.
3. Record findings as you go. Title, what it is, what it means, how to reproduce it, how to fix it. Attach the evidence while it is in front of you. Score it with CVSS. Use the library for weaknesses your firm has written up before, so the wording stays consistent.
4. Confirm them. A finding starts as a draft. Confirming is a deliberate step — that is the point at which you stand behind it.
5. Generate the report for the client, from the findings already recorded. Nothing is retyped.
6. Track the fixes. As the client remediates, record retests. A successful retest moves the finding to verified-fixed and it leaves the open queue.

8. Ongoing care

• Watch the open findings. The dashboard leads with what is still outstanding, by severity. That is the number that should be trending down.
• Keep the library current. Every write-up worth reusing saves time later.
• Review who has access, especially after people join or leave.
• Back up the database. Findings and evidence are kept indefinitely by default and removed only by deliberate administrator action. The audit history is always retained.
• Retest before closing. A finding is not fixed because the client says so; it is fixed because a retest confirmed it.

---

Glossary

Term	Meaning
Engagement	One piece of testing work for one client, with agreed scope and dates.
Finding	A single weakness discovered, with its evidence, severity and fix.
Scope	Exactly which systems may be tested. Working outside it is a serious matter.
Asset	A thing that can be tested — a server, an application, a service.
Evidence	Proof a finding is real: a screenshot, a captured request, a log.
Retest	Checking a reported weakness after the client says it is fixed.
Remediation	The client's work to fix what was found.
CVSS	The standard scoring system for severity. This tool uses version 4.0.
CWE	A public catalogue of types of weakness.
CVE	An identifier for one specific, publicly known vulnerability.
MITRE ATT&CK	A public catalogue of techniques attackers use.
OWASP / PTES / NIST SP 800-115	Published testing methodologies.
Single-tenant	One installation serves one firm; data is not shared with others.
SSO	Signing in with your existing company account rather than a new password.
Audit log	An append-only record of every change. It cannot be edited or deleted through the application.

Who can do what

Role	Can do
Administrator	Everything, including managing people and access.
Tester	Record and score findings, attach evidence, record retests.
Analyst	As above, and may be restricted to named clients only.
Client viewer	Read-only, and only their own organisation's results.

Restrictions are enforced on the server. A restricted user cannot reach another client's data by searching for it or by guessing a web address.

The other documents here

Document	What it covers
production-setup.md	Preparing a real deployment for first use.
demo-data.md	The example data, and how to load or reload it.
../preview/README.md	Running the self-contained preview image.

Common questions

Is the demo data real? No. Northwind Security and its clients are invented. Nothing in the preview relates to a real organisation.

Can I start clean? Yes. The preview discards its data when it stops, so restarting gives you the original example back. For a real deployment, the initialisation script sets up an empty system with only the essentials.

Why can't I move an engagement straight to delivered? Statuses follow a fixed order on purpose, so the record of how work progressed stays truthful. The software offers only the transitions that are valid from where you are.

Someone can't see a client they should. Check their client restrictions under access management. Restricted users see only what they are assigned.

Do I have to use the AI features? No. They are assistive only, they are off unless configured, and everything works without them. Where AI does suggest something, a person must confirm it before it counts — AI never sets a severity or finalises anything a client sees.

What if I need it to do something it doesn't? That is expected. This is a core build meant to be extended — see below.

Where to get help

This application is a core build: it does its job, without any company's branding or house style, and it is meant to be adapted.

For help adapting it, for ideas about what it should do next, or to find people who can build it into something bespoke for your organisation, visit the community at wbsp.ai. Other versions of this application, and many others, have been built there — one may already be close to what you need.