tmux panes
      │
      ▼
  raw bytes ──────────────────────────────►  raw/pane-000003.log
      │                                       authoritative · never parsed
      │ terminal emulation
      ▼
  segments  ◄── byte-addressable, immutable
      │
      │ LLM (local by default)
      ▼
  observations  ◄── append-only, every fact cites its source
      │
      │ deterministic rebuild
      ▼
  entities · relationships · auth log
      │
      ├──────────────► Obsidian vault   (a projection, not the store)
      │
      └──────────────► pentest-mcp ────► Claude Code · Codex · any MCP agent

git clone git@github.com:lucianoengel/pentest-mcp.git
cd pentest-mcp
./install.sh

cd pentest-mcp
git pull
./install.sh

pentest-recorder init inlanefreight --client "ACME" --scope "172.16.119.0/24"
tmux new -s inlanefreight
pentest-recorder start

pentest-recorder status                  # what is — and is NOT — being captured
pentest-recorder search 'Summer2026!'    # find the exact string, across everything
pentest-recorder pause                   # stop capturing, right now
pentest-recorder sync                    # extract, rebuild, export

claude mcp add pentest -- ~/.local/bin/pentest-mcp --engagement inlanefreight

// list_entities(type="credential", filter={"validated": false})
{
  "items": [{
    "id": "credential:INLANEFREIGHT/svc_backup:password:HolyMoly123!",
    "type": "credential",
    "data": {
      "username": "svc_backup",
      "domain": "INLANEFREIGHT",
      "secret": "HolyMoly123!",      // exact, never normalized
      "secret_type": "password",
      "status": "unvalidated"
    },
    "fact_type": "CONFIRMED",
    "observation_count": 1
  }],
  "total": 1
}

// get_provenance(entity_id="credential:INLANEFREIGHT/svc_backup:...")
{
  "observations": [{
    "kind": "credential",
    "source": "extraction",
    "actor": "ollama/qwen2.5-coder:7b",
    "verified": true,                 // appeared verbatim in the source
    "segment_ids": [1]
  }],
  "segments": [{
    "id": 1,
    "terminal": "inlanefreight:2.1",
    "ts_start": "2026-08-26T14:32:11+00:00",
    "command": "cat /mnt/backup/scripts/backup.ini",
    "cwd": "/home/kali/eng",
    "raw_path": ".../raw/pane-000003.log",
    "byte_start": 0,
    "byte_end": 125                   // the original bytes, still on disk
  }]
}

// get_engagement_summary()
hosts: 2 · services: 1 · identities: 1
credentials: 2  (1 unvalidated)
auth: 1 successful, 1 failed
findings: 1 candidate · open tasks: 0
hosts_with_no_service_recorded: 1     ← DC01 is under-enumerated
entities_with_unverified_fields: 0
segments: 1  (1 pending extraction)

$ nc -lvnp 4444                    ← the only local command that ever runs
connect to [10.10.14.7] from (UNKNOWN) [172.16.119.30] 51422
C:\inetpub\wwwroot> type web.config
  <add name="prod" connectionString="...;Password=P@ssw0rd#2026;" />
                                   ↑ captured, extracted, attributed to nothing

Engagement:  inlanefreight  (client: ACME)
Recorder:    running (pid 48213) since 2026-08-26T13:58:02+00:00
tmux server: 347338
Capturing:   3 pane(s)
     %1  inlanefreight:1:recon.0  (0 B buffered)
     %4  inlanefreight:2:ad.0     (2145 B buffered)
     %7  inlanefreight:3:shell.0  (0 B buffered)

NOT capturing 2 pane(s) in scope:
     %9  inlanefreight:5:agent.0  -- window excluded by configuration
    %11  inlanefreight:4:web.0    -- already piped by another tool; left untouched

Segments:    184 total, 3 pending, 181 extracted, 0 failed
Extraction:  ollama / qwen2.5-coder:7b
  Local provider: no engagement data leaves this machine.

~/.local/share/pentest-recorder/engagements/inlanefreight/
├── engagement.db     one ordinary SQLite file — the canonical store
├── raw/              exact terminal bytes, rotated and gzipped
└── evidence/

sqlite3 engagement.db \
  "SELECT json_extract(data,'\$.username'), json_extract(data,'\$.status')
   FROM entities WHERE type='credential';"

pentest-recorder init acme   --client "ACME"   --local-only
pentest-recorder init globex --client "Globex" --local-only

pentest-recorder purge -e acme --include-vault

svc_qualys::INLANEFREIGHT:1122334455667788:AB12…:0101…
└────┬────┘  └─────┬─────┘
  username      domain        ← both are part of the value

[SMB] NTLMv2-SSP Hash : svc_qualys::INLANEFREIGHT:1122334455667788:<Ta1b2c3d4:1>
                        └──────────── kept, so the model can attribute it ────┘

Extraction is configured to use openai (gpt-4o-mini) at
  https://api.openai.com/v1

This sends captured terminal output to that service. In a penetration
test that includes, in full and unredacted:
  - plaintext passwords, password hashes, tokens and API keys
  - usernames, domains, internal hostnames and IP addresses
  - file contents, share names and command output
  - vulnerability evidence and client-identifying data

There is no redaction option: extracting a secret requires sending it.

pentest-recorder init acme --local-only

# Credentials

| Identity | Secret | Type | Validated on | Source |
|---|---|---|---|---|
| INLANEFREIGHT\fiona     | `Summer2026!`  | Password | SMB FILE01 | Segment 1 |
| INLANEFREIGHT\svc_backup| `HolyMoly123!` | Password | Not yet    | Segment 1 |

[data]
root = "~/.local/share/pentest-recorder"

[obsidian]
vault_path = "~/Obsidian/Pentests"
include_secrets = "include"        # include | redact | partial

[tmux]
session = "@engagement"            # or a glob such as "client-*"
exclude_windows = ["agent"]

[capture]
idle_flush_seconds = 3.0
max_segment_bytes = 65536
rotate_bytes = 134217728

[extraction]
rules = true                       # derive facts the text determines
redact = true                      # replace long tokens before prompting
collapse = true                    # collapse repeated lines
route = true                       # skip segments carrying nothing new
escalation_model = ""              # optional stronger model for hard cases

[llm]
provider = "ollama"                # ollama | openai | openai-compatible
model = "qwen2.5-coder:7b"
base_url = "http://127.0.0.1:11434"
api_key_env = "OPENAI_API_KEY"     # names the variable, never holds the key

[mcp]
default_engagement = ""

source /path/to/pentest-mcp/shell/pentest-recorder.sh

python -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/python -m pytest tests/ -q
.venv/bin/ruff check src tests bench

tests/test_capture.py       capture, segmentation, rotation, pause, restart
tests/test_normalize.py     terminal emulation, both implementations
tests/test_extract.py       the extraction contract and the verbatim guard
tests/test_derive.py        union-find correlation, merges, corrections
tests/test_mcp.py           tool surface, bounds, attribution
tests/test_acceptance.py    end-to-end rehearsal in real tmux
tests/test_passivity.py     proves the recorder never touches a target