# sh3n0bi/netforensicai architecture

> Architecture diagram of the GitHub repository sh3n0bi/netforensicai, 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/sh3n0bi/netforensicai
- Repository: https://github.com/sh3n0bi/netforensicai

## Overview

NetForensicAI is a local-first digital-forensics workbench: investigators ingest packet captures and endpoint logs into a case, then examine correlated events, entities, detections, findings, and evidence-cited reports. The graph follows that shared workflow and includes investigation, live capture, and optional enrichment capabilities documented in the README. Source excerpts directly establish the ingestion dispatch and persistence path; links for other documented capabilities are limited to their supported module paths.

Main entry points: [`netforensicai/cli.py`](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/cli.py) (CLI), [`netforensicai/core/pipeline.py`](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/pipeline.py) (Ingestion pipeline), [`netforensicai/web/app.py`](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/web/app.py) (Local web UI), [`netforensicai/core/finding.py`](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/finding.py) (Investigator findings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Investigator interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_web["Local web UI<br/>[app.py]"]
end

subgraph group_evidence["Evidence ingestion"]
  node_case["Case management<br/>[case.py]"]
  node_capture["Live capture<br/>[capture.py]"]
  node_pipeline["Ingestion pipeline<br/>[pipeline.py]"]
  node_parsers["Format parsers"]
  node_pcap_engine["PCAP engine selection<br/>[pcap_engine.py]"]
  node_wireshark["Wireshark tools<br/>[wireshark.py]"]
end

subgraph group_analysis["Case analysis"]
  node_store[("Case event store<br/>[store.py]")]
  node_entities["Entity extraction<br/>[entities.py]"]
  node_correlation["Event correlation<br/>[correlation.py]"]
  node_timeline["Unified timeline<br/>[timeline.py]"]
  node_detections["Deterministic detections<br/>[detections.py]"]
end

subgraph group_investigation["Investigation outputs"]
  node_search["Packet content search<br/>[search.py]"]
  node_investigate["Indicator investigation<br/>[investigate.py]"]
  node_ioc["IOC feed import<br/>[ioc.py]"]
  node_findings["Investigator findings<br/>[finding.py]"]
  node_report["Reports and export<br/>[report.py]"]
  node_audit["Custody audit<br/>[audit.py]"]
end

subgraph group_enrichment["Optional enrichment"]
  node_agents["AI investigation team<br/>[coordinator.py]"]
  node_assistant["AI assistant<br/>[ai_assistant.py]"]
  node_virustotal["VirusTotal lookup<br/>[virustotal.py]"]
end

node_investigator(("Investigator"))
node_external_intel{{"VirusTotal service"}}

node_investigator -->|"runs commands"| node_cli
node_investigator -->|"uses UI"| node_web
node_cli -->|"manages cases"| node_case
node_web -->|"manages cases"| node_case
node_cli -->|"parses evidence"| node_pipeline
node_web -->|"analyzes uploads"| node_pipeline
node_capture -->|"ingests rotations"| node_pipeline
node_pipeline -->|"dispatches parsing"| node_parsers
node_parsers -->|"selects PCAP parser"| node_pcap_engine
node_pcap_engine -->|"checks availability"| node_wireshark
node_pipeline -->|"writes events"| node_store
node_pipeline -->|"extracts entity IDs"| node_entities
node_entities -->|"stores entities"| node_store
node_pipeline -->|"records ingest"| node_audit
node_cli -->|"builds timeline"| node_timeline
node_cli -->|"runs detections"| node_detections
node_cli -->|"investigates indicators"| node_investigate
node_cli -->|"searches captures"| node_search
node_cli -->|"imports feeds"| node_ioc
node_cli -->|"manages findings"| node_findings
node_cli -->|"generates reports"| node_report
node_web -->|"views timeline"| node_timeline
node_web -->|"manages findings"| node_findings
node_web -->|"imports feeds"| node_ioc
node_agents -.->|"proposes cited findings"| node_findings
node_assistant -.->|"offers assistance"| node_investigator
node_virustotal -.->|"queries reputation"| node_external_intel

click node_cli "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/cli.py"
click node_web "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/web/app.py"
click node_case "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/case.py"
click node_capture "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/capture.py"
click node_pipeline "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/pipeline.py"
click node_parsers "https://github.com/sh3n0bi/netforensicai/tree/NetForensicAI/netforensicai/parsers"
click node_pcap_engine "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/parsers/pcap_engine.py"
click node_wireshark "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/integrations/wireshark.py"
click node_store "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/store.py"
click node_entities "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/entities.py"
click node_correlation "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/correlation.py"
click node_timeline "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/timeline.py"
click node_detections "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/detections.py"
click node_search "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/search.py"
click node_investigate "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/investigate.py"
click node_ioc "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/ioc.py"
click node_findings "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/finding.py"
click node_report "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/report.py"
click node_audit "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/audit.py"
click node_agents "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/agents/coordinator.py"
click node_assistant "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/ai_assistant.py"
click node_virustotal "https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/intel/virustotal.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_web toneBlue
class node_case,node_capture,node_pipeline,node_parsers,node_pcap_engine,node_wireshark toneAmber
class node_store,node_entities,node_correlation,node_timeline,node_detections toneMint
class node_search,node_investigate,node_ioc,node_findings,node_report,node_audit toneRose
class node_agents,node_assistant,node_virustotal,node_investigator,node_external_intel toneIndigo
```

## Components

### Investigator interfaces

- [CLI](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/cli.py): `netforensicai/cli.py`
- [Local web UI](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/web/app.py): `netforensicai/web/app.py`

### Evidence ingestion

- [Case management](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/case.py): `netforensicai/core/case.py`
- [Live capture](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/capture.py): `netforensicai/core/capture.py`
- [Ingestion pipeline](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/pipeline.py): `netforensicai/core/pipeline.py`
- [Format parsers](https://github.com/sh3n0bi/netforensicai/tree/NetForensicAI/netforensicai/parsers): `netforensicai/parsers`
- [PCAP engine selection](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/parsers/pcap_engine.py): `netforensicai/parsers/pcap_engine.py`
- [Wireshark tools](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/integrations/wireshark.py): `netforensicai/integrations/wireshark.py`

### Case analysis

- [Case event store](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/store.py): `netforensicai/core/store.py`
- [Entity extraction](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/entities.py): `netforensicai/core/entities.py`
- [Event correlation](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/correlation.py): `netforensicai/core/correlation.py`
- [Unified timeline](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/timeline.py): `netforensicai/core/timeline.py`
- [Deterministic detections](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/detections.py): `netforensicai/core/detections.py`

### Investigation outputs

- [Packet content search](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/search.py): `netforensicai/core/search.py`
- [Indicator investigation](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/investigate.py): `netforensicai/core/investigate.py`
- [IOC feed import](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/ioc.py): `netforensicai/core/ioc.py`
- [Investigator findings](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/finding.py): `netforensicai/core/finding.py`
- [Reports and export](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/report.py): `netforensicai/core/report.py`
- [Custody audit](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/audit.py): `netforensicai/core/audit.py`

### Optional enrichment

- [AI investigation team](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/agents/coordinator.py): `netforensicai/agents/coordinator.py`
- [AI assistant](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/core/ai_assistant.py): `netforensicai/core/ai_assistant.py`
- [VirusTotal lookup](https://github.com/sh3n0bi/netforensicai/blob/NetForensicAI/netforensicai/intel/virustotal.py): `netforensicai/intel/virustotal.py`

### Other components

- **Investigator**
- **VirusTotal service**

## Connections

- Investigator → CLI: runs commands
- Investigator → Local web UI: uses UI
- CLI → Case management: manages cases
- Local web UI → Case management: manages cases
- CLI → Ingestion pipeline: parses evidence
- Local web UI → Ingestion pipeline: analyzes uploads
- Live capture → Ingestion pipeline: ingests rotations
- Ingestion pipeline → Format parsers: dispatches parsing
- Format parsers → PCAP engine selection: selects PCAP parser
- PCAP engine selection → Wireshark tools: checks availability
- Ingestion pipeline → Case event store: writes events
- Ingestion pipeline → Entity extraction: extracts entity IDs
- Entity extraction → Case event store: stores entities
- Ingestion pipeline → Custody audit: records ingest
- CLI → Unified timeline: builds timeline
- CLI → Deterministic detections: runs detections
- CLI → Indicator investigation: investigates indicators
- CLI → Packet content search: searches captures
- CLI → IOC feed import: imports feeds
- CLI → Investigator findings: manages findings
- CLI → Reports and export: generates reports
- Local web UI → Unified timeline: views timeline
- Local web UI → Investigator findings: manages findings
- Local web UI → IOC feed import: imports feeds
- AI investigation team → Investigator findings: proposes cited findings
- AI assistant → Investigator: offers assistance
- VirusTotal lookup → VirusTotal service: queries reputation