Evidence-First Pentest Logger — Capture every command, find anything, prove everything.
High-fidelity terminal logs with AI analysis, searchable content, interactive timelines, and compliance-ready reports. Built on ttyrec.
Perfect for Real-World Engagements, Compliance & Audits, OSCP, and HackTheBox.
Quick Start • Features • Commands • Install • Docs • Contributing
Using script, tmux, or basic shell redirection during pentests creates fragmented, unsearchable, unmaintainable evidence:
- 🔴 Lost commands — Mixed with noise, impossible to extract context
- 🔴 No integrity — How do you prove logs weren't tampered with?
- 🔴 Manual reports — Hours spent copying/pasting into documents
- 🔴 Evidence gaps — ANSI codes, terminal artifacts, overwrites break readability
- 🔴 Compliance nightmares — No audit trails, no encrypted archives
- ✅ Evidence-First Design — Every command + output captured with perfect fidelity using Virtual Terminal Emulator (handles colors, overwrites, redraws—what you see matches what happened)
- ✅ Context & Metadata — Automatic timestamps, operator tracking, client/engagement organization from day one
- ✅ Searchable Everything — Find any command across all sessions with regex + boolean operators in seconds
- ✅ Compliance-Ready — Integrity hashes, AES-256 encrypted archives, detailed audit trails
- ✅ Reports in Minutes — Auto-generate Markdown/HTML with AI-powered summaries (no manual copy/paste)
- ✅ No Root Required — Works as normal user; logs land safely in
~/.pentlog/ - ✅ Interactive Workflows — Intuitive TUI for engagement creation, phase switching, searching, and notes
- ✅ Replayable — Faithful session playback with
ttyplaypreserves exact timing - ✅ Integrity Protection —
pentlog freezegenerates SHA256 hashes for evidence packaging
# 1. Install (macOS/Linux) — ~30 seconds
curl -sSf https://raw.githubusercontent.com/aancw/pentlog/main/install.sh | sh
# 2. Setup (one-time) — Verify dependencies
pentlog setup
# 3. Create engagement — Interactive wizard
pentlog create
# 4. Start recording — Shell with ttyrec running
pentlog shell
# → You now have high-fidelity logs in ~/.pentlog/logs/
# → Logs are indexed in SQLite, ready to search
# 5. Search logs — Find commands across all sessions
pentlog search
# 6. Export report — Generate Markdown/HTML for client
pentlog exportWhat you get after 5 minutes:
- ✅ Searchable terminal logs with perfect fidelity (ANSI colors, overwrites, etc.)
- ✅ Timestamped commands organized by Client → Engagement → Phase
- ✅ Compliance-ready HTML reports with AI summaries
- ✅ Encrypted archives for secure client delivery
| Feature | Why It Matters |
|---|---|
| 🎬 High-Fidelity Recording | Every keystroke + output captured with perfect terminal accuracy (ANSI colors, overwrites, redraws preserved) |
| 🔍 Interactive Search | Find any command across all sessions instantly with regex and boolean operators—no more grep chaos |
| 📊 Virtual Terminal Emulator | What you see in the viewer is exactly what you saw in your shell (unlike script or tmux which break on special chars) |
| 💾 Compliance-Ready Export | Generate Markdown/HTML reports with AI summaries, integrity hashes, and encrypted archives in seconds |
| 📝 Automatic Context | Every command timestamped and organized by Client → Engagement → Phase—no manual naming or organizing |
| Feature | Description |
|---|---|
| 🤖 AI Analysis | Summarize findings with Google Gemini or Ollama (local LLM) |
| 🎯 Timeline Extraction | Interactive timeline browser to reconstruct your attack sequence |
| 📌 Notes & Bookmarks | Add timestamped annotations to sessions for later review |
| ⌨️ Quick Hotkeys | Ctrl+N for notes, Ctrl+G for vulns during shell sessions |
| 🔄 Full Replay | Faithful playback with ttyplay preserves exact timing |
| 🛡️ Crash Recovery | Protect evidence from SSH disconnects, OOM kills, and unexpected crashes |
| 📡 Live Share | Share terminal sessions in real-time via browser with dark-themed viewer |
| 🔐 AES-256 Archive | Password-protected encrypted archives for secure client delivery |
| Command | Description |
|---|---|
| Session Management | |
create |
Initialize a new engagement context (Interactive) |
shell |
Start a recorded shell with the engagement context loaded |
shell --share |
Start a recorded shell with live browser sharing enabled |
share |
Share a live or recorded session for read-only viewing |
sessions |
List and manage recorded sessions |
switch |
Switch to a different pentest phase |
| Analysis & Search | |
search |
Search command history across all sessions (Regex & Boolean) |
timeline |
Interactive browser for command timeline extraction |
dashboard |
Show an interactive dashboard of your pentest activity |
note |
Manage session notes and bookmarks |
| Reporting | |
export |
Export commands for a specific phase (Markdown/HTML) |
analyze |
Analyze a report with an AI provider to summarize findings |
vuln |
Manage findings and vulnerabilities |
| Data Management | |
archive |
Archive old sessions with optional encryption |
import |
Restore archived sessions back into pentlog |
freeze |
Generate SHA256 hashes of all session logs for integrity |
gif |
Convert sessions to animated GIF (720p/1080p) |
serve |
Start HTTP server to view HTML reports with GIF players |
recover |
Recover and manage crashed or stale sessions |
| Utilities | |
replay |
Replay a recorded session with full fidelity |
status |
Show current tool and engagement status |
setup |
Verify dependencies and prepare local logging |
reset |
Clear the current active engagement context |
completion |
Generate auto-completion scripts for Zsh and Bash |
update |
Update pentlog to the latest version automatically |
- Go 1.24.0+ (if building from source)
- ttyrec (terminal recording tool)
- ttyplay (optional, for session replay)
curl -sSf https://raw.githubusercontent.com/aancw/pentlog/main/install.sh | sh
pentlog setup # One-time dependency check and setupgit clone https://github.com/aancw/pentlog.git
cd pentlog
go build -o pentlog main.go
# Or cross-compile for Linux
GOOS=linux GOARCH=amd64 go build -o pentlog main.goAutomatic (recommended):
pentlog setup # Auto-installs on macOS, Ubuntu, Fedora, AlpineManual Installation:
- macOS:
brew install ttyrec - Ubuntu/Debian/WSL:
sudo apt-get install ttyrec - Fedora:
sudo dnf install ttyrec - Alpine:
sudo apk add ttyrec
- Password-Protected Archives: Use interactive mode (
pentlog archive) instead of--passwordflag to avoid storing passwords in shell history - Database Permissions: Sensitive files are created with 0600 permissions automatically
- Evidence Integrity: Use
pentlog freezebefore archiving for compliance audits
| Feature | script |
tmux |
PentLog |
|---|---|---|---|
| Terminal Fidelity | ❌ Breaks on special chars | ✅ Perfect (Virtual Terminal Emulator) | |
| Searchable Logs | ❌ Manual grep chaos | ❌ Session-by-session only | ✅ Full-text search + regex + boolean operators |
| Automatic Organization | ❌ Manual naming | ❌ Manual naming | ✅ Client → Engagement → Phase auto-organized |
| Timestamps | ❌ No timestamps | ✅ Every command timestamped | |
| Compliance Ready | ❌ No integrity | ❌ No integrity | ✅ Hashes + encryption + audit trails |
| Replay | ❌ No timing info | ✅ Faithful playback with ttyplay |
|
| Reports | ❌ Manual copy/paste | ❌ Manual copy/paste | ✅ Auto-generate Markdown/HTML + AI summaries |
| Database | ❌ Just files | ❌ Just files | ✅ Indexed SQLite for fast searching |
| Root Required | ❌ Works as user | ✅ Works as normal user | |
| Live Sharing | ❌ Not supported | ❌ Not supported | ✅ Real-time browser viewer with scrollback |
| Crash Recovery | ❌ Logs lost | ✅ Protected from SSH/OOM crashes |
- Quick Start Guide - Set up and run your first engagement
- User Guide - Deep dive into all commands and features
- Modes Guide - Client Mode vs. Exam/Lab Mode vs. Log-Only Mode
- AI Analysis Setup - Configure Gemini or Ollama for report summarization
- Export & Reporting - Generate Markdown and HTML reports
- Archiving & Encryption - Create encrypted evidence packages
- Roadmap - Implemented features and future plans
- Changelog - Version history and improvements
- Contributing - Help us improve PentLog
Problem: Client demands evidence of every command. Your manual notes + tmux logs are a mess.
Solution:
- Auto-capture everything with perfect terminal fidelity
- Organize by Client → Engagement → Phase automatically
- Export compliance-ready HTML reports with AI summaries in minutes
- Archive with encryption for secure client delivery
Problem: Regulators need tamper-proof logs, audit trails, and encryption. Your shell history isn't enough.
Solution:
- Generate integrity hashes with
pentlog freezebefore archiving - Encrypt sessions with AES-256 for secure evidence packaging
- Maintain detailed audit trails with timestamps and operator tracking
- Create audit-ready reports with searchable content
Problem: Need to document every step for writeups. Fighting with formatting and missing commands.
Solution:
- Search across all sessions to find any command instantly
- Export clean Markdown reports with proper formatting
- Perfect terminal fidelity means what you see is what you get
- Timeline browser helps reconstruct your attack flow
Problem: Need reproducible, timestamped terminal sessions for analysis and playback.
Solution:
- Record sessions with precise timing for faithful
ttyplayreplay - Extract command timelines for detailed activity analysis
- Search across historical sessions for patterns and techniques
- Generate GIF recordings for documentation and presentations
We welcome contributions! Start by checking:
- Roadmap - See what's planned
- Contributing Guide - Review guidelines
- Open Issues - Find items to work on
- roomkangali - AI Summary feature & logo design
- ttyrec/ttyplay authors - Underlying recording technology
- Go community - Bubble Tea, Cobra, and other excellent libraries
MIT License - See LICENSE for details.
- 📖 Documentation: docs/wiki/Home.md
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- ⭐ Star us on GitHub if you find PentLog useful!
Made for professionals. Evidence-first. No compromises.
