FindEvil

Autonomous AI agent for Linux incident response forensics.

Built for the FIND EVIL! hackathon by SANS Institute.

Most DFIR tooling targets Windows. But the systems attackers actually compromise in practice — web servers, Kubernetes clusters, cloud VMs — run Linux. FindEvil is a custom MCP server built for investigating compromised Linux systems.

It turns Linux forensic utilities into typed, read-only, audited functions that Claude can call autonomously. Given the available evidence (auth logs, systemd journal exports, nginx access logs, filesystem snapshots, package logs, Docker configs…), the agent discovers what's there, runs the right chain of structured tools, correlates findings across sources, explicitly audits its own claims, and produces a full IR report with per-finding line-number provenance and a complete tool-call audit trail.

FindEvil analyzes collected evidence — a mounted disk image, a triage collection, or a memory capture, examined on a clean workstation (SIFT) — never the live, untrusted host. This is the standard dead-disk forensics model, and it's the basis for the read-only guarantee: there is no tool that touches the compromised machine.

Protocol SIFT (the hackathon baseline) uses the "Direct Agent Extension" architecture — Claude Code with a bash allow-list and instructional SKILL.md files. It works but openly admits to hallucinating more than is acceptable for forensic work.

FindEvil addresses this at the architecture layer, not the prompt layer:

See docs/architecture.md for diagrams and docs/accuracy-report.md for the full per-tool recall/precision analysis across all 29 ground-truth attack scenarios (28 dead-disk + 1 memory).

MITRE ATT&CK Linux techniques with specialised detection include T1110.001 (brute force), T1078.003 (valid accounts), T1003.008 (/etc/shadow), T1136.001 (useradd), T1543.002 (systemd persistence), T1053.003 (cron), T1098.004 (authorized_keys), T1574.006 (LD_PRELOAD), T1556.003 (PAM), T1547.006 (kernel modules), T1562.001 (disable security tools), T1070.003 (history tampering), T1222 (file attributes), T1190 (webshell), T1195.002 (software supply chain), T1611 (container escape), T1071 / T1105 (C2 + ingress).

A five-minute walkthrough: install → launch → stage → investigate → self-correct.

• SANS SIFT Workstation (or any Ubuntu 22.04+ host)
• Python 3.11+
• Claude Code with MCP support

git clone https://github.com/marlyocat/findevil.git
cd findevil
sudo apt install python3.12-venv
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

cd findevil        # .mcp.json is only read from the directory you launch in
claude

The repo ships .mcp.json at the root, so Claude Code auto-detects the server and prompts for approval on first launch. Verify it loaded:

/mcp   →   findevil · ✔ connected · 45 tools

cp -r samples/attack-scenario-01 evidence/

Investigate evidence/attack-scenario-01 using the findevil tools.
Produce a full IR report including persistence mechanisms.

That single instruction is the only thing you type. The server's standing instructions make the agent run a senior-analyst loop on its own: orient → investigate → pivot on every IOC it finds → call assess_coverage to find what it still hasn't examined → go back and close those gaps → and finally finalize_report, which rejects any CONFIRMED claim that fails independent verification or contradicts another. When rejected, the agent re-investigates or downgrades the claim's confidence and tries again. You don't tell it which tools to use, and you don't tell it to check itself — it doesn't stop until coverage is clean and its claims have passed the gate.

To run it fully unattended (headless, with a hard iteration cap and a per-iteration progress trace), or to auto-investigate any evidence that lands in the directory:

python scripts/investigate.py evidence/attack-scenario-01 --max-iterations 5
python scripts/investigate.py --watch          # triages new evidence on arrival

investigate.py runs the loop as an outer harness with a hard --max-iterations cap, deciding termination mechanically (it re-reads the audit trail and re-runs assess_coverage itself each pass) and writing a per-iteration trace to logs/progress/. It keeps normal approval prompts by default; fully unattended operation is a deliberate opt-in (--permission-mode bypassPermissions, on a disposable SIFT VM with read-only evidence only).

Use verify_finding, find_contradictions, and get_audit_trail to audit your claims.

.mcp.json (shipped at the repo root):

{
  "mcpServers": {
    "findevil": {
      "type": "stdio",
      "command": "./.venv/bin/python",
      "args": ["-m", "findevil"]
    }
  }
}

The command path is relative to the repo root, so launch claude from there (step 2). If the server doesn't appear under /mcp, switch command to an absolute path such as /home/sansforensics/findevil/.venv/bin/python.

The entrypoint is python -m findevil, not python -m findevil.server — the latter triggers a Python dual-module execution bug documented in src/findevil/__main__.py.

Twenty-eight bundled-evidence scenarios plus one live-capture memory scenario (S29), each designed to disagree with the others so the agent is continuously tested against overfitting. Each has its own README.md with the narrative, expected detections, and control samples that must NOT be flagged. The first thirteen anchor the core attack patterns; the next fifteen stress-test specific failure modes (false-positive resistance, authorship attribution, dormancy, agent-operated tradecraft, novel persistence classes); S29 exercises the Volatility 3 memory tools against a live-captured RAM dump.

Three layered test suites + one-command reproduce:

# Unit tests — parser correctness + per-tool recall/precision on bundled samples
pytest tests/ -v

# Security suite — 102 cases covering path validation, symlink escape, static
# write-capability audit, audit-completeness AST walk, MITRE coverage, FIM guard
pytest tests/security/ -v

# Grader calibration — verifies the hallucination-harness grader correctly
# says PASS on good reports and FAIL on synthetic bad ones
python tests/harness/grader_calibration.py

# Everything in one command:
bash tests/harness/reproduce.sh

The security suite has already surfaced two real vulnerabilities:

• Prefix confusion in _validate_evidence_path — str.startswith() accepted sibling directories sharing the evidence prefix. Fixed with Path.relative_to().
• FIM output-path bypass — baseline_create accepted user-supplied output paths inside EVIDENCE_DIR. Fixed with an inverse path guard.

tests/harness/ spawns real Claude runs against the 29 scenarios and grades each report against ground-truth markers — both recall (did it find the planted attack?) and forbidden-marker checks (did it mention artifacts from other scenarios it couldn't legitimately know about?).

• docs/architecture.md — system diagrams, data flow, security boundaries
• docs/accuracy-report.md — per-tool recall & precision, known failure modes, Protocol SIFT comparison
• docs/memory-forensics.md — Volatility 3 acquisition, symbol-table workflow, tool family
• docs/real-world-evidence.md — pointing findevil at NIST CFReDS / Digital Corpora / Ali Hadi's DFIR challenges
• docs/devpost.md — Devpost project description (copy-paste ready)
• docs/sift-setup.md — SIFT Workstation installation walkthrough
• docs/example-reports/ — curated IR reports Claude wrote during calibration (one per scenario) + committed structured tool-execution trace audit-trail-scenario-01.jsonl for end-to-end auditability
• logs/README.md — the agent execution-log model: audit.json (mechanical per-tool trail, timestamps) + token_usage.jsonl (agent-layer token usage, correlated per tool execution via scripts/extract_token_usage.py)
• samples/attack-scenario-*/README.md — per-scenario narratives and ground-truth tables

MIT