How rienman88/blitz-dfir works
1. What this repository is
- Blitz DFIR is a Python 3.11+ digital forensics / incident response pipeline.
- It is organized as a deterministic evidence-processing system with an optional LLM explanation layer, not as an AI-first app.
2. Top-level runtime entry points
- app.py is the main application entry point.
- The blitz_dfir.pipeline.analyze module appears to orchestrate a full investigation run.
- Most behavior is driven by a case manifest and config files under config/.
3. Primary data model and case boundary
- The repository is centered on a “case” concept: evidence inputs, output roots, manifests, and run/session state.
- Raw evidence can live outside the case directory (external evidence root); Blitz writes outputs under /cases/<CASE>/output and run-specific paths under /cases/<CASE>/analysis/runs/....
- This is an important boundary: evidence is not copied by default, while derived artifacts, reports, and logs are generated inside case-managed storage.
4. Core evidence lifecycle
- The core package defines the foundational flow: evidence metadata, manifests, sessions, normalization, validation, and integrity checks.
- This layer is the authoritative source for what was analyzed and how, and it feeds later subsystems with normalized representations rather than raw tool output.
5. Tool execution layer
- The tools package wraps approved forensic executables such as Volatility, log2timeline, psort, chainsaw, tshark, yara, strings, and disk-triage tooling.
- config/tools.yaml and allowlist logic in mcp/allowlist.py constrain what can be executed.
- This is a hardened boundary: no generic shell access is exposed through the typed tool layer.
6. Parsing and normalization pipeline
- parsers/ contains format-specific adapters for outputs like EVTX, PCAP, Plaso, strings, Volatility, YARA, and disk triage.
- Parsed outputs are normalized into shared models so that different evidence types can be compared and correlated consistently.
- The core/normalization.py and parser validation modules enforce that transformation step.
7. Correlation and timeline reconstruction
- correlation/ is where normalized evidence becomes investigative structure: timelines, lineage, attack chains, evidentiary weighting, contradiction analysis, and triage.
- There is a persistence layer and a SQLite backend, indicating local structured storage for cross-artifact correlation state.
- This subsystem is the main bridge from “facts extracted” to “findings assembled.”
8. Validation, contradiction handling, and uncertainty
- validation/, signal/, and parts of correlation/ preserve uncertainty rather than collapsing it away.
- The repo explicitly models truth reconstruction, truth scoring, warnings, contradictions, coverage gaps, and integrity signals.
- This means the architecture is designed to carry confidence and limitations forward into reporting instead of presenting a single overstated conclusion.
9. Reasoning and optional AI layer
- reasoning/ contains hypothesis formation, competing hypotheses, narrative generation, explainability, verification, and “truth alignment.”
- The LLM is optional and treated as a bounded explanatory layer; it does not generate authoritative findings.
- mcp/ provides tool registry, dispatcher, and stdio/server plumbing, likely for controlled agent/tool interaction rather than direct analysis authority.
10. Planning, batching, and recovery
- planning/, batching/, and recovery/ manage how evidence and tools are scheduled, grouped, retried, and rerun.
- correction/ adds bounded retry and rerun logic when validation or execution issues require remediation.
- This layer is important for repeatability and for handling partial failures without corrupting the investigative record.
11. Audit, integrity, and accounting
- audit/ captures execution trace, progress, integrity logs, and session integrity.
- accounting/ stores event-like execution records, likely supporting reproducibility and later review.
- These subsystems form a cross-cutting observability layer that records what ran, when, and with what integrity state.
12. Reporting and deliverables
- reporting/ builds the final investigator-facing outputs: HTML, Markdown, collated outputs, findings summaries, provenance visualization, and evidence maturity views.
- The submission/ directory contains packaged judge-facing artifacts and logs, while docs/ explains workflows and expected outputs.
- Reporting consumes correlated/validated findings plus provenance and uncertainty metadata, not raw parser output.
13. Sandboxing, sanitization, and trust boundaries
- sandbox/ and sanitization/ indicate explicit isolation around tool execution and output handling.
- Sanitization/provenance/schema enforcement is especially relevant for any content that may be consumed by an LLM or exported into reports.
- The repo’s trust boundary is: external evidence and external tools are untrusted inputs; normalized, audited, validated outputs are trusted downstream.
14. Operational footprint
- The repository assumes SIFT/DFIR tooling on Linux, with optional Ollama/OpenAI-compatible LLM support.
- Shell scripts in scripts/ are operational wrappers for SIFT, VM sync, stress runs, and demo workflows; they support deployment and test execution but are not the core runtime architecture.
- CI is present via GitHub Actions, and tests cover the major subsystems end-to-end.
Main entry points: correlation Correlation · tools Tools · reporting Reporting · analyze.py Analyze
Components 21
Runtime
Entry points and orchestration
Foundation
Case model, evidence, and normalization
- Case Core · Evidence metadata, manifests, sessions, validation, and normalization boundary.
blitz_dfir/core - Normalize · Shared normalization of parsed and tool-derived evidence.
blitz_dfir/core/normalization.py - Core Validation · Integrity and validation gates for canonical evidence state.
blitz_dfir/core/validation.py
Execution
Tooling, planning, sandboxing, and recovery
- Tools · Approved forensic tool wrappers and provenance-aware execution layer.
blitz_dfir/tools - Sandbox · Execution isolation and resource limits for tool runs.
blitz_dfir/sandbox/runner.py - Planner · Evidence-first planning and batched execution selection.
blitz_dfir/planning - Recovery · Bounded retry, rerun, and remediation logic.
blitz_dfir/correction
Analysis
Parsing, correlation, validation, and reasoning
- Parsers · Format-specific adapters for tool and evidence outputs.
blitz_dfir/parsers - Correlation · Timeline, lineage, weighting, contradiction analysis, and persistence.
blitz_dfir/correlation - Truth · Truth reconstruction, scoring, and validation of findings.
blitz_dfir/validation - Reasoning · Hypotheses, narratives, verification, and bounded explanation.
blitz_dfir/reasoning - Signal · Coverage, integrity, and warning signals carried through analysis.
blitz_dfir/signal - Unknowns · Tracks unresolved uncertainty and missing information.
blitz_dfir/unknowns - Temporal · Time-oriented analysis helpers supporting timelines and ordering.
blitz_dfir/temporal/analysis.py
Outputs
Reporting and audit artifacts
Ops
Inventory, MCP, and support subsystems
- MCP · Controlled tool registry, dispatcher, and stdio/server plumbing.
blitz_dfir/mcp - Inventory · Object inventory, discovery, and tool cataloging.
blitz_dfir/inventory - Investigation · Tool guidance, recommendations, and graph of investigative actions.
blitz_dfir/investigation
Connections 24
- App → Analyze: starts · Application launches the main analysis pipeline.
- Analyze → Case Core: loads case · Pipeline consumes manifests, sessions, and case state.
- Analyze → Planner: plans work · Selects evidence and tool batches for execution.
- Planner → Tools: dispatches · Plans approved tool execution.
- Tools → Sandbox: runs in · Tool execution is isolated and constrained.
- Tools → Parsers: emits outputs · Tool outputs are parsed into structured records.
- Parsers → Normalize: normalizes · Parsed data is converted into canonical models.
- Normalize → Core Validation: checks · Normalized outputs are validated before downstream use.
- Core Validation → Correlation: feeds · Validated facts become correlated investigative structure.
- Correlation → Truth: scores · Correlation state informs truth reconstruction and scoring.
- Truth → Reasoning: grounds · Reasoning is grounded in validated and scored evidence.
- Correlation → Temporal: orders · Timeline reconstruction depends on temporal analysis.
- Correlation → Signal: tracks signals · Coverage, integrity, and warnings are preserved with findings.
- Signal → Unknowns: exposes gaps · Uncertainty and missing evidence are tracked explicitly.
- Reasoning → Reporting: explains · Reasoning produces bounded narratives and explanations.
- Truth → Reporting: authorizes · Validated findings and confidence state flow into reports.
- Correlation → Reporting: summarizes · Correlated evidence becomes investigator-facing output.
- Audit → Reporting: documents · Audit and accounting artifacts support final deliverables.
- MCP → Tools: registers · Controlled tools are exposed through the MCP boundary.
- Inventory → Investigation: guides · Discovery and catalogs inform investigation recommendations.
- Investigation → Planner: informs · Investigation guidance influences execution planning.
- Recovery → Tools: reruns · Bounded recovery can request corrected tool execution.
- Recovery → Core Validation: responds to · Validation failures can trigger rerun/remediation paths.
- Audit → Case Core: records · Execution trace and integrity state are tied back to the case.