AletheiaIR

A self-correcting, contradiction-aware DFIR agent for Protocol SIFT.

RESEARCH / LAB USE ONLY — Findings are NOT court-admissible.

---

What It Does

Protocol SIFT demonstrates what AI-assisted incident response looks like when it works. AletheiaIR addresses the next problem: what happens when the agent is confidently wrong?

AletheiaIR extends the Protocol SIFT agent loop with four additional pipeline stages that run before anything reaches the report:

1. Evidence Validation — every finding is checked against other source types. Memory and log both showing the same process chain raises confidence. A single source keeps it at "inferred."

2. Contradiction Detection — a deterministic rule engine checks for logical conflicts: a process visible in memory but absent from disk prefetch, C2 traffic with no owning process, claimed persistence without a registry artefact. Conflicts are recorded, not silenced.

3. Bounded Self-Correction — when contradictions exist, the agent reruns targeted analysis on the conflicting artefact types. Hard-capped at two iterations to prevent runaway loops.

4. Structured Audit Trail — every agent action is logged as JSONL with timestamps, confidence deltas, and tool call records. Judges can trace any finding back to its origin.

---

Why It Matters

CrowdStrike's observed breakout time: 7 minutes. Human analysts still look up flags during active incidents.

AletheiaIR doesn't make the agent faster — it makes it more trustworthy. An autonomous agent that hallucinates certainty is not a defender. One that measures, contradicts, and self-corrects before reporting is.

---

Core Guarantees

Guarantee	What it means in practice
Evidence-first analysis	Every finding is anchored to source artefacts before it reaches the report.
Contradiction-aware workflow	Conflicts between sources are detected and recorded instead of being hidden.
Bounded correction	Targeted re-analysis runs only when needed and stops after a fixed number of passes.
Traceable output	Reports and logs preserve the reasoning path, confidence shifts, and tool usage.
Read-only evidence handling	Input artefacts are handled conservatively to reduce accidental mutation or overwrite risk.
Deterministic pipeline	The core flow is designed to be repeatable and reviewable by another analyst.

---

Architecture

flowchart TD
    A[Evidence Sources\nmemory · disk · logs · pcap] --> B[Evidence Store\nSHA-256 hash · O_RDONLY]
    B --> C[Analyzer Agent\nPhase 1 — SIFT wrapper dispatch]
    C --> D[Validator Agent\nPhase 2 — Cross-source corroboration]
    D --> E[Contradiction Detector\nPhase 3 — Deterministic rule engine]
    E -->|contradictions found| F[Self-Correction Controller\nPhase 4 — Targeted re-analysis · max 2 iter]
    E -->|no contradictions| G
    F --> G[Reporter Agent\nPhase 5 — Markdown reports]
    G --> H[reports/final_report.md]
    G --> I[reports/accuracy_report.md]
    C --> J[logs/execution_log.jsonl]
    D --> J
    E --> J
    F --> J

Loading

Architectural pattern: Direct Agent Extension

The four validation stages wrap Protocol SIFT's tool access layer — they do not replace it. Every SIFT wrapper function can be upgraded from mock to real by changing one function body; no other code changes.

---

File Structure

aletheia-ir/
├── README.md
├── LICENSE                      MIT
├── requirements.txt             (no mandatory external deps in core pipeline)
├── main.py                      CLI entry point
├── config.py                    Runtime tunables
├── agents/
│   ├── analyzer.py              Phase 1 — tool dispatch
│   ├── validator.py             Phase 2 — cross-source corroboration
│   ├── contradiction_detector.py Phase 3 — rule engine
│   ├── self_corrector.py        Phase 4 — bounded re-analysis loop
│   └── reporter.py              Phase 5 — Markdown + accuracy reports
├── sift_wrappers/
│   ├── memory_tools.py          Volatility 3 wrappers (mock-compatible)
│   ├── disk_tools.py            TSK / Plaso / RegRipper wrappers
│   ├── log_tools.py             python-evtx / Chainsaw wrappers
│   └── network_tools.py         tshark / Zeek wrappers
├── core/
│   ├── schemas.py               Finding, Contradiction, AuditEntry, CaseContext
│   ├── evidence_store.py        SHA-256 hashing, read-only file access
│   ├── confidence.py            Scoring thresholds, corroboration, penalties
│   └── logger.py                JSONL execution logger + terminal output
├── sample_cases/
│   ├── README.md
│   └── mock_case.json           Demo scenario definition
├── logs/
│   └── execution_log.jsonl      Written at runtime
├── reports/
│   ├── final_report.md          Written at runtime
│   └── accuracy_report.md       Written at runtime
└── docs/
    ├── architecture.md          Detailed architecture + security boundaries
    └── devpost_submission.md    Full Devpost project story

---

Setup Instructions

Requirements

• Python 3.9 or later
• No mandatory pip packages for mock mode (pure stdlib)

Install

git clone https://github.com/<your-handle>/aletheia-ir
cd aletheia-ir

# Optional: install future integrations
pip install -r requirements.txt

---

SIFT Workstation Setup

1. Download the SIFT Workstation OVA from sans.org/tools/sift-workstation
   • File: sift-2026-04-22.ova
2. Import into VirtualBox or VMware
3. Start the VM
   • Username: sansforensics
   • Password: forensics
4. Install Protocol SIFT inside the VM:

   curl -fsSL https://raw.githubusercontent.com/teamdfir/protocol-sift/main/install.sh | bash

5. Clone AletheiaIR inside the VM:

   git clone https://github.com/<your-handle>/aletheia-ir
   cd aletheia-ir

---

How to Run

Mock mode (no evidence files required)

python main.py --case-name demo_case

Mock mode with named file paths (realistic output)

python main.py \
    --memory sample_cases/mock_memory.raw \
    --disk   sample_cases/mock_disk.E01   \
    --logs   sample_cases/mock_evtx.log   \
    --case-name demo_case

Real evidence (SIFT Workstation environment)

python main.py \
    --memory /cases/memory.raw    \
    --disk   /cases/disk.E01      \
    --logs   /cases/evtx.log      \
    --pcap   /cases/capture.pcap  \
    --case-name real_case_001

---

Output Files

File	Description
reports/final_report.md	Full incident report: executive summary, confirmed/inferred/unresolved/contradicted findings, contradiction record, self-correction sequence, confidence table, evidence table, next steps
reports/accuracy_report.md	Self-assessment: FP analysis, missed artefacts, hallucination prevention approach, architectural vs prompt guardrails
logs/execution_log.jsonl	Structured audit trail: every agent action with timestamp, confidence delta, tool called

---

Demo Scenario

The built-in mock scenario covers a fileless macro-dropper attack:

Step	What AletheiaIR does
Memory analysis	Finds PowerShell with encoded -Enc payload, C2 connection to 185.220.101.47:4444, MZ header in non-image VAD
Disk analysis	Finds no PowerShell prefetch file — key contradiction
Log analysis	Finds Event 4104 (IEX download-cradle), Event 4688 (WINWORD→cmd chain)
Contradiction detection	Flags memory↔disk conflict: process in memory, no prefetch on disk
Self-correction	Targeted malfind re-analysis confirms fileless execution indicators
Report	Finding promoted from CONTRADICTED to UNRESOLVED with explanation

Final finding status: medium confidence, unresolved — honest about the evidence gap, not hallucinating certainty.

---

Limitations

• Tool wrappers are mock-compatible stubs. Real Volatility/TSK integration requires the SIFT Workstation environment (see # TODO blocks in each wrapper).
• No LLM in the core pipeline — all finding generation is deterministic. A future version could add an LLM summarisation layer without touching the evidence integrity pipeline.
• Confidence scores are heuristic, not ground-truth validated.
• Encrypted network traffic (TLS 1.3) cannot be inspected without a private key or MITM proxy.
• Single-host scope — lateral movement is not tracked.

---

Future Work

• Real Volatility 3 subprocess integration (one function change per wrapper)
• MCP server wrapping to expose each SIFT tool as a typed MCP endpoint
• LLM summarisation layer (bounded by existing confidence + contradiction pipeline)
• SIGMA rule integration via Chainsaw for log analysis
• Persistent SQLite case database for multi-round correlation
• Web-based report viewer

---

License

MIT License. See LICENSE for full text.

RESEARCH / LAB USE ONLY — AletheiaIR is experimental. Findings are NOT court-admissible and must not be used as the sole basis for legal proceedings, employment decisions, or law enforcement action. All analysis should be reviewed by a qualified forensic examiner.