Self-Hosting a Free Pentest Reporting Tool

Our reporting tool is Pental’s reporting on its own: findings and sections your way, AI on your own key, the built-in PDF and your own Word templates. It is free and open source under the GNU AGPL-3.0, and it runs on a computer of yours beside its own PostgreSQL database, so nothing is sent to Pental. This guide installs it, shares it with your team, and keeps it up to date and backed up. The reporting tool’s page shows it, and from finding to Word report takes a whole engagement through it.

What you need

Docker. On a Mac or a Windows PC that is Docker Desktop, opened once before you install and taken on to its main screen: it does not start until you accept its terms and skip signing in or create an account. On Linux it is Docker Engine, and where it is missing the installer offers to set it up with Docker’s own installer. One computer is enough for one person; for a team, use one that stays on, such as an office machine or a small server.

Install it

irm https://pental.io/report/install.ps1 | iex

curl -fsSL https://pental.io/report/install.sh | sh

The installer checks Docker, downloads the latest release, makes your settings with new secrets and starts the app beside its own PostgreSQL. On a desktop it then opens your browser on the first-run page with the setup code filled in; on a server it prints the address and the code. The code is also SETUP_TOKEN in the .env file in the folder it installed to: ~/pental-report, or /opt/pental-report when run as root, unless you chose another with --dir.

On the first-run page you name your firm, make the first administrator account and set up your authenticator app, and you are in. Your logo, colours and theme are under Settings, Branding.

Full size

Corvane SecurityIn our free reporting toolA demonstration: Corvane Security and its client are invented. Every screen is the real software.Drag sideways to see the whole screen.

Share it with your team

As installed, it is for the computer it runs on. Two installer options share it with your team, each over HTTPS:

& ([scriptblock]::Create((irm https://pental.io/report/install.ps1))) -Tailscale

curl -fsSL https://pental.io/report/install.sh | sh -s -- --tailscale

Sign the computer in to Tailscale first; on Linux the installer does it for you. The first time, Tailscale may ask you to turn on HTTPS for your tailnet, and shows the link. Already installed for one computer? Run the same command and it is shared, with your data as it is. Either way, the address your team types is PUBLIC_URL in .env: the links the app hands out to set a password are made with it, and a security key works only at that one address.

Add your team

Under Team, Add User adds a colleague, who chooses a password from a setup link and sets up a second factor: an authenticator app, or a security key or passkey once the app is served over HTTPS. There are three roles, administrators, senior testers and testers, and row-level security in PostgreSQL checks every read and write against the person’s role and a recent second factor. Under Settings, Security you choose which second factors are allowed or require both, when people prove it again and how long a session lasts, and see the active sessions.

Full size

Corvane SecurityIn our free reporting toolA demonstration: Corvane Security and its client are invented. Every screen is the real software.Drag sideways to see the whole screen.

Keeping it up to date

On macOS and Linux the installer asks whether to keep the app up to date by itself, and yes is the answer it takes if you just press Enter. It sets up a small updater on that computer, run by a systemd timer on Linux and a launchd agent on macOS, which asks the app every minute whether there is anything to install. A new release then installs overnight, between 1am and 6am on that computer’s clock, or straight away when an administrator presses Update Now.

• Before each update the updater copies the database to backups/ in the app’s folder, and keeps the last three.
• It installs the release from its own tag on GitHub, and if the new version does not start, it puts the one before it back.
• What it did is in update.log, and in Settings, Updates, where automatic updates can be turned off: a release then installs only when you press Update Now.

On Windows, or installed with --no-auto-update, there is no updater. The app tells its administrators when a release is out, and Settings, Updates gives the command that updates that computer, ready to copy: the install command again, which keeps your settings and your data as they are. Either way, the app brings its database up to date when it starts.

Backups

The simplest is in the app: Settings, Data, Back Up Your Data downloads one file with your records and uploaded files, which the tool or Pental can restore. From the server, in the app’s folder:

docker compose exec -T db pg_dump -U postgres report > report-$(date +%F).sql

Keep .env with your backups. VAULT_KEY in it seals the server’s signing keys in the database, and the server will not start on a copy of the database without it.

Where your data goes

If you are locked out

An administrator makes a colleague a new password link from Team, and resets a lost authenticator there too. When the person locked out is the only administrator, whoever runs the server does it, in the app’s folder:

# A link to choose a new password (it works once, for an hour)
docker compose exec report node server/bin/password-link.js you@yourfirm.com

# Clear a lost authenticator or security key: a new one is set up at the next sign-in
docker compose exec report node server/bin/reset-mfa.js you@yourfirm.com

When you want more than reporting

The tool is the reporting. When you want clients signing in to a portal of their own, QA before anything goes out, encrypted credentials and the rest, moving from the free reporting tool to Pental takes everything across in one file. What running any reporting server yourself takes is counted in what open-source pentest reporting costs.