# joblinours/defair architecture

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

- Interactive diagram: https://gitdiagram.com/joblinours/defair
- Repository: https://github.com/joblinours/defair

## Overview

DEFAIR is a DFIR investigation platform: analysts or AI agents use its CLI or MCP interface to register cases and evidence, prepare inputs, run forensic profiles and tools, then inspect normalized artifacts, timelines, and findings. The README documents this overall orchestration; sampled code confirms the MCP-to-container proxy, container management, SQLite-backed artifact search, and normalization behavior. The graph preserves documented capability branches, but some links among unsampled services are intentionally omitted rather than inferred from module names.

Main entry points: [`src/defair/database.py`](https://github.com/joblinours/defair/blob/main/src/defair/database.py) (Investigation database), [`src/defair/tools`](https://github.com/joblinours/defair/tree/main/src/defair/tools) (Forensic tool adapters), [`src/defair/mcp_server/server.py`](https://github.com/joblinours/defair/blob/main/src/defair/mcp_server/server.py) (MCP server), [`src/defair/services`](https://github.com/joblinours/defair/tree/main/src/defair/services) (Service layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Analyst interfaces"]
  node_cli["DEFAIR CLI<br/>[main.py]"]
  node_mcp["MCP server<br/>[server.py]"]
end

subgraph group_investigation["Investigation management"]
  node_services["Service layer"]
  node_cases["Cases and evidence<br/>[case_service.py]"]
  node_evidence["Evidence preparation<br/>[prepare.py]"]
end

subgraph group_execution["Analysis execution"]
  node_orchestrator["Profile and run orchestration"]
  node_worker["Background workers<br/>[worker_service.py]"]
  node_tools["Forensic tool adapters"]
  node_engines["Forensic engines<br/>[main.rs]"]
  node_supertimeline["Plaso and Sleuth Kit"]
end

subgraph group_results["Results and detection"]
  node_normalize["Normalization pipeline<br/>[pipeline.py]"]
  node_artifacts["Artifact inspection"]
  node_timeline["Unified timeline"]
  node_findings["Findings and detections<br/>[finding_service.py]"]
  node_search["IOC and artifact search<br/>[search_service.py]"]
  node_watchlists["Watchlist hunting"]
  node_scanning["YARA and Sigma scans"]
  node_rules["Rule management<br/>[rules_service.py]"]
end

subgraph group_runtime["Runtime infrastructure"]
  node_containers["Container management"]
  node_database[("Investigation database<br/>[database.py]")]
end

node_analyst(("Analyst / agent"))
node_docker["Docker"]

node_analyst -->|"issues commands"| node_cli
node_analyst -->|"sends MCP requests"| node_mcp
node_cli -->|"invokes operations"| node_services
node_mcp -->|"manages containers"| node_containers
node_mcp -->|"proxies commands"| node_containers
node_services -->|"manages cases"| node_cases
node_services -->|"starts investigations"| node_orchestrator
node_cases -->|"reads and writes"| node_database
node_evidence -->|"records prepared evidence"| node_database
node_containers -->|"controls containers"| node_docker
node_orchestrator -->|"dispatches jobs"| node_worker
node_orchestrator -->|"selects tools"| node_tools
node_worker -->|"runs tools"| node_tools
node_tools -.->|"invokes engines"| node_engines
node_tools -->|"normalizes output"| node_normalize
node_normalize -->|"inserts artifacts"| node_database
node_artifacts -->|"reads artifacts"| node_database
node_search -->|"searches artifacts"| node_database
node_timeline -->|"reads timeline"| node_database
node_findings -->|"reads findings"| node_database
node_watchlists -->|"searches case data"| node_database
node_scanning -->|"runs scans"| node_tools
node_rules -->|"provides rule sets"| node_scanning
node_supertimeline -->|"dispatches timeline jobs"| node_worker
node_supertimeline -->|"imports timeline events"| node_database

click node_cli "https://github.com/joblinours/defair/blob/main/src/defair/cli/main.py"
click node_mcp "https://github.com/joblinours/defair/blob/main/src/defair/mcp_server/server.py"
click node_services "https://github.com/joblinours/defair/tree/main/src/defair/services"
click node_cases "https://github.com/joblinours/defair/blob/main/src/defair/services/case_service.py"
click node_evidence "https://github.com/joblinours/defair/blob/main/src/defair/sources/prepare.py"
click node_containers "https://github.com/joblinours/defair/blob/main/src/defair/services/container_service.py"
click node_database "https://github.com/joblinours/defair/blob/main/src/defair/database.py"
click node_orchestrator "https://github.com/joblinours/defair/tree/main/src/defair/orchestrator"
click node_worker "https://github.com/joblinours/defair/blob/main/src/defair/services/worker_service.py"
click node_tools "https://github.com/joblinours/defair/tree/main/src/defair/tools"
click node_engines "https://github.com/joblinours/defair/blob/main/engines/raijin/src/main.rs"
click node_normalize "https://github.com/joblinours/defair/blob/main/src/defair/normalizers/pipeline.py"
click node_artifacts "https://github.com/joblinours/defair/blob/main/src/defair/services/artifact_service.py"
click node_timeline "https://github.com/joblinours/defair/blob/main/src/defair/services/timeline_service.py"
click node_findings "https://github.com/joblinours/defair/blob/main/src/defair/services/finding_service.py"
click node_search "https://github.com/joblinours/defair/blob/main/src/defair/services/search_service.py"
click node_watchlists "https://github.com/joblinours/defair/blob/main/src/defair/services/watchlist_service.py"
click node_scanning "https://github.com/joblinours/defair/blob/main/src/defair/services/scanning_service.py"
click node_rules "https://github.com/joblinours/defair/blob/main/src/defair/services/rules_service.py"
click node_supertimeline "https://github.com/joblinours/defair/blob/main/src/defair/services/supertimeline_service.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_cli,node_mcp toneBlue
class node_services,node_cases,node_evidence toneAmber
class node_orchestrator,node_worker,node_tools,node_engines,node_supertimeline toneMint
class node_normalize,node_artifacts,node_timeline,node_findings,node_search,node_watchlists,node_scanning,node_rules toneRose
class node_containers,node_database,node_analyst,node_docker toneIndigo
```

## Components

### Analyst interfaces

- [DEFAIR CLI](https://github.com/joblinours/defair/blob/main/src/defair/cli/main.py): `src/defair/cli/main.py`
- [MCP server](https://github.com/joblinours/defair/blob/main/src/defair/mcp_server/server.py): `src/defair/mcp_server/server.py`

### Investigation management

- [Service layer](https://github.com/joblinours/defair/tree/main/src/defair/services): `src/defair/services`
- [Cases and evidence](https://github.com/joblinours/defair/blob/main/src/defair/services/case_service.py): `src/defair/services/case_service.py`
- [Evidence preparation](https://github.com/joblinours/defair/blob/main/src/defair/sources/prepare.py): `src/defair/sources/prepare.py`

### Analysis execution

- [Profile and run orchestration](https://github.com/joblinours/defair/tree/main/src/defair/orchestrator): `src/defair/orchestrator`
- [Background workers](https://github.com/joblinours/defair/blob/main/src/defair/services/worker_service.py): `src/defair/services/worker_service.py`
- [Forensic tool adapters](https://github.com/joblinours/defair/tree/main/src/defair/tools): `src/defair/tools`
- [Forensic engines](https://github.com/joblinours/defair/blob/main/engines/raijin/src/main.rs): `engines/raijin/src/main.rs`
- [Plaso and Sleuth Kit](https://github.com/joblinours/defair/blob/main/src/defair/services/supertimeline_service.py): `src/defair/services/supertimeline_service.py`

### Results and detection

- [Normalization pipeline](https://github.com/joblinours/defair/blob/main/src/defair/normalizers/pipeline.py): `src/defair/normalizers/pipeline.py`
- [Artifact inspection](https://github.com/joblinours/defair/blob/main/src/defair/services/artifact_service.py): `src/defair/services/artifact_service.py`
- [Unified timeline](https://github.com/joblinours/defair/blob/main/src/defair/services/timeline_service.py): `src/defair/services/timeline_service.py`
- [Findings and detections](https://github.com/joblinours/defair/blob/main/src/defair/services/finding_service.py): `src/defair/services/finding_service.py`
- [IOC and artifact search](https://github.com/joblinours/defair/blob/main/src/defair/services/search_service.py): `src/defair/services/search_service.py`
- [Watchlist hunting](https://github.com/joblinours/defair/blob/main/src/defair/services/watchlist_service.py): `src/defair/services/watchlist_service.py`
- [YARA and Sigma scans](https://github.com/joblinours/defair/blob/main/src/defair/services/scanning_service.py): `src/defair/services/scanning_service.py`
- [Rule management](https://github.com/joblinours/defair/blob/main/src/defair/services/rules_service.py): `src/defair/services/rules_service.py`

### Runtime infrastructure

- [Container management](https://github.com/joblinours/defair/blob/main/src/defair/services/container_service.py): `src/defair/services/container_service.py`
- [Investigation database](https://github.com/joblinours/defair/blob/main/src/defair/database.py): `src/defair/database.py`

### Other components

- **Analyst / agent**
- **Docker**

## Connections

- Analyst / agent → DEFAIR CLI: issues commands
- Analyst / agent → MCP server: sends MCP requests
- DEFAIR CLI → Service layer: invokes operations
- MCP server → Container management: manages containers
- MCP server → Container management: proxies commands
- Service layer → Cases and evidence: manages cases
- Service layer → Profile and run orchestration: starts investigations
- Cases and evidence → Investigation database: reads and writes
- Evidence preparation → Investigation database: records prepared evidence
- Container management → Docker: controls containers
- Profile and run orchestration → Background workers: dispatches jobs
- Profile and run orchestration → Forensic tool adapters: selects tools
- Background workers → Forensic tool adapters: runs tools
- Forensic tool adapters → Forensic engines: invokes engines
- Forensic tool adapters → Normalization pipeline: normalizes output
- Normalization pipeline → Investigation database: inserts artifacts
- Artifact inspection → Investigation database: reads artifacts
- IOC and artifact search → Investigation database: searches artifacts
- Unified timeline → Investigation database: reads timeline
- Findings and detections → Investigation database: reads findings
- Watchlist hunting → Investigation database: searches case data
- YARA and Sigma scans → Forensic tool adapters: runs scans
- Rule management → YARA and Sigma scans: provides rule sets
- Plaso and Sleuth Kit → Background workers: dispatches timeline jobs
- Plaso and Sleuth Kit → Investigation database: imports timeline events