convez.ai
MCP ServerSegurançaAvançado
saivarun3407

MemoryHound - Agente DFIR Autônomo com IA

saivarun3407/DFIR-AI

Triagem IR autônoma e verificável com IA para evidências digitais

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que transforma Claude, OpenAI ou Ollama em analista forense autônomo. Processa evidências digitais (memory dumps, registros, logs) e gera relatórios estruturados com achados verificáveis, assinaturas criptográficas e trilha de auditoria à prova de adulteração. Suporta Windows, macOS, Linux e análise de rede/memória com 47 ferramentas forenses integradas.

Instalação

$npx convez-ai saivarun3407/DFIR-AI

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
13

Casos de uso

  • Resposta a incidentes com relatórios forenses verificáveis
  • Análise autônoma de dumps de memória e artefatos do SO
  • Conformidade NIST/ISO/MITRE com rastreabilidade completa
  • Laboratórios DFIR air-gapped com Ollama local

Veredito

Solução robusta para times de resposta a incidentes que precisam de análise forense verificável com rastreabilidade criptográfica. Implementação profissional com suporte multi-engine (Claude, OpenAI, Ollama), mas requer expertise em DFIR e infraestrutura para máximo proveito.

README

A tradução para o português deste README ainda está na fila.

MemoryHound

Drop-in DFIR superpowers for Claude Code. Autonomous, cross-OS incident-response triage with structured findings, an independent verifier, and a plain audit trail.

Submission to the SANS FIND EVIL! Hackathon (Apr 15 – Jun 15, 2026).

AI threats strike in minutes. Build the defender that responds in seconds. — SANS


At a Glance

WhatAutonomous IR triage agent — drop evidence, get a pinned forensic report
HowCustom MCP server + provider-agnostic AI driver + skills/agents/hooks + LangGraph state machine
AI enginesAnthropic Claude Code · Anthropic API · OpenAI · Ollama (local) — one command, auto-detected, swappable via MH_PROVIDER
Surface47 typed forensic tools across 13 modules · 14 skills · 4 specialist subagents · 5 lifecycle hooks · 20-node IR graph (14 IR + session_init + session_finalize + suppress + correlate + manifest_ingest + scope)
OS coverageWindows (registry, EVTX, Prefetch, LNK, MFT, Amcache via EZ Tools), macOS (plist, KnowledgeC), Linux (shell history, journald, audit), Memory (Volatility 3 — 45+ plugins; MemProcFS FindEvil), Disk (Sleuth Kit — fls/icat/mmls/mactime/istat), Timeline (Plaso log2timeline + psort), Network (tshark, Zeek, pcap→Zeek/NetFlow/PassiveDNS), Malware/Carving (YARA, bulk_extractor, binwalk, strings)
FrameworksNIST CSF 2.0 · ISO/IEC 27035-1:2023 · SANS PICERL · MITRE ATT&CK · D3FEND
TrustSchema-rejected un-pinned findings · independent Verifier subagent with self-correction loop · cross-finding Correlator · sha256-chained audit log · SHA256 manifest at ingest · mh verify spoliation re-check
DeployOne-line installer (bash scripts/install.sh) · Host install · Docker (advanced — see docs/deployment.md)
AuthClaude subscription · Anthropic API key · OpenAI API key · Ollama (local, no key) · Bedrock · Vertex
Code~12K LoC Python · 60+ test files · 435 tests · CI green
Demo videoRecording in W6 (May 31 – Jun 6, 2026) — link added on upload. Must show verifier dissent → re-analyze self-correction (per hackathon rules).

What This Is

MemoryHound turns any major AI engine into an autonomous DFIR analyst. You drop evidence into a folder, run one command, and get back a structured forensic report whose every claim is pinned to a specific tool call against a specific artifact.

The custom MCP server's 47 forensic tools are the substrate; the AI driver is swappable — Claude Code, Anthropic API, OpenAI, or Ollama running locally on a laptop. Same orchestrator, same findings.json, same audit trail, regardless of engine. A judge with a Claude subscription, a shop on OpenAI, and an air-gapped DFIR lab on Ollama all run the same ./bin/mh run command.

Inspired by Daniel Miessler's PAI pattern: the .claude/ directory plus the custom MCP server give the AI driver the skills, subagents, hooks, and forensic primitives to operate as a domain specialist — without modifying the underlying model.

You drop:    Evidence files (memory dumps, registry hives, EVTX, plist, etc.)
You run:     mh run <case-id>     OR     mh orchestrate <case-id>
You get:     Pinned findings, investigative narrative, accuracy report,
             audit log, multi-framework compliance map

Two execution modes with the same trust contract:

  • mh run <case-name|file-path|folder-path> --interactive — free-form Claude Code session driven by the triage-orchestrator skill. Best for exploratory casework.
  • mh orchestrate — deterministic LangGraph state machine walking the §11.2 14-IR-node topology. Best for repeatable, framework-aligned IR.

Quickstart

One command from a freshly cloned repo to a working install:

git clone https://github.com/saivarun3407/DFIR-AI.git memoryhound && cd memoryhound
bash scripts/install.sh

The installer checks Python 3.11+, checks the claude CLI, then runs bin/mh init (creates .venv, installs deps). It surfaces missing system packages with the exact brew/apt command to fix them — it never installs anything for you silently.

Once installed, pick any AI engine — MemoryHound is provider-agnostic:

# 1) Anthropic Claude Code CLI (Pro/Max subscription)  — default if installed
claude /login

# 2) Anthropic API direct (no Claude Code needed)
export ANTHROPIC_API_KEY=sk-ant-...

# 3) OpenAI (gpt-4o by default)
export OPENAI_API_KEY=sk-...

# 4) Ollama — local models, $0/run, air-gapped DFIR
ollama serve & ollama pull llama3.3   # https://ollama.com

./bin/mh quickstart               # auth check + stub demo (no tokens spent)

./bin/mh run … auto-detects which provider you have. Set MH_PROVIDER (anthropic-cli / anthropic-api / openai / ollama) to force one explicitly. The same orchestrator, same findings.json, same audit trail — regardless of engine.

After mh quickstart finishes, full IR triage is one command. Point it at a file, a folder, or an existing case name — it figures out the rest:

./bin/mh run /path/to/memory.raw          # auto-wraps the file into a new case
./bin/mh run /path/to/evidence-folder/    # auto-wraps the folder into a new case
./bin/mh run case-001                     # uses cases/case-001/input/

That single command drives the entire IR pipeline: SHA256 manifest, ingest, OS detection, skill routing (FOR500 / FOR518 / FOR577), Windows/macOS/Linux subagent triage, Volatility memory analysis, Verifier dissent loop, MITRE ATT&CK tagging, NIST CSF 2.0 / ISO 27035 / PICERL framework mapping, D3FEND countermeasures, containment + remediation plans, narrative, accuracy report, sha256-chained audit log. Add --interactive for the skill-driven free-form Claude TUI (live tool calls visible) when you want to explore manually.

After triage:

./bin/mh serve                    # browse findings at http://127.0.0.1:8765/
./bin/mh report --exec case-001   # one-page executive summary
./bin/mh verify case-001          # chain-of-custody re-hash; exit 0 on no spoliation

Need a containerized run, a SIFT/Ubuntu host bootstrap with the full forensics toolchain, or the prebuilt image? See docs/deployment.md.


AI Provider Matrix

MemoryHound's MCP forensic tool surface (47 tools across 13 modules) is the substrate; the AI engine driving the subagent loop is swappable. Pick whichever the judge (or shop, or air-gapped lab) has.

ProviderMH_PROVIDERAuthModel defaultNotes
Anthropic Claude Codeanthropic-cliclaude /login or API keyClaude (via CLI)Default; subscription supports interactive TUI.
Anthropic API directanthropic-apiANTHROPIC_API_KEYclaude-sonnet-4-5No Claude Code needed. Override via MH_ANTHROPIC_MODEL.
OpenAIopenaiOPENAI_API_KEYgpt-4oFunction-calling tool loop. Override via MH_OPENAI_MODEL.
Ollama (local)ollamanone (local daemon)llama3.3$0/run, air-gapped. Native + text-tag fallback tool calls.

Auto-detect order when MH_PROVIDER is unset: anthropic-cli > anthropic-api > openai > ollama. Examples:

# Air-gapped DFIR with local llama3.3 — no internet, no API keys.
MH_PROVIDER=ollama OLLAMA_HOST=http://localhost:11434 ./bin/mh run /case/memory.raw

# Use a different Ollama model and force text-tag mode (for models without native tool calling).
MH_OLLAMA_MODEL=qwen2.5:32b MH_OLLAMA_TOOLS_MODE=text ./bin/mh run /case/memory.raw

# Run via the Anthropic API directly with a custom model.
MH_PROVIDER=anthropic-api MH_ANTHROPIC_MODEL=claude-opus-4-7 ./bin/mh run /case/memory.raw

# Force OpenAI even if claude is installed.
MH_PROVIDER=openai ./bin/mh run /case/memory.raw

The orchestrator's per-decision checkpointing, verifier loop, audit trail, framework mapping, and TUI dashboard all work identically across providers.


Demo — 60 Seconds, No API Key Needed

The demo proves the end-to-end pipeline without spending a token:

./bin/mh init       # if not already done
./bin/mh demo

Output:

» Step 1: self-collect safe host artifacts            ✓
» Step 2: ingest, hash, write to audit log            ✓
» Step 3: classify each artifact with os_detect       ✓
» Step 4: parse plist contents                        ✓

Real-Claude smoke (opt-in):

./bin/mh demo --real-claude       # ~$0.01, ≤1500 tokens, triage subagent only

Architecture

Every architecture claim below is grounded in a specific file. The codebase is the source of truth — diagrams summarize it, not the other way around.

System Layers

┌──────────────────────────────────────────────────────────────────┐
│  USER                                                             │
│  Drops evidence into cases/<id>/input/                            │
└────────────────────────────┬──────────────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────────────┐
│  CLI WRAPPER          bin/mh                                      │
│  Bash dispatcher with 14 subcommands; manages venv + auth +       │
│  fresh-cycle output reset; preflight detects active AI provider   │
└─────────────┬───────────────────────────────────┬─────────────────┘
              │                                   │
              ▼                                   ▼
┌────────────────────────────────┐  ┌────────────────────────────────┐
│  EXECUTION MODE A              │  │  EXECUTION MODE B              │
│  Skill-driven (free-form)      │  │  LangGraph (deterministic)     │
│                                │  │                                │
│  claude --mcp-config …         │  │  mh-orchestrate run <id>       │
│   (anthropic-cli only)         │  │   │                            │
│   ▼                            │  │   ▼                            │
│  triage-orchestrator skill     │  │  20-node IR graph + conditional│
│   │                            │  │  edges                         │
│   ├─→ WindowsAgent             │  │   │                            │
│   ├─→ MacOSAgent               │  │   ├─→ LLM-invoking nodes ──┐   │
│   ├─→ LinuxAgent               │  │   ├─→ deterministic nodes  │   │
│   └─→ Verifier                 │  │   └─→ Verifier pass        │   │
│                                │  │                            ▼   │
│  .claude/skills/*/SKILL.md     │  │  ┌─────────────────────────┐   │
│  .claude/agents/*.md           │  │  │ PROVIDER REGISTRY       │   │
└────────────┬───────────────────┘  │  │ MH_PROVIDER or auto-    │   │
             │                      │  │ detect → one of:        │   │
             │                      │  │   anthropic-cli         │   │
             │                      │  │   anthropic-api (SDK)   │   │
             │                      │  │   openai (SDK)          │   │
             │                      │  │   ollama (HTTP, local)  │   │
             │                      │  │ orchestrator/src/       │   │
             │                      │  │   mh_orchestrator/      │   │
             │                      │  │   providers/            │   │
             │                      │  └────────────┬────────────┘   │
             │                      └───────────────┼────────────────┘
             │                                      │
             └──────────────┬───────────────────────┘
                            ▼
┌──────────────────────────────────────────────────────────────────┐
│  CUSTOM MCP SERVER     mcp-server/src/protocol_sift_mcp/         │
│  ─ stdio protocol (Claude CLI) + in-process Python (other        │
│    providers) — single tool surface, two transports              │
│  ─ 47 typed tools across 13 modules                              │
│  ─ schema-rejects findings without pins (finding.py)             │
│  ─ path-escape sandbox (sandbox.py); evidence read-only          │
│  ─ writes audit.jsonl + findings.json directly                   │
└────────────────────────────┬──────────────────────────────────────┘
                             ▼
┌──────────────────────────────────────────────────────────────────┐
│  FORENSIC TOOLCHAIN     (vendored or pip-installed)              │
│  ─ Volatility 3 (windows.* / mac.* / linux.* plugin families)    │
│  ─ python-registry, python-evtx, pylnk3, windowsprefetch         │
│  ─ plistlib, libmagic, hashlib                                   │
│  ─ ISF symbols vendored at corpus/<case>/symbols/                │
└──────────────────────────────────────────────────────────────────┘

Two Execution Modes Compared

mh run (skill-driven)mh orchestrate (LangGraph)
Drivertriage-orchestrator skill in a Claude Code sessionmh-orchestrate run invoking compiled StateGraph
DeterminismFree-form within the skill spec20 nodes, 6 typed conditional edges
Output deliverables4 files (audit, findings, narrative, accuracy-report)10 §11.4 files (state, history, audit, agent_messages, containment, recovery, lessons, remediation, compliance, summary)
LLM callsAll triage stepsOnly ClaudeNode calls; deterministic nodes are pure Python
Stub moden/aMH_NO_CLAUDE=1 short-circuits LLM nodes
Re-route on dissentSkill spec says re-run subagentverifier_pass → analyze (capped at 1 revision)
Source.claude/skills/triage-orchestrator/SKILL.mdorchestrator/src/mh_orchestrator/graph.py

LangGraph Topology

The orchestrator implements the §11.2 14-IR-node topology from Plans/IR_FRAMEWORKS_REFERENCE.md, plus session_init, session_finalize, suppress (false-positive path), correlate (cross-finding linker after verifier_pass), manifest_ingest (chain-of-custody manifest), and scope (multi-host scoping) — 20 nodes total. Six conditional edges (§11.3) govern branching and bounded loops.

flowchart TD
    SI[session_init] --> D[detect]
    D --> T[triage]
    T -->|severity ∈ {low,info}<br/>and findings=∅| SP[suppress]
    T -->|else| DI[declare_incident]
    DI --> A[analyze]
    A -->|RCA incomplete<br/>and iter < 3| A
    A -->|RCA complete<br/>OR cap reached| AT[attack_tag]
    AT --> KC[kill_chain]
    KC --> D3[d3fend_recommend]
    D3 --> C[contain]
    C -->|blast > threshold| HIL[human_in_loop]
    C -->|else| E[eradicate]
    HIL --> E
    E -->|reinfection| C
    E -->|clean| R[recover]
    R -->|post-restore alarm| C
    R -->|clean| LL[lessons_learned]
    LL --> RM[remediation]
    RM --> VP[verifier_pass]
    VP -->|dissent and<br/>revisions < 1| A
    VP -->|complete| SF[session_finalize]
    SP --> SF
    SF --> END([END])

Six conditional edges (graph.py:43–149):

EdgeSource line§11.3 rowNIST CSF tagTrigger
route_after_triagegraph.py:43row 1RS.MA-03severity ∈ {low, informational} ∧ findings=∅ → suppress; else → declare_incident
route_after_analyzegraph.py:60row 2RS.AN-03RCA loop, capped at 3 iterations (_ANALYZE_ITER_CAP)
route_after_containgraph.py:73row 3IR-7blast-radius score > MH_BLAST_RADIUS_THRESHOLD (default 50) → human_in_loop
route_after_eradicategraph.py:97row 4PICERL phase 4 retryre-infection detected → loop back to contain
route_after_recovergraph.py:108row 5RC.RP-01post-restore alarm → re-contain
route_after_verifier_passgraph.py:119dissent edge—dissent ∧ revision available → re-analyze; else → session_finalize

IncidentState Schema

orchestrator/src/mh_orchestrator/state.py mirrors §11.1 of the framework reference. Public fields are visible to every node; underscore-prefixed fields are internal plumbing.

Public fieldTypePurpose
incident_idstrStable case identifier
severitylow | medium | high | critical | unknownTriage verdict
phasedetect | triage | analyze | contain | eradicate | recover | lessonsCurrent PICERL phase
kill_chain_stageintLockheed Martin Cyber Kill Chain stage (0–7)
attack_techniqueslist[str]MITRE ATT&CK technique IDs
forensic_artifactslist[Artifact]Pinned evidence with hash + label
csf_subcategories_satisfiedset[str]NIST CSF 2.0 subcategory IDs
iso27035_phasestrPlan / Detect / Assess / Respond / Lessons
d3fend_recommendationslist[Countermeasure]D3FEND countermeasures
containment_actions / eradication_actions / recovery_actionslist[dict]Advisory actions, never executed
remediation_planlist[dict]NIST SP 800-53 IR/SI/SC controls

Trust Contract — Five Layers of "No Hallucinations"

1. SCHEMA            mcp-server/src/protocol_sift_mcp/tools/finding.py
                     finding_record() rejects un-pinned claims at the
                     MCP schema layer (pins[].minItems = 1).

2. TOOL BOUNDARY     .claude/hooks/guard.sh   (PreToolUse)
                     Re-rejects un-pinned finding_record calls plus
                     any Bash, Write to /input, or network egress.

3. SANDBOX           mcp-server/src/protocol_sift_mcp/sandbox.py
                     Path-escape rejection on every tool call.
                     Evidence mounted read-only.

4. AUDIT             .claude/hooks/audit.sh   (PostToolUse)
                     Every tool call appended to cases/<id>/output/audit.jsonl.

5. VERIFIER          .claude/agents/verifier.md  +
                     orchestrator/.../nodes/verifier_pass.py
                     Independent subagent re-runs the cited tool against
                     the cited evidence with NO context from the
                     originating agent. Disagreements re-route through
                     analyze (capped at 1 revision).

Confidence enum (triage-orchestrator/SKILL.md):

  • confirmed — corroborated across ≥2 independent artifacts
  • inferred — single artifact, well-understood semantics
  • uncertain — observation suggestive but not conclusive
  • unknown — explicit gap; pinned, never guessed

MCP Tool Surface (47 tools, 13 modules)

mcp-server/src/protocol_sift_mcp/tools/ (source):

ModuleToolsPurpose
audit.pyaudit_appendAppend-only event log
evidence.pyhashsha256 + sha1 + size of any artifact
finding.pyfinding_recordSchema-validated pinned findings (rejects un-pinned)
parse.pyos_detect, magic_checkCross-OS routing primitives
windows.pywin_registry_get, win_prefetch_parse, win_evtx_query, win_lnk_parseFOR500-aligned native Windows triage
win_artifacts.pyez_evtxecmd, ez_mftecmd, ez_recmd, ez_amcacheparserEZ Tools wrappers (EVTX, MFT, registry, Amcache)
macos.pymac_plist_get, mac_knowledgec_queryFOR518-aligned macOS triage
linux.pylinux_history_parseBash + zsh history (FOR577)
memory.pymemory_volatility, memprocfs_findevilVolatility 3 (11-plugin allowlist) + MemProcFS FindEvil
filesystem.pytsk_fls, tsk_icat, tsk_mmls, tsk_mactime, tsk_istatThe Sleuth Kit — file listing, content extract, partition map, timeline, inode stat
timeline.pyplaso_log2timeline, plaso_psortPlaso super-timeline build + sort
network.pytshark_extract, zeek_log_readtshark protocol extract, Zeek log reader
carving.pyyara_scan, bulk_extractor, binwalk, strings_extractMalware/carving — YARA rule scan, bulk_extractor, binwalk, strings

AI Driver Layer

The provider registry (orchestrator/src/mh_orchestrator/providers/) picks one engine at runtime via MH_PROVIDER or auto-detect (anthropic-cli > anthropic-api > openai > ollama). Every node calls Provider.invoke(subagent_name, prompt, allowed_tools, headless) → SubagentResult — the same shape regardless of engine, so triage / analyze / verifier_pass / scope code is unchanged across providers.

ProviderFileTransportTool surface
anthropic-cliproviders/anthropic_cli.pyclaude -p subprocess + stream-jsonMCP server via stdio
anthropic-apiproviders/anthropic_api.pyanthropic.Anthropic().messages.createIn-process Python (tool_dispatch)
openaiproviders/openai_provider.pyopenai.OpenAI().chat.completions.createIn-process Python (tool_dispatch)
ollamaproviders/ollama.pyurllib POST /api/chat (stdlib-only)In-process Python (tool_dispatch) — native + <tool> text-tag fallback

The shared providers/tool_dispatch.py mirrors the MCP server's call_tool dispatch surface line-for-line in plain Python so non-CLI providers run the same 47 forensic tools without stdio framing.

Claude Code Layer (used by anthropic-cli)

.claude/ (source) — drives the anthropic-cli provider AND provides the persona / skill source for every other provider:

SurfaceCountFiles
Skills14triage-orchestrator, windows-triage, macos-triage, linux-triage, memory-forensics, evidence-pin, gap-acknowledgment, self-correct, ir-narrative, accuracy-report, exec-report, containment-recommender, remediation-planner, threat-hunting
Subagents4WindowsAgent, MacOSAgent, LinuxAgent, Verifier — non-CLI providers load .claude/agents/<name>.md as the system prompt (frontmatter stripped).
Hooks5session-start.sh (ingest+hash), inject-context.sh (UserPromptSubmit), guard.sh (PreToolUse trust gate), audit.sh (PostToolUse log), finalize.sh (Stop summary) — fire only for the anthropic-cli path.
Permissions—allow: mcp__protocol_sift__*, Read, Glob, Grep · deny: Bash, WebFetch, WebSearch, Edit, Write, mcp__filesystem__write_* (anthropic-cli only)

The bin/mh:claude_run wrapper extends the headless --allowedTools set to also include Write and TodoWrite so the agent can land narrative.md and accuracy-report.md without an interactive approval channel.


Output Schemas

mh run deliverables — cases/<id>/output/

FileSchemaPurpose
audit.jsonl{seq, ts, event, data}Append-only log of every step
findings.json[{finding_id, claim, confidence, pins[], mitre_attck[]}]Structured findings, schema-validated
narrative.mdInvestigator prosePlain-English report with timeline, IOCs, gaps
accuracy-report.mdTP/FP/FN/uncertain tallyHonest accuracy disclosure

mh orchestrate deliverables — cases/<id>/output/ (§11.4, 10 files)

FileSource nodePurpose
state.jsonsession_finalizeFinal IncidentState (Pydantic-serialized)
state.history.jsonlevery nodeOne snapshot per node exit
audit.jsonlnodes/__init__.record_auditAppend-only event log
agent_messages.jsonlnodes/__init__.emit_messageInter-agent + Verifier dissent trace
containment_actions.jsonlcontainAdvisory NIST SP 800-61 §5.1 recs
recovery_verification.jsonrecoverRestore validation steps
lessons_learned.mdlessons_learnedInvestigator retro
remediation_plan.jsonremediationNIST SP 800-53 IR/SI/SC controls
compliance_map.jsonsession_finalizeCSF 2.0 + ISO 27035 + ATT&CK + kill-chain
incident_summary.mdsession_finalizeInvestigator-readable narrative

Pin Schema (mandatory on every finding)

{
  "artifact": "/input/memory.raw",
  "tool": "mcp__protocol_sift__memory_volatility",
  "locator": {"type": "file_offset", "value": "psscan@0x1cdbeb00"},
  "raw_excerpt": "explorer.exe PID=1172 PPID=2024 Threads=32 …",
  "captured_at": "2026-05-10T01:55:01Z"
}

CLI Reference (bin/mh)

mh init [--with-forensics]   First-time setup: venv, deps.
                             --with-forensics adds heavy libs (Volatility, etc.)
mh doctor                    Health check across env, deps, auth.
mh demo [--real-claude]      Showcase run — no real evidence, no tokens
                             (--real-claude does one ≤1500-token smoke test).
mh run <case-id>             Skill-driven Claude Code triage on cases/<id>/input/.
mh orchestrate <case-id>     Full §11.2 LangGraph IR state machine.
mh report <case-id>          Plain-English summary (no LLM, no tokens).
mh serve [--port=8765]       Local web viewer for findings + narrative.
mh status                    List cases + their phase.
mh tools                     List MCP tools the agent can call.
mh check                     Quick env probe (exit 0/1).
mh help                      Show this list.

Each command is a cmd_* function in bin/mh; subcommand source lines are easy to grep:

grep -nE "^cmd_[a-z]+\(\)" bin/mh

Configuration

Environment Variables

VariableEffectDefault
AI provider selection
MH_PROVIDERForce a provider: anthropic-cli, anthropic-api, openai, ollama. Unset = auto-detect.auto
ANTHROPIC_API_KEYEnables anthropic-api (and anthropic-cli API-key auth)unset
OPENAI_API_KEYEnables openaiunset
OLLAMA_HOSTOllama daemon endpoint (enables ollama provider when reachable)http://localhost:11434
MH_ANTHROPIC_MODELOverride anthropic-api modelclaude-sonnet-4-5
MH_OPENAI_MODELOverride openai modelgpt-4o
MH_OLLAMA_MODELOverride ollama modelllama3.3
MH_OLLAMA_TOOLS_MODEauto / native / text — pick native tool calling, text-tag fallback, or autoauto
MH_MAX_TOKENSPer-call max_tokens (anthropic-api / openai)8192
MH_SUBAGENT_IDLE_TIMEOUT_SECKill a subagent when idle this long (no CPU, no output)600
MH_SUBAGENT_MAX_SECHard wall-clock ceiling per subagent7200
CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEXClaude Code cloud-provider auth (applies to anthropic-cli)unset
Pipeline knobs
MH_HOMEProject root overriderepo dir
MH_VENVPython venv path$MH_HOME/.venv
MH_NO_CLAUDEStub LLM-invoking nodes (CI / no-token testing)0
MH_BLAST_RADIUS_THRESHOLDroute_after_contain escalation cutoff50
MH_LG_RECURSION_LIMITLangGraph recursion cap (default 50, ~3× headroom over 15-node happy path)50
MH_CLAUDE_HEADLESSclaude -p print mode for CI/scripts (anthropic-cli only)0
MH_DEMO_NONINTERACTIVESkip the mh demo --real-claude y/N prompt0
VOLATILITY_SYMBOL_PATHVendored ISF symbols (Linux/macOS kernels)corpus/<case>/symbols/

Auth modes (any provider works)

  • Claude Code subscription — claude /login once; persistent ~/.claude/ (drives anthropic-cli)
  • Anthropic API key — export ANTHROPIC_API_KEY=sk-ant-... (drives anthropic-api or anthropic-cli)
  • OpenAI API key — export OPENAI_API_KEY=sk-... (drives openai)
  • Ollama (local, no key) — ollama serve & ollama pull llama3.3 (drives ollama; air-gapped, $0/run)
  • AWS Bedrock — export CLAUDE_CODE_USE_BEDROCK=1 (drives anthropic-cli)
  • Google Vertex — export CLAUDE_CODE_USE_VERTEX=1 (drives anthropic-cli)

Capability Matrix

ComponentStatus
Sandbox (path-escape rejection, deny-list hooks)✅ live
os_detect, magic_check (cross-OS routing)✅ live
Windows tools: win_registry_get, win_prefetch_parse, win_evtx_query, win_lnk_parse✅ live
13 Claude Code skills (FOR500 / APFS / Linux + IR planners)✅ live
4 specialist subagents (Windows / macOS / Linux / Verifier)✅ live
5 hooks (session-start / inject-context / guard / audit / finalize)✅ live
mh CLI + mh-mcp-server portable launcher✅ live
LangGraph orchestrator (full §11.2 17-node topology, 6 conditional edges)✅ live
Multi-framework state (CSF 2.0 + ISO 27035 + PICERL + ATT&CK + kill-chain)✅ live
Reversibility gate + human-in-loop + Verifier pass✅ live
§11.4 deliverables (10 outputs incl. compliance_map + incident_summary)✅ live
memory_volatility (Volatility 3 CLI, 11-plugin allowlist)✅ live
Mimikatz / credential-extraction allowlist (windows.lsadump, hashdump, cmdline, dlllist, svcscan, handles)✅ live (allowlisted; OtterCTF staging)
linux_history_parse (bash/zsh formats)✅ live
D3FEND ATT&CK → countermeasure crosswalk (25 techniques, 52 countermeasures)✅ live
mh demo --real-claude opt-in real-Claude smoke✅ live (gated test in CI)
Verifier dissent → analyze re-route (one-shot self-correction)✅ live
Subagent failure paths (loud RuntimeError on analyze; tool_failure on verifier; severity=unknown on triage)✅ live
Pre-commit gate (ruff + pytest + license check)✅ live
mac_* macOS tools (apfs / tracev3 / spotlight)🛠️ Sub-Plan 06+
linux_journal_query, linux_audit_query, linux_systemd_units🛠️ Sub-Plan 06+

656 tests passing (221 mcp-server + 435 orchestrator + 4 opt-in skips). CI green on every commit. Includes 26 provider-abstraction tests covering MH_PROVIDER auto-detect across the four engines and in-process MCP tool dispatch.


Project Structure

memoryhound/
├── bin/
│   ├── mh                    # 11-subcommand bash dispatcher (claude_run + cmd_*)
│   └── mh-mcp-server         # MCP server launcher (used by both modes)
│
├── mcp-server/               # Custom MCP server — typed forensic primitives
│   ├── src/protocol_sift_mcp/
│   │   ├── server.py         # 13 Tool() declarations, stdio wiring
│   │   ├── sandbox.py        # path-escape rejection
│   │   ├── schema.py         # Pin / Finding pydantic schemas
│   │   └── tools/            # 8 modules (audit/evidence/finding/parse/windows/macos/linux/memory)
│   └── tests/                # 12 test files
│
├── orchestrator/             # LangGraph IR state machine
│   ├── src/mh_orchestrator/
│   │   ├── graph.py          # build_graph(): 17 nodes, 6 conditional edges
│   │   ├── state.py          # IncidentState TypedDict (§11.1)
│   │   ├── claude_node.py    # ClaudeNode abstraction for LLM-invoking nodes
│   │   ├── blast_radius.py   # contain() reversibility scorer
│   │   ├── csf_tags.py       # NIST CSF 2.0 subcategory tagging
│   │   ├── d3fend_crosswalk.py   # ATT&CK → D3FEND mapping
│   │   ├── picerl.py         # PICERL phase mapping
│   │   ├── persistence.py    # state.history.jsonl writer
│   │   ├── cli.py            # mh-orchestrate run <id>
│   │   └── nodes/            # 17 node implementations (one .py per node)
│   └── tests/                # 28 test files
│
├── .claude/                  # Claude Code config (PAI pattern)
│   ├── settings.json         # permissions + MCP wiring + 5 hooks
│   ├── mcp-config.json       # standalone MCP config for headless mode
│   ├── skills/               # 13 SKILL.md (one per skill)
│   ├── agents/               # 4 subagents (Windows/MacOS/Linux/Verifier)
│   └── hooks/                # 5 lifecycle .sh hooks
│
├── scripts/
│   ├── install-sift.sh       # SIFT/Ubuntu host bootstrap
│   ├── install.sh            # generic host bootstrap
│   ├── fetch-isf-symbols.sh  # ISF kernel symbol fetcher
│   ├── self-collect.sh       # demo evidence collector
│   ├── plain-summary.py      # mh report (no LLM)
│   ├── serve.py              # mh serve (local viewer)
│   └── replay.sh, eval.sh, record-demo.sh, …
│
├── corpus/                   # Vendored evidence + ground truth
│   ├── _template/            # Per-case template
│   └── dfrws-2008-memory/    # First public corpus case
│       ├── ground-truth.json
│       └── symbols/          # ISF symbols (gitignored binaries)
│
├── docs/
│   ├── architecture.md       # Deep-dive system design
│   ├── deployment.md         # Three deployment paths in detail
│   ├── usage.md              # End-to-end walkthrough
│   ├── development.md        # Pre-commit + CI workflow
│   ├── dataset-documentation.md
│   └── superpowers/plans/    # Master spec + sub-plan history
│
├── cases/                    # Per-case input/output (gitignored)
│   └── <case-id>/
│       ├── input/            # Evidence (read-only)
│       └── output/           # Audit log + findings + reports
│
├── Dockerfile                # Multi-stage runtime image (Sub-Plan 05)
├── docker-compose.yml        # Local-build compose (two services)
└── .pre-commit-config.yaml   # ruff + pytest + license check

Top-of-tree counts (current branch):

  • Python: ~10K LoC (3.5K mcp-server + 4.7K orchestrator + 1.8K scripts)
  • Tests: 60+ test files, 656 tests passing
  • Skills: 13 · Subagents: 4 · Hooks: 5 · MCP tools: 13
  • LangGraph nodes: 17 (14 IR + session_init + session_finalize + suppress)
  • Conditional edges: 6

Development

Running the test suite

.venv/bin/python -m pytest mcp-server/tests orchestrator/tests

Per-area:

.venv/bin/python -m pytest mcp-server/tests        # 75 tests, ~3s
.venv/bin/python -m pytest orchestrator/tests      # 138 tests, ~6s

Opt-in real-Claude smoke (~$0.01, ≤1500 tokens):

RUN_REAL_CLAUDE=1 .venv/bin/python -m pytest orchestrator/tests/test_demo_real_claude.py

Pre-commit gates

.pre-commit-config.yaml runs on every commit:

  • ruff check + ruff format (linting + formatting)
  • pytest (full suite)
  • License-header check on Python sources
  • shellcheck on bin/mh and hooks
pre-commit install            # one-time
pre-commit run --all-files    # manual full run

CI

.github/workflows/ runs the same suite on push + PR, plus builds and pushes the Docker image to ghcr.io/saivarun3407/memoryhound on tagged releases.

Adding a new MCP tool

  1. Drop the implementation into mcp-server/src/protocol_sift_mcp/tools/<family>.py
  2. Register the Tool() declaration in mcp-server/src/protocol_sift_mcp/server.py
  3. Add a smoke test in mcp-server/tests/test_<family>.py
  4. Allowlist the tool in bin/mh:38 (claude_run --allowedTools) — headless mode skips the consent prompt for allowlisted tools only

Adding a new LangGraph node

  1. Create orchestrator/src/mh_orchestrator/nodes/<name>.py exporting def run(state: IncidentState) -> IncidentState
  2. Register it in orchestrator/src/mh_orchestrator/nodes/__init__.py:NODES
  3. Wire edges in orchestrator/src/mh_orchestrator/graph.py:build_graph
  4. Add a unit test in orchestrator/tests/test_node_<name>.py

Hackathon Deliverables (8 / 8)

#DeliverableWhere
1Public GitHub repo (Apache-2.0)this repo, LICENSE at root
2Demo video < 5 minW6 — May 31 – Jun 6
3Architecture diagramthis README + docs/architecture.md
4Project descriptionthis README + docs/usage.md
5Evidence dataset documentationdocs/dataset-documentation.md + corpus/README.md
6Accuracy reportcases/<id>/output/accuracy-report.md per run
7Deployment / setup instructionsthis Quickstart + docs/deployment.md
8Agent execution logs (timestamps + tokens)cases/<id>/output/audit.jsonl

Documentation Index


License

Apache-2.0 — see LICENSE.

Acknowledgments

  • SANS Institute — SIFT Workstation, FOR500 / FOR518 / FOR577 curricula, FIND EVIL! hackathon
  • The DFIR community — 19 years of open tooling
  • Volatility Foundation — Volatility 3
  • Anthropic — Claude Code, MCP
  • Daniel Miessler — PAI pattern for AI-as-domain-specialist
Ver o original no GitHub

Bom para

Relacionados