pentest-recorder · pentest-mcp

Ihr Terminal ist das beste Protokoll eines Engagements, das Sie je haben werden. Dieses Tool macht es zu einem.

Zwei Stunden nach Beginn einer Bewertung haben Sie eine Domänenanmeldedaten, vier Hosts, eine Freigabe, die Sie lesen können – und keine Ahnung, in welchem Bereich Sie das gesehen haben. Also scrollen Sie. Oder Sie führen die Enumeration erneut aus. Oder Sie fügen alles von Hand in eine Notizdatei ein – und machen es morgen wieder.

pentest-recorder überwacht Ihre bestehende tmux-Sitzung, behält die exakten Bytes, die Ihr Terminal erzeugt hat, und verwandelt sie in strukturierten Engagement-Zustand. pentest-mcp reicht diesen Zustand an jeden MCP-kompatiblen Agenten weiter – damit er die Frage wo habe ich svc_backup's Passwort bekommen mit dem Segment, dem Bereich, dem Zeitstempel und den ursprünglichen Bytes beantworten kann.

Sie behalten Ihre VM, Ihr tmux, Ihre VPNs und Pivots, Ihre Aliase, Ihre Wortlisten. Nichts wird umhüllt. Nichts wird ersetzt.

  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

Dies ist kein autonomer Pentesting-Agent. Die Datenschicht hält Wahrheit und Gedächtnis; der Agent übernimmt das Denken. Der Recorder verbindet sich nie mit etwas, das Sie gescannt haben – durch einen Test erzwungen, nicht durch gute Absichten.

Installation

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

Python 3.11+, tmux und SQLite mit FTS5 – letzteres prüft der Installer, weil einige Distro-Pythons es weglassen. Kein Docker, kein Datenbankserver, keine Browser-Oberfläche. Insgesamt drei Drittanbieter-Pakete: pyte, httpx, mcp.

Aktualisieren

cd pentest-mcp
git pull
./install.sh

Den Installer erneut auszuführen ist das Update. Es baut aus dem Checkout neu auf, behält Ihre bestehende config.toml und lässt Engagement-Daten unangetastet. Wenn ein Engagement von einer älteren Version geschrieben wurde, wird sein Speicher beim nächsten Öffnen zum Schreiben migriert – pentest-recorder status meldet die Schema-Version und sagt es, wenn sie nicht übereinstimmen.

Stoppen Sie zuerst den Recorder, falls einer läuft (pentest-recorder stop), da ein laufender Daemon weiterhin den Code verwendet, mit dem er gestartet wurde.

Related MCP server: mcp-ssh-interactive

Verwendung

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

Dann arbeiten Sie normal weiter. Jeder Bereich in dieser Sitzung wird erfasst, einschließlich Bereichen und Fenstern, die Sie später öffnen.

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

Einen Agenten verbinden

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

Jetzt fragen Sie ihn Dinge.

welche Anmeldedaten habe ich, die ich noch nicht validiert habe?

// 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
}

woher kam dieses Passwort?

// 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
  }]
}

bring mich auf den neuesten Stand

// 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)

Diese Zusammenfassung ist der Index des Agenten. Deshalb gibt es kein list_unvalidated_credentials()-Werkzeug – die Zählungen sagen dem Agenten, welche Fragen es wert sind, gestellt zu werden, sodass zwölf Lese-Werkzeuge abdecken, was sonst dreißig erfordern würde.

Was es erfasst – und was es bewusst nicht erfasst

Es sieht in verschachtelte Sitzungen hinein. Eine gefangene Reverse Shell, ssh, evil-winrm, msfconsole, sqlplus. Dort liegt ein Großteil der guten Beweise, und genau das erreichen Shell-History-Werkzeuge nicht:

$ 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

Der Befehl, der es erzeugt hat, wird nur aufgezeichnet, wenn er wirklich bekannt ist. Innerhalb dieser Reverse Shell ist command nc -lvnp 4444 – wahrheitsgemäß – und exit_code bleibt leer, statt geraten zu werden.

Es stoppt, wenn Sie es sagen:

