# maaz-ansari-cys/digital-forensics-tool-vellum-ir- architecture

> Architecture diagram of the GitHub repository maaz-ansari-cys/digital-forensics-tool-vellum-ir-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-
- Repository: https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-

## Overview

VellumIR is an offline DFIR investigation platform: an analyst creates a case, uploads artifacts, and receives normalized events, detections, correlated attack sessions, enrichment, dashboard views, and downloadable reports. Flask coordinates ingestion and analysis; format detection dispatches to the unified parser set, while SQLite persists case evidence and analysis results. The README documents all seven parser formats and the dashboard/reporting capabilities; some wiring and subsystems are represented at their exact directory path because their implementation was not sampled. Dashed edges mark UI/API interaction not directly shown in the excerpts.

Main entry points: [`app.py`](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/app.py) (Flask API), [`intel/enrichment.py`](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/intel/enrichment.py) (IP Enrichment), [`core/detector.py`](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/core/detector.py) (Format Detector), [`parsers`](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/tree/main/parsers) (Log Parsers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Evidence Ingestion"]
  node_api["Flask API<br/>[app.py]"]
  node_detector["Format Detector<br/>[detector.py]"]
  node_parsers["Log Parsers"]
  node_normalizer["Event Normalizer<br/>[normalizer.py]"]
end

subgraph group_analysis["Forensic Analysis"]
  node_rules["Detection Rules<br/>[rules.py]"]
  node_correlator["Session Correlator<br/>[correlator.py]"]
  node_timefilter["Time Filtering<br/>[time_filter.py]"]
  node_metrics["Dashboard Metrics"]
end

subgraph group_intel["Threat Intelligence"]
  node_ioc["IOC Matching<br/>[ioc_matcher.py]"]
  node_geo["IP Enrichment<br/>[enrichment.py]"]
end

subgraph group_state["Case Data"]
  node_storage[("SQLite Evidence Store<br/>[storage.py]")]
end

subgraph group_outputs["Investigation Outputs"]
  node_webui["Web Interface"]
  node_summary["Executive Summary"]
  node_recommendations["Remediation Guidance<br/>[recommendations.py]"]
  node_htmlreport["HTML Reports<br/>[html_report.py]"]
  node_pdfreport["PDF Reports<br/>[pdf_report.py]"]
end

node_analyst(("Analyst"))
node_geoapi["ip-api.com"]

node_analyst -->|"uses"| node_webui
node_webui -.->|"calls API"| node_api
node_api -->|"detects formats"| node_detector
node_detector -->|"dispatches to"| node_parsers
node_parsers -->|"normalizes events"| node_normalizer
node_api -->|"persists evidence"| node_storage
node_api -->|"runs detection"| node_rules
node_api -->|"correlates events"| node_correlator
node_api -->|"filters metrics"| node_timefilter
node_api -->|"gets metrics"| node_metrics
node_api -->|"matches indicators"| node_ioc
node_api -->|"enriches IPs"| node_geo
node_geo -->|"queries"| node_geoapi
node_geo -->|"caches results"| node_storage
node_api -->|"generates summary"| node_summary
node_api -->|"gets guidance"| node_recommendations
node_api -->|"generates report"| node_htmlreport
node_api -->|"generates report"| node_pdfreport

click node_webui "https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/tree/main/web"
click node_api "https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/app.py"
click node_detector "https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/core/detector.py"
click node_parsers "https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/tree/main/parsers"
click node_normalizer "https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/core/normalizer.py"
click node_rules "https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/core/rules.py"
click node_correlator "https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/core/correlator.py"
click node_timefilter "https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/core/time_filter.py"
click node_metrics "https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/core/extended_metrics.py"
click node_ioc "https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/intel/ioc_matcher.py"
click node_geo "https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/intel/enrichment.py"
click node_storage "https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/core/storage.py"
click node_summary "https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/reports/summary_generator.py"
click node_recommendations "https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/reports/recommendations.py"
click node_htmlreport "https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/reports/html_report.py"
click node_pdfreport "https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/reports/pdf_report.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_api,node_detector,node_parsers,node_normalizer toneBlue
class node_rules,node_correlator,node_timefilter,node_metrics toneAmber
class node_ioc,node_geo,node_geoapi toneMint
class node_storage toneRose
class node_webui,node_summary,node_recommendations,node_htmlreport,node_pdfreport,node_analyst toneIndigo
```

## Components

### Evidence Ingestion

- [Flask API](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/app.py): `app.py`
- [Format Detector](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/core/detector.py): `core/detector.py`
- [Log Parsers](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/tree/main/parsers): `parsers`
- [Event Normalizer](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/core/normalizer.py): `core/normalizer.py`

### Forensic Analysis

- [Detection Rules](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/core/rules.py): `core/rules.py`
- [Session Correlator](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/core/correlator.py): `core/correlator.py`
- [Time Filtering](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/core/time_filter.py): `core/time_filter.py`
- [Dashboard Metrics](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/core/extended_metrics.py): `core/extended_metrics.py`

### Threat Intelligence

- [IOC Matching](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/intel/ioc_matcher.py): `intel/ioc_matcher.py`
- [IP Enrichment](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/intel/enrichment.py): `intel/enrichment.py`

### Case Data

- [SQLite Evidence Store](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/core/storage.py): `core/storage.py`

### Investigation Outputs

- [Web Interface](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/tree/main/web): `web`
- [Executive Summary](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/reports/summary_generator.py): `reports/summary_generator.py`
- [Remediation Guidance](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/reports/recommendations.py): `reports/recommendations.py`
- [HTML Reports](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/reports/html_report.py): `reports/html_report.py`
- [PDF Reports](https://github.com/maaz-ansari-cys/digital-forensics-tool-vellum-ir-/blob/main/reports/pdf_report.py): `reports/pdf_report.py`

### Other components

- **Analyst**
- **ip-api.com**

## Connections

- Analyst → Web Interface: uses (evidence: `README.md`)
- Web Interface → Flask API: calls API
- Flask API → Format Detector: detects formats (evidence: `app.py`)
- Format Detector → Log Parsers: dispatches to (evidence: `core/detector.py`)
- Log Parsers → Event Normalizer: normalizes events (evidence: `parsers/auth_log.py`)
- Flask API → SQLite Evidence Store: persists evidence (evidence: `app.py`)
- Flask API → Detection Rules: runs detection (evidence: `app.py`)
- Flask API → Session Correlator: correlates events (evidence: `app.py`)
- Flask API → Time Filtering: filters metrics (evidence: `app.py`)
- Flask API → Dashboard Metrics: gets metrics (evidence: `app.py`)
- Flask API → IOC Matching: matches indicators (evidence: `app.py`)
- Flask API → IP Enrichment: enriches IPs (evidence: `app.py`)
- IP Enrichment → ip-api.com: queries (evidence: `intel/enrichment.py`)
- IP Enrichment → SQLite Evidence Store: caches results (evidence: `intel/enrichment.py`)
- Flask API → Executive Summary: generates summary (evidence: `app.py`)
- Flask API → Remediation Guidance: gets guidance (evidence: `app.py`)
- Flask API → HTML Reports: generates report (evidence: `app.py`)
- Flask API → PDF Reports: generates report (evidence: `app.py`)
