# nagasivagunturu/ioc-insight architecture

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

- Interactive diagram: https://gitdiagram.com/nagasivagunturu/ioc-insight
- Repository: https://github.com/nagasivagunturu/ioc-insight

## Overview

IOC Insight is a command-line threat-intelligence assessment tool: an analyst supplies an IOC and type, the application queries applicable providers, converts their responses into a common representation, consolidates findings and failures, scores and classifies the result, then renders an explainable report. The README documents the provider coverage and assessment features; sampled entry-point and module code confirms the central orchestration and analysis calls. DataLoader and the AbuseIPDB/ThreatFox processors are indexed but not excerpted, so their internal call relationships are left unverified where necessary.

Main entry points: [`main.py`](https://github.com/nagasivagunturu/ioc-insight/blob/main/main.py) (CLI workflow), [`utils/data_loader.py`](https://github.com/nagasivagunturu/ioc-insight/blob/main/utils/data_loader.py) (Response loading), [`models/intel.py`](https://github.com/nagasivagunturu/ioc-insight/blob/main/models/intel.py) (Provider intelligence), [`clients/otx_client.py`](https://github.com/nagasivagunturu/ioc-insight/blob/main/clients/otx_client.py) (OTX client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input and configuration"]
  node_cli["CLI workflow<br/>[main.py]"]
  node_ioc["IOC value<br/>[ioc.py]"]
  node_validator["IOC validation<br/>[ioc_validator.py]"]
  node_configuration["API configuration<br/>[config_loader.py]"]
end

subgraph group_collection["Provider collection"]
  node_data_loader["Response loading<br/>[data_loader.py]"]
  node_otx_client["OTX client<br/>[otx_client.py]"]
  node_threatfox_client["ThreatFox client"]
  node_abuse_client["AbuseIPDB client"]
  node_otx_processor["OTX normalization<br/>[otx_processor.py]"]
  node_threatfox_processor["ThreatFox normalization"]
  node_abuse_processor["AbuseIPDB normalization"]
end

subgraph group_analysis["Intelligence analysis"]
  node_intel_model["Provider intelligence<br/>[intel.py]"]
  node_aggregator["Intel aggregation"]
  node_consolidated["Consolidated findings"]
  node_analyzer["Scoring and analysis<br/>[intel_analyzer.py]"]
  node_assessment["Assessment model"]
end

subgraph group_output["Assessment output"]
  node_renderer["Report renderer"]
end

node_analyst(("Analyst"))
node_otx_service{{"AlienVault OTX"}}
node_threatfox_service{{"ThreatFox API"}}
node_abuse_service{{"AbuseIPDB API"}}

node_analyst -->|"provides IOC"| node_cli
node_cli -->|"validates input"| node_validator
node_cli -->|"creates IOC"| node_ioc
node_cli -->|"loads responses"| node_data_loader
node_data_loader -.->|"invokes lookup"| node_otx_client
node_data_loader -.->|"invokes lookup"| node_threatfox_client
node_data_loader -.->|"invokes lookup"| node_abuse_client
node_otx_client -->|"gets API key"| node_configuration
node_threatfox_client -->|"gets API key"| node_configuration
node_abuse_client -->|"gets API key"| node_configuration
node_otx_client -->|"queries"| node_otx_service
node_threatfox_client -->|"queries"| node_threatfox_service
node_abuse_client -->|"queries"| node_abuse_service
node_cli -->|"processes response"| node_otx_processor
node_cli -->|"processes response"| node_threatfox_processor
node_cli -->|"processes response"| node_abuse_processor
node_otx_processor -->|"creates intelligence"| node_intel_model
node_threatfox_processor -->|"creates intelligence"| node_intel_model
node_abuse_processor -->|"creates intelligence"| node_intel_model
node_cli -->|"aggregates results"| node_aggregator
node_aggregator -->|"merges records"| node_intel_model
node_aggregator -->|"produces findings"| node_consolidated
node_cli -->|"analyzes findings"| node_analyzer
node_analyzer -->|"reads findings"| node_consolidated
node_analyzer -->|"creates assessment"| node_assessment
node_cli -->|"renders assessment"| node_renderer
node_renderer -->|"displays fields"| node_assessment

click node_cli "https://github.com/nagasivagunturu/ioc-insight/blob/main/main.py"
click node_ioc "https://github.com/nagasivagunturu/ioc-insight/blob/main/models/ioc.py"
click node_validator "https://github.com/nagasivagunturu/ioc-insight/blob/main/utils/ioc_validator.py"
click node_configuration "https://github.com/nagasivagunturu/ioc-insight/blob/main/config/config_loader.py"
click node_data_loader "https://github.com/nagasivagunturu/ioc-insight/blob/main/utils/data_loader.py"
click node_otx_client "https://github.com/nagasivagunturu/ioc-insight/blob/main/clients/otx_client.py"
click node_threatfox_client "https://github.com/nagasivagunturu/ioc-insight/blob/main/clients/threatfox_client.py"
click node_abuse_client "https://github.com/nagasivagunturu/ioc-insight/blob/main/clients/abuseipdb_client.py"
click node_otx_processor "https://github.com/nagasivagunturu/ioc-insight/blob/main/processors/otx_processor.py"
click node_threatfox_processor "https://github.com/nagasivagunturu/ioc-insight/blob/main/processors/threatfox_processor.py"
click node_abuse_processor "https://github.com/nagasivagunturu/ioc-insight/blob/main/processors/abuseipdb_processor.py"
click node_intel_model "https://github.com/nagasivagunturu/ioc-insight/blob/main/models/intel.py"
click node_aggregator "https://github.com/nagasivagunturu/ioc-insight/blob/main/aggregator/intel_aggregator.py"
click node_consolidated "https://github.com/nagasivagunturu/ioc-insight/blob/main/models/consolidated_intel.py"
click node_analyzer "https://github.com/nagasivagunturu/ioc-insight/blob/main/analyzers/intel_analyzer.py"
click node_assessment "https://github.com/nagasivagunturu/ioc-insight/blob/main/models/intelligence_assessment.py"
click node_renderer "https://github.com/nagasivagunturu/ioc-insight/blob/main/renderers/assessment_renderer.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_ioc,node_validator,node_configuration toneBlue
class node_data_loader,node_otx_client,node_threatfox_client,node_abuse_client,node_otx_processor,node_threatfox_processor,node_abuse_processor toneAmber
class node_intel_model,node_aggregator,node_consolidated,node_analyzer,node_assessment,node_threatfox_service,node_abuse_service toneMint
class node_renderer toneRose
class node_analyst,node_otx_service toneIndigo
```

## Components

### Input and configuration

- [CLI workflow](https://github.com/nagasivagunturu/ioc-insight/blob/main/main.py): `main.py`
- [IOC value](https://github.com/nagasivagunturu/ioc-insight/blob/main/models/ioc.py): `models/ioc.py`
- [IOC validation](https://github.com/nagasivagunturu/ioc-insight/blob/main/utils/ioc_validator.py): `utils/ioc_validator.py`
- [API configuration](https://github.com/nagasivagunturu/ioc-insight/blob/main/config/config_loader.py): `config/config_loader.py`

### Provider collection

- [Response loading](https://github.com/nagasivagunturu/ioc-insight/blob/main/utils/data_loader.py): `utils/data_loader.py`
- [OTX client](https://github.com/nagasivagunturu/ioc-insight/blob/main/clients/otx_client.py): `clients/otx_client.py`
- [ThreatFox client](https://github.com/nagasivagunturu/ioc-insight/blob/main/clients/threatfox_client.py): `clients/threatfox_client.py`
- [AbuseIPDB client](https://github.com/nagasivagunturu/ioc-insight/blob/main/clients/abuseipdb_client.py): `clients/abuseipdb_client.py`
- [OTX normalization](https://github.com/nagasivagunturu/ioc-insight/blob/main/processors/otx_processor.py): `processors/otx_processor.py`
- [ThreatFox normalization](https://github.com/nagasivagunturu/ioc-insight/blob/main/processors/threatfox_processor.py): `processors/threatfox_processor.py`
- [AbuseIPDB normalization](https://github.com/nagasivagunturu/ioc-insight/blob/main/processors/abuseipdb_processor.py): `processors/abuseipdb_processor.py`

### Intelligence analysis

- [Provider intelligence](https://github.com/nagasivagunturu/ioc-insight/blob/main/models/intel.py): `models/intel.py`
- [Intel aggregation](https://github.com/nagasivagunturu/ioc-insight/blob/main/aggregator/intel_aggregator.py): `aggregator/intel_aggregator.py`
- [Consolidated findings](https://github.com/nagasivagunturu/ioc-insight/blob/main/models/consolidated_intel.py): `models/consolidated_intel.py`
- [Scoring and analysis](https://github.com/nagasivagunturu/ioc-insight/blob/main/analyzers/intel_analyzer.py): `analyzers/intel_analyzer.py`
- [Assessment model](https://github.com/nagasivagunturu/ioc-insight/blob/main/models/intelligence_assessment.py): `models/intelligence_assessment.py`

### Assessment output

- [Report renderer](https://github.com/nagasivagunturu/ioc-insight/blob/main/renderers/assessment_renderer.py): `renderers/assessment_renderer.py`

### Other components

- **Analyst**
- **AlienVault OTX**
- **ThreatFox API**
- **AbuseIPDB API**

## Connections

- Analyst → CLI workflow: provides IOC (evidence: `README.md`)
- CLI workflow → IOC validation: validates input (evidence: `main.py`)
- CLI workflow → IOC value: creates IOC (evidence: `main.py`)
- CLI workflow → Response loading: loads responses (evidence: `main.py`)
- Response loading → OTX client: invokes lookup
- Response loading → ThreatFox client: invokes lookup
- Response loading → AbuseIPDB client: invokes lookup
- OTX client → API configuration: gets API key (evidence: `clients/otx_client.py`)
- ThreatFox client → API configuration: gets API key (evidence: `clients/threatfox_client.py`)
- AbuseIPDB client → API configuration: gets API key (evidence: `clients/abuseipdb_client.py`)
- OTX client → AlienVault OTX: queries (evidence: `clients/otx_client.py`)
- ThreatFox client → ThreatFox API: queries (evidence: `clients/threatfox_client.py`)
- AbuseIPDB client → AbuseIPDB API: queries (evidence: `clients/abuseipdb_client.py`)
- CLI workflow → OTX normalization: processes response (evidence: `main.py`)
- CLI workflow → ThreatFox normalization: processes response (evidence: `main.py`)
- CLI workflow → AbuseIPDB normalization: processes response (evidence: `main.py`)
- OTX normalization → Provider intelligence: creates intelligence (evidence: `processors/otx_processor.py`)
- ThreatFox normalization → Provider intelligence: creates intelligence (evidence: `processors/threatfox_processor.py`)
- AbuseIPDB normalization → Provider intelligence: creates intelligence (evidence: `README.md`)
- CLI workflow → Intel aggregation: aggregates results (evidence: `main.py`)
- Intel aggregation → Provider intelligence: merges records (evidence: `aggregator/intel_aggregator.py`)
- Intel aggregation → Consolidated findings: produces findings (evidence: `aggregator/intel_aggregator.py`)
- CLI workflow → Scoring and analysis: analyzes findings (evidence: `main.py`)
- Scoring and analysis → Consolidated findings: reads findings (evidence: `analyzers/intel_analyzer.py`)
- Scoring and analysis → Assessment model: creates assessment (evidence: `analyzers/intel_analyzer.py`)
- CLI workflow → Report renderer: renders assessment (evidence: `main.py`)
- Report renderer → Assessment model: displays fields (evidence: `renderers/assessment_renderer.py`)