status listet jeden Bereich im Geltungsbereich auf, der nicht erfasst wird, mit dem Grund. Ein stillschweigend nicht überwachter Bereich ist der schlimmste Fehler, den dieses Tool haben kann, also ist er nie eine Fußnote:

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.

Wo Ihre Daten leben

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

Verzeichnisse 0700, Dateien 0600. Die Rohprotokolle sind das Sensibelste auf der Maschine – Klartext-Domänenanmeldedaten und Kundendaten liegen darin. Behandeln Sie dieses Verzeichnis wie Beute.

Alles ist mit gewöhnlichen Werkzeugen prüfbar. Ein Backup ist cp -r; ein Audit ist eine SQL-Abfrage:

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

Getrennte Engagements sind getrennt auf der Platte

Ein Verzeichnis und eine Datenbankdatei pro Engagement – keine gemeinsame Tabelle mit einem Filter. Zwei Kunden, die denselben RFC1918-Raum nutzen, bleiben zwei getrennte Entitätsmengen, und die Suche in der einen nach dem Passwort der anderen liefert nichts.

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

Jedes bindet an die tmux-Sitzung mit demselben Namen. Wenn zwei Recorder jemals auf einen Bereich zielen, weigert sich pipe-pane -o, den ersten zu verdrängen, und der zweite meldet den Bereich als nicht überwacht.

Am Ende eines Engagements:

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

Was das Modell erreicht

Drei Dinge liegen zwischen Erfassung und Modell, und jedes lässt sich unabhängig in [extraction] deaktivieren.

Fakten, die der Text bestimmt, werden ohne Modell abgeleitet. Eine Adresse, eine URL, ein UNC-Pfad, password=X und Anmeldedaten in erkannten Formaten – NTLMv2, Kerberos-Tickets, pwdump-Zeilen, JWTs, PEM-Schlüssel – werden direkt aus dem Text gelesen. Wo das Format das Konto trägt, wie es die meisten tun, stammt der Besitzer aus dem Wert selbst:

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

Gemessen an einem Korpus von neun Formaten: Der Regel-Durchlauf erholt 9/9 byte-identisch mit 9/9 korrekter Zuordnung; qwen2.5-coder:7b, gebeten, dieselben Werte zu transkribieren, schafft 6/9 und 5/9. Was es nicht tun wird, ist einen Wert zu erkennen, der nur wegen des Ortes, an dem ein Werkzeug ihn druckt, etwas bedeutet – microsoft-ds ist ein Dienst, weil nmap eine SERVICE-Spalte hat, und das bleibt die Aufgabe des Modells.

Lange Tokens werden ersetzt, bevor das Modell sie sieht. Was übrig bleibt, ist ein Platzhalter, seine Länge und Zeichenklasse sowie der gesamte umgebende Kontext:

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

Der Recorder setzt die echten Bytes zurück ein. Transkriptionsfehler hört auf, etwas zu sein, das erkannt wird, und wird etwas, das nicht passieren kann. Die Kennungen sichtbar zu halten, ist wichtig: Die gesamte Anmeldedaten zu verbergen senkt die Klassifikation auf 44 %, sie zu behalten hebt sie auf 78 % – besser, als dem Modell den Rohwert zu zeigen.

Wiederholung wird zusammengefasst und leere Segmente werden übersprungen. Identische Zeilen werden zu einer Instanz und einer Zählung, wobei jeder einzelne Wert erhalten bleibt. Ein Segment ohne Kandidaten und ohne Wert, den das Engagement nicht bereits kennt, wird nie gesendet – die Entscheidung betrifft unbekannte Werte, nicht Zeilenformen, denn mitten im Engagement ist jede Form vertraut und connected to \\SQL01\payroll würde sonst zusammen mit einem neuen Host und einer Freigabe verworfen. Übersprungene Segmente protokollieren den Grund und bleiben erneut verarbeitbar.

Die Zahlen dahinter stehen in bench/BASELINE.md.

Wenn Daten die Maschine verlassen

