404reportor is a CLI tool that takes your messy pentest notes and screenshots, and turns them into clean, professional HTML / PDF / Markdown reports. Works great for HTB, CTF, OSCP, CPTS labs, or real pentests.

It uses Google Gemini or Anthropic Claude to write the report for you. No API key? No problem — it works offline too with a built-in fallback.

What You Get

• 🎨 Beautiful dark/light HTML reports with sidebar navigation, code copy buttons, scroll progress, severity badges, and image lightbox
• 🤖 AI-powered writing — feeds your notes to Gemini/Claude and gets back a professional 0xdf-style writeup
• 📸 Screenshot analysis — AI reads your screenshots and categorizes them (recon, exploit, privesc, proof)
• 🔒 Auto-redacts passwords and flags in the final report
• 📄 Multiple formats — HTML, PDF, or raw Markdown
• 🖨️ Print-ready — clean print styles built in

Quick Start

Run Without Installing (npx)

npx 404reportor init

This creates the workspace files. Now:

1. Write your notes in main.md — just dump your writeup, commands, outputs, everything
2. Drop screenshots in the img/ folder
3. Generate the report:

npx 404reportor run --format html

That's it. Open the .html file and you're done.

Install Globally

npm install -g 404reportor

Then use 404reportor instead of npx 404reportor everywhere.

Using AI (Free)

By default 404reportor tries to use AI to rewrite your notes into a proper report. To set it up:

cp .env.example .env

Open .env and paste your free Google AI Studio API key:

GEMINI_API_KEY=your_key_here

Get a free key at aistudio.google.com

That's it. Run the tool and it'll use Gemini to generate the report.

If no API key is set, 404reportor will automatically fall back to a local report generator.

Using Anthropic Claude Instead

RECON_REPORT_PROVIDER=anthropic
ANTHROPIC_API_KEY=your_key_here

How to Write Your Notes (main.md)

Just write naturally. The parser picks up commands, outputs, credentials, services, CVEs, and flags automatically. Here's a quick example:

TARGET: 10.10.11.42
MACHINE: Cascade
OS: Windows
DIFFICULTY: Medium

# Recon

nmap -sC -sV 10.10.11.42
22/tcp   open  ssh     OpenSSH 7.4
80/tcp   open  http    Apache 2.4.18
445/tcp  open  smb     Samba 4.7.6

# Web Enumeration

gobuster dir -u http://10.10.11.42 -w /usr/share/wordlists/dirb/common.txt
Found: /admin (302)
Found: /uploads (200)

# Initial Access

Used SQLi on login page to get shell as www-data.
password: SuperSecret123

# Privilege Escalation

sudo -l shows we can run /usr/bin/vim as root.

# Proof

user.txt: abc123def456
root.txt: 789xyz000111

The tool understands metadata lines (TARGET:, OS:, etc.), headings, shell prompts, common tools (nmap, gobuster, evil-winrm, etc.), and credential patterns.

Screenshots

Drop screenshots in img/. Supported formats: .png, .jpg, .jpeg, .gif, .webp, .bmp

You can organize them in subfolders:

img/
  01-nmap.png
  exploit/02-shell.png
  privesc/03-root.png

Want captions? Create img/captions.txt:

01-nmap.png: Initial Nmap scan showing exposed services.
exploit/02-shell.png: Got shell as www-data.

All Commands

| Command | What It Does | |---------|-------------| | 404reportor init | Creates main.md, img/, .env in current folder | | 404reportor setup --provider google | Set up AI provider config | | 404reportor run | Parse notes → AI generate → render report | | 404reportor --help | Show all options |

Run Options

| Flag | Description | Default | |------|------------|---------| | -f, --format | html, pdf, or md | html | | -t, --type | htb, ctf, pentest, cpts, oscp | pentest | | --provider | auto, google, anthropic | auto | | --model | AI model name | auto | | --save-md | Save markdown draft alongside HTML/PDF | off | | -i, --input | Notes file path | main.md | | --img-dir | Screenshots directory | img | | -o, --output | Output directory | . |

Examples

# HTB writeup with AI
npx 404reportor run --type htb --format html

# OSCP-style PDF report
npx 404reportor run --type oscp --format pdf

# Save the markdown draft too
npx 404reportor run --type ctf --format html --save-md

# Use Claude instead of Gemini
npx 404reportor run --provider anthropic --format html

Output Formats

• HTML — Self-contained file with everything embedded (CSS, images, JS). Has dark/light mode, sidebar TOC, code copy buttons, image lightbox, and severity badges. Just open it in any browser.
• PDF — Rendered from HTML using Puppeteer. If Chrome isn't installed:

  npx puppeteer browsers install chrome

• Markdown — Raw AI-generated draft (use --save-md).

Security Note

Your notes might have real passwords, hashes, or flags. The tool auto-masks these in the output. But if you use AI mode, your notes are sent to Google/Anthropic servers. If you're working with sensitive client data, don't set an API key — the tool will use its local report builder instead.

Contributing

PRs welcome! Fork → branch → commit → PR.

git clone https://github.com/Hacck3y/404reportor.git
cd 404reportor
npm install
npm link

License

MIT © 2025-2026