# rienman88/blitz-dfir architecture

> Architecture diagram of the GitHub repository rienman88/blitz-dfir, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rienman88/blitz-dfir
- Repository: https://github.com/rienman88/blitz-dfir

## Overview

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: [`blitz_dfir/correlation`](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/correlation) (Correlation), [`blitz_dfir/tools`](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/tools) (Tools), [`blitz_dfir/reporting`](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/reporting) (Reporting), [`blitz_dfir/pipeline/analyze.py`](https://github.com/rienman88/blitz-dfir/blob/main/blitz_dfir/pipeline/analyze.py) (Analyze)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app_py["App<br/>entrypoint<br/>[app.py]"]
  node_pipeline_analyze["Analyze<br/>orchestrator<br/>[analyze.py]"]
end

subgraph group_foundation["Foundation"]
  node_core_case[("Case Core<br/>case model")]
  node_core_normalization["Normalize<br/>transform<br/>[normalization.py]"]
  node_core_validation["Core Validation<br/>checks<br/>[validation.py]"]
end

subgraph group_execution["Execution"]
  node_tools_layer["Tools<br/>tool adapters"]
  node_sandbox_runner["Sandbox<br/>isolation<br/>[runner.py]"]
  node_planning_batching["Planner<br/>scheduling"]
  node_correction_recovery["Recovery<br/>rerun control"]
end

subgraph group_analysis["Analysis"]
  node_parsers_layer["Parsers<br/>adapters"]
  node_correlation_layer[("Correlation<br/>structured analysis")]
  node_validation_truth["Truth<br/>uncertainty model"]
  node_reasoning_layer["Reasoning<br/>optional LLM"]
  node_signal_layer["Signal"]
  node_unknowns_layer["Unknowns<br/>gaps"]
  node_temporal_layer["Temporal<br/>time analysis<br/>[analysis.py]"]
end

subgraph group_outputs["Outputs"]
  node_reporting_layer["Reporting<br/>deliverables"]
  node_audit_accounting["Audit<br/>execution record"]
end

subgraph group_ops["Ops"]
  node_mcp_layer["MCP<br/>tool server"]
  node_inventory_layer["Inventory<br/>catalog"]
  node_investigation_layer["Investigation<br/>guidance"]
end

node_app_py -->|"starts"| node_pipeline_analyze
node_pipeline_analyze -->|"loads case"| node_core_case
node_pipeline_analyze -->|"plans work"| node_planning_batching
node_planning_batching -->|"dispatches"| node_tools_layer
node_tools_layer -->|"runs in"| node_sandbox_runner
node_tools_layer -->|"emits outputs"| node_parsers_layer
node_parsers_layer -->|"normalizes"| node_core_normalization
node_core_normalization -->|"checks"| node_core_validation
node_core_validation -->|"feeds"| node_correlation_layer
node_correlation_layer -->|"scores"| node_validation_truth
node_validation_truth -->|"grounds"| node_reasoning_layer
node_correlation_layer -->|"orders"| node_temporal_layer
node_correlation_layer -->|"tracks signals"| node_signal_layer
node_signal_layer -->|"exposes gaps"| node_unknowns_layer
node_reasoning_layer -->|"explains"| node_reporting_layer
node_validation_truth -->|"authorizes"| node_reporting_layer
node_correlation_layer -->|"summarizes"| node_reporting_layer
node_audit_accounting -->|"documents"| node_reporting_layer
node_mcp_layer -->|"registers"| node_tools_layer
node_inventory_layer -->|"guides"| node_investigation_layer
node_investigation_layer -->|"informs"| node_planning_batching
node_correction_recovery -->|"reruns"| node_tools_layer
node_correction_recovery -->|"responds to"| node_core_validation
node_audit_accounting -->|"records"| node_core_case

click node_app_py "https://github.com/rienman88/blitz-dfir/blob/main/app.py"
click node_pipeline_analyze "https://github.com/rienman88/blitz-dfir/blob/main/blitz_dfir/pipeline/analyze.py"
click node_core_case "https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/core"
click node_core_normalization "https://github.com/rienman88/blitz-dfir/blob/main/blitz_dfir/core/normalization.py"
click node_core_validation "https://github.com/rienman88/blitz-dfir/blob/main/blitz_dfir/core/validation.py"
click node_tools_layer "https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/tools"
click node_sandbox_runner "https://github.com/rienman88/blitz-dfir/blob/main/blitz_dfir/sandbox/runner.py"
click node_planning_batching "https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/planning"
click node_correction_recovery "https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/correction"
click node_parsers_layer "https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/parsers"
click node_correlation_layer "https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/correlation"
click node_validation_truth "https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/validation"
click node_reasoning_layer "https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/reasoning"
click node_reporting_layer "https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/reporting"
click node_audit_accounting "https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/audit"
click node_mcp_layer "https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/mcp"
click node_inventory_layer "https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/inventory"
click node_investigation_layer "https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/investigation"
click node_signal_layer "https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/signal"
click node_unknowns_layer "https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/unknowns"
click node_temporal_layer "https://github.com/rienman88/blitz-dfir/blob/main/blitz_dfir/temporal/analysis.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_py,node_pipeline_analyze toneBlue
class node_core_case,node_core_normalization,node_core_validation toneAmber
class node_tools_layer,node_sandbox_runner,node_planning_batching,node_correction_recovery toneMint
class node_parsers_layer,node_correlation_layer,node_validation_truth,node_reasoning_layer,node_signal_layer,node_unknowns_layer,node_temporal_layer toneRose
class node_reporting_layer,node_audit_accounting toneIndigo
class node_mcp_layer,node_inventory_layer,node_investigation_layer toneTeal
```

## Components

### Runtime

Entry points and orchestration

- [App](https://github.com/rienman88/blitz-dfir/blob/main/app.py): entrypoint · Main application entry point. · `app.py`
- [Analyze](https://github.com/rienman88/blitz-dfir/blob/main/blitz_dfir/pipeline/analyze.py): orchestrator · Top-level investigation pipeline run. · `blitz_dfir/pipeline/analyze.py`

### Foundation

Case model, evidence, and normalization

- [Case Core](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/core): case model · Evidence metadata, manifests, sessions, validation, and normalization boundary. · `blitz_dfir/core`
- [Normalize](https://github.com/rienman88/blitz-dfir/blob/main/blitz_dfir/core/normalization.py): transform · Shared normalization of parsed and tool-derived evidence. · `blitz_dfir/core/normalization.py`
- [Core Validation](https://github.com/rienman88/blitz-dfir/blob/main/blitz_dfir/core/validation.py): checks · Integrity and validation gates for canonical evidence state. · `blitz_dfir/core/validation.py`

### Execution

Tooling, planning, sandboxing, and recovery

- [Tools](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/tools): tool adapters · Approved forensic tool wrappers and provenance-aware execution layer. · `blitz_dfir/tools`
- [Sandbox](https://github.com/rienman88/blitz-dfir/blob/main/blitz_dfir/sandbox/runner.py): isolation · Execution isolation and resource limits for tool runs. · `blitz_dfir/sandbox/runner.py`
- [Planner](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/planning): scheduling · Evidence-first planning and batched execution selection. · `blitz_dfir/planning`
- [Recovery](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/correction): rerun control · Bounded retry, rerun, and remediation logic. · `blitz_dfir/correction`

### Analysis

Parsing, correlation, validation, and reasoning

- [Parsers](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/parsers): adapters · Format-specific adapters for tool and evidence outputs. · `blitz_dfir/parsers`
- [Correlation](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/correlation): structured analysis · Timeline, lineage, weighting, contradiction analysis, and persistence. · `blitz_dfir/correlation`
- [Truth](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/validation): uncertainty model · Truth reconstruction, scoring, and validation of findings. · `blitz_dfir/validation`
- [Reasoning](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/reasoning): optional LLM · Hypotheses, narratives, verification, and bounded explanation. · `blitz_dfir/reasoning`
- [Signal](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/signal): risk signals · Coverage, integrity, and warning signals carried through analysis. · `blitz_dfir/signal`
- [Unknowns](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/unknowns): gaps · Tracks unresolved uncertainty and missing information. · `blitz_dfir/unknowns`
- [Temporal](https://github.com/rienman88/blitz-dfir/blob/main/blitz_dfir/temporal/analysis.py): time analysis · Time-oriented analysis helpers supporting timelines and ordering. · `blitz_dfir/temporal/analysis.py`

### Outputs

Reporting and audit artifacts

- [Reporting](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/reporting): deliverables · HTML, Markdown, provenance, maturity, and findings exports. · `blitz_dfir/reporting`
- [Audit](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/audit): execution record · Execution trace, progress, integrity logs, and event accounting. · `blitz_dfir/audit`

### Ops

Inventory, MCP, and support subsystems

- [MCP](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/mcp): tool server · Controlled tool registry, dispatcher, and stdio/server plumbing. · `blitz_dfir/mcp`
- [Inventory](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/inventory): catalog · Object inventory, discovery, and tool cataloging. · `blitz_dfir/inventory`
- [Investigation](https://github.com/rienman88/blitz-dfir/tree/main/blitz_dfir/investigation): guidance · Tool guidance, recommendations, and graph of investigative actions. · `blitz_dfir/investigation`

## Connections

- 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.