Die Extraktion benötigt ein Sprachmodell, und es gibt keine Schwärzungsoption – um ein Geheimnis zu extrahieren, müssen Sie das Geheimnis senden.

Der Standard-Provider ist also lokal (Ollama auf 127.0.0.1), und nichts verlässt Ihre Maschine, es sei denn, Sie ändern das. Wenn Sie einen Remote-Provider konfigurieren, sagt Ihnen start genau, was übertragen würde, und weigert sich, bis Sie es bestätigen:

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.

Für Kundenarbeit, bei der das vertraglich verboten ist:

pentest-recorder init acme --local-only

Dieses Engagement lehnt einen Remote-Provider dauerhaft ab, unabhängig davon, was die Konfiguration später sagt – und meldet die Ablehnung, während die Erfassung weiterläuft.

API-Schlüssel werden aus der Umgebung gelesen, benannt durch api_key_env in der Konfiguration. Der Schlüssel wird nie in die Konfigurationsdatei, Engagement-Daten, Protokolle oder exportiertes Markdown geschrieben.

Obsidian

Zeigen Sie obsidian.vault_path irgendwohin, und das Engagement wird in gewöhnliches Markdown projiziert – Dashboard, Hosts, Anmeldedaten, Befunde, Zeitachse und eine Notiz pro Host, mit Wikilinks verknüpft. Kein Plugin, und Obsidian selbst ist optional – das sind Textdateien; cat, grep und git funktionieren einwandfrei.

# Credentials

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

Der Vault ist eine Projektion, nicht der Speicher: Löschen Sie ihn, exportieren Sie erneut, verlieren Sie nichts. Generierte Dateien tragen generated_by: pentest-recorder-Frontmatter, und der Exporteur überschreibt niemals eine Datei ohne diesen Marker – er schreibt daneben und informiert Sie. Ihre eigenen Notizen leben in Notes/, das nie angefasst wird.

include_secrets ist standardmäßig include, weil genaue Anmeldedaten-Verfolgung der ganze Sinn ist. Setzen Sie redact oder partial, wenn der Vault irgendwohin synchronisiert, wo Sie es lieber nicht hätten; das betrifft nur die Projektion.

Konfiguration

~/.config/pentest-recorder/config.toml – generieren Sie es mit pentest-recorder config --write. Jede Einstellung hat einen dokumentierten Standardwert, und ein ungültiger Wert wird mit Namen gemeldet, ohne dass etwas angewendet wird.

[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 = ""

Optionale Shell-Integration

Fügt den exakten Befehl, das Arbeitsverzeichnis und den Exit-Code zu Segmenten aus Ihrer äußeren Shell hinzu:

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

Die Erfassung funktioniert vollständig ohne sie, und Aktivität innerhalb einer verschachtelten Sitzung bleibt korrekt nicht zugeordnet, statt geraten zu werden.

Wie es zusammenhält

Vier Speicherklassen, jede mit genau einer Regel:

Fünf Konsequenzen, die es wert sind, zu wissen:

Ein Modellfehler kostet nichts. tmux schreibt Bereichsausgabe in eine einfache Datei; der Recorder verfolgt sie ab einem eingecheckten Byte-Offset. Nichts im Erfassungspfad hängt davon ab, dass dieser Prozess läuft. Recorder stirbt → Bytes landen weiterhin auf der Platte und werden beim Neustart aufgenommen. Provider down → Segmente bleiben ausstehend.

Jedes extrahierte Literal wird gegen seine Quelle geprüft. Ein Wert, der nicht wörtlich vorkommt, wird behalten, aber markiert und über MCP als unverified angezeigt. HolyMoly123!, das still zu HolyMoly123 wird, ist genau der Fehler, den dieses Tool verhindern soll – und einfache Teilstring-Übereinstimmung kann ihn nicht erkennen, da die Kürzung ein Teilstring der Wahrheit ist.

Zusammenführen ist emergent. Entitäten sind verbundene Komponenten über Identitätsschlüssel. Erfahren Sie am Dienstag, dass FILE01 172.16.119.10 ist, und die zwei getrennten Datensätze von Montag werden beim nächsten Neubau zu einem – ohne Neuschreiben, ohne Tombstones. Entitäts-IDs sind inhaltsadressiert, also überleben sie jeden Neubau.

Eine falsche Zusammenführung ist behebbar und umkehrbar. Sagen Sie es dem Agenten; er zeichnet eine Trennung auf, die die Ableitung berücksichtigt – auch für transitiv behauptete Verknüpfungen.

reprocess --model <besser> ist sicher. Neue Beobachtungen werden hinzugefügt, nie ersetzt, und Ihre Befunde und Aufgaben bleiben unberührt. Jetzt günstig und lokal erfassen; die Extraktion später verbessern.

Gemessen, nicht angenommen

Drei Designfragen wurden während des Baus durch Messung entschieden. Reproduzieren Sie mit den Skripten in bench/.

Suchindex – Trigramm, kein abgestimmter Wort-Tokenizer. Über 20 repräsentative Abfragen gegen echte Werkzeugausgabe:

tokenchars weit genug zu machen, um 172.16.119.10 zusammenzuhalten, klebt auch INLANEFREIGHT\fiona:Summer2026! zu einem einzigen Token zusammen, sodass die Suche nach dem Passwort allein nichts findet.

Erfassungsvolumen – Normalisierung beseitigt Rauschen, nicht Masse.

Ein 4.000-zeiliger find besteht vollständig aus echtem Inhalt und wird unverändert durchgereicht. Deshalb ist die lokale Extraktion tragend und nicht nur klug.

Modell – qwen2.5-coder:7b. Bewertet danach, ob Geheimnisse, Hashes und Adressen byte-identisch zurückkommen:

Das 3B-Modell lieferte für beide Authentifizierungs-Fixtures überhaupt nichts zurück und lag bei Erfolg-vs-Fehler zweimal falsch – der eine Fehler, den dieses System nicht stillschweigend machen darf.

MCP-Tools

Zwölf Lese-, drei Schreiboperationen. Eine Aufblähung der Tool-Anzahl verschlechtert die Fähigkeit eines Agenten, das richtige auszuwählen, daher tragen die Zähler in get_engagement_summary die Hinweise, die sonst jeweils ein eigenes Tool benötigen würden.

Schreibvorgänge werden immer dem Bediener oder dem Agenten zugeordnet – niemals der Extraktion, und der Aufrufer kann nichts anderes behaupten. Kein Schreibpfad kann ein Segment verändern.

Entwicklung

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

CI führt die Suite auf Python 3.11 bis 3.14 aus, installiert tmux, damit die echten tmux-Abnahmetests tatsächlich laufen und sich nicht selbst überspringen, lintet und prüft, dass das Wheel mit seinen Lizenzmetadaten intakt gebaut wird.

296 Tests, einschließlich einer vollständigen Abnahme-Probe gegen echtes tmux mit einer verschachtelten Reverse Shell, einem echten MCP-Client über stdio, echtem gleichzeitigem Zugriff zwischen Recorder und Server sowie einem AST-Check, dass nur das Modellanbieter-Modul ein Netzwerk erreichen kann.

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

Designentscheidungen, Spezifikationen und die dahinterstehende Begründung finden sich in openspec/changes/add-pentest-recorder-mcp/.

Umfang

Bewusst nicht gebaut: autonomes Pentesting, automatische Ausnutzung, ein Ersatzterminal oder eine VM, ein Web-Dashboard, eine Graphdatenbank, Mehrbenutzer-Zusammenarbeit, Netzwerk-MCP-Transport oder ein Parser pro Tool.

Der Recorder erfasst und organisiert. Der MCP-Server stellt bereit. Der Agent denkt. Diese bleiben getrennt.

Lizenz

MIT — © 2026 Luciano Engel.

Nutze es, forke es, bring es raus. Es kommt ohne Garantie, was hier mehr als sonst zählt: Dieses Tool speichert Klartext-Anmeldedaten und Client-Daten auf der Festplatte. Lies Wo deine Daten leben und Wenn Daten die Maschine verlassen, bevor du es auf ein echtes Engagement richtest.