# SIFTAgent

**A typed, audited MCP server that turns Claude Code into an autonomous DFIR
analyst on the SANS SIFT Workstation.**

Built for the SANS **FIND EVIL!** hackathon. SIFTAgent is the *Custom MCP
Server* architecture — the approach the hackathon's own materials call "the most
architecturally sound" — designed specifically to beat Protocol SIFT's
hallucination baseline.

## Why this design wins on the judging criteria

| Criterion | How SIFTAgent addresses it |
|---|---|
| **Autonomous execution quality** | A playbook (`playbooks/INVESTIGATION.md`) drives a hypothesize → run → verify → self-correct loop. The agent retracts unsupported findings instead of asserting them. |
| **IR accuracy** | Findings **cannot be recorded without citing real `execution_id`s** that exist in the audit log — fabricated evidence is rejected at the API. Confidence levels separate `confirmed` from `inferred`. |
| **Breadth & depth** | Typed tools across disk (Sleuth Kit), memory (Volatility 3), timeline (plaso), registry (RegRipper), strings/IOCs, YARA, hashing. |
| **Constraint implementation** | **Architectural, not prompt-based** guardrails: a binary allowlist of read-only forensic tools, no `shell=True` anywhere, no generic "run command" path, write-flag rejection. Evidence cannot be modified. |
| **Audit trail quality** | Append-only JSONL log; every execution has a timestamp, exact argv, runtime, and SHA-256 output hash. Any finding links back to a specific tool execution. |
| **Usability** | One-command install, mock mode for offline testing, full test suite. |

## Architecture

See `docs/ARCHITECTURE.md` (diagram + security boundaries). In short:

```
Claude Code  ──MCP(stdio)──►  SIFTAgent server
                                  │
            ┌─────────────────────┼───────────────────────┐
            ▼                     ▼                       ▼
     runner.py (guardrails)   case.py (findings)     iocs.py (parsing)
       binary allowlist        evidence-cited           pure python
       no shell, read-only     verify/retract
            │                     │
            ▼                     ▼
   SIFT binaries  ───────►  audit.jsonl (timestamped, hashed)
   (tsk, vol3, plaso,            ▲
    regripper, yara)             │
                          incident-report.md (cites execution_ids)
```

## Install on the SIFT Workstation

```bash
# On the SANS SIFT Workstation (Ubuntu-based; sleuthkit, volatility3,
# plaso, regripper, yara are pre-installed):
git clone <your-repo-url> siftagent && cd siftagent
python3 -m pip install -r requirements.txt   # installs the `mcp` SDK
```

### Connect to Claude Code

Add to your Claude Code MCP config (`~/.claude.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "siftagent": {
      "command": "python3",
      "args": ["-m", "siftagent.server"],
      "cwd": "/home/sansforensics/siftagent",
      "env": { "SIFTAGENT_LOG_DIR": "/cases/host01/logs" }
    }
  }
}
```

Then in Claude Code, paste `playbooks/INVESTIGATION.md` as your system steer (or
reference it) and say: *"Investigate /cases/host01.E01 and /cases/host01.mem."*

## Run an investigation

**Live (on SIFT):**
```bash
export SIFTAGENT_LOG_DIR=/cases/host01/logs
# Claude Code drives the MCP tools per the playbook.
```

**Offline / mock mode (Windows, macOS, CI — no SIFT needed):**
```bash
SIFTAGENT_MODE=mock python -m siftagent.investigate
# Prints an evidence-cited incident report from synthetic fixtures.
```

`SIFTAGENT_MODE=mock` serves canned tool output from `siftagent/fixtures/`, so
the whole agent loop is reproducible without a disk image. Setting
`SIFTAGENT_ALLOW_MOCK_FALLBACK=1` falls back to fixtures only when a binary is
absent — useful for partial environments.

## Tools exposed

Case layer: `open_case`, `add_hypothesis`, `update_hypothesis`, `add_finding`,
`verify_finding`, `retract_finding`, `generate_report`, `get_audit_entry`.

Forensics: `disk_partitions`, `disk_fs_info`, `disk_list_files`,
`disk_file_metadata`, `disk_read_file`, `timeline_bodyfile`, `timeline_plaso`,
`timeline_query`, `memory_analyze`, `registry_analyze`, `extract_strings`,
`extract_iocs`, `hash_file`, `file_type`, `yara_scan`.

## Tests

```bash
python -m pytest -q        # 18 tests, all offline via fixtures
```

Covers guardrail enforcement, anti-hallucination citation checks, IOC parsing,
and the full investigation pipeline including a self-correction/retraction case.

## License

Apache-2.0. See `LICENSE`.