# ziyadnz/threat-intel-ip-feeds architecture

> Architecture diagram of the GitHub repository ziyadnz/threat-intel-ip-feeds, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ziyadnz/threat-intel-ip-feeds
- Repository: https://github.com/ziyadnz/threat-intel-ip-feeds

## Overview

This repository aggregates threat-intelligence IP feeds into firewall-ready blocklists and richer analysis formats. Its main workflow is the CLI composition root constructing feed adapters, collecting and validating their results, filtering whitelisted addresses and tracking source health, then writing output files. Separate health reporting persists status and can notify about source problems. The README documents raw IPv4/IPv6, per-source, CSV, JSON and STIX outputs plus global and Turkey-specific feeds. Some adapter and writer wiring is documented or indexed but not shown in full excerpts, so uncertain links are omitted.

Main entry points: [`threat_intel/presentation/cli.py`](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/presentation/cli.py) (CLI composition), [`threat_intel/application/use_cases/collect_threat_intel.py`](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/application/use_cases/collect_threat_intel.py) (Collect feeds), [`threat_intel/infrastructure/sources/global_sources.py`](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/sources/global_sources.py) (Global feeds), [`threat_intel/infrastructure/sources/regional_sources.py`](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/sources/regional_sources.py) (Regional feeds)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and orchestration"]
  node_cli["CLI composition<br/>[cli.py]"]
  node_collect["Collect feeds"]
  node_write["Write outputs<br/>[write_outputs.py]"]
  node_health_report["Health reporting<br/>[report_health.py]"]
end

subgraph group_domain["Threat domain"]
  node_entities["Threat entities<br/>[entities.py]"]
  node_ports["Domain ports<br/>[ports.py]"]
  node_rules["Filtering and analysis<br/>[services.py]"]
end

subgraph group_feeds["Feed integrations"]
  node_http["HTTP client<br/>[requests_client.py]"]
  node_global_feeds["Global feeds<br/>[global_sources.py]"]
  node_regional_feeds["Regional feeds"]
  node_api_feeds["API feeds<br/>[api_sources.py]"]
  node_source_base["Feed base adapter<br/>[base.py]"]
  node_source_urls["Feed endpoints<br/>[urls.py]"]
end

subgraph group_persistence["State and reporting"]
  node_source_cache[("Feed cache<br/>[source_cache.py]")]
  node_whitelist["Whitelist file<br/>[file_repository.py]"]
  node_health_store[("Health records<br/>[json_repository.py]")]
  node_report_writer["Health report file"]
  node_notifier["GitHub notifier<br/>[github_notifier.py]"]
  node_raw_writer["Raw IP feeds<br/>[raw_writer.py]"]
  node_csv_writer["CSV output<br/>[csv_writer.py]"]
  node_json_writer["JSON output<br/>[json_writer.py]"]
  node_stix_writer["STIX bundle<br/>[stix_writer.py]"]
end

node_operator(("Hourly runner"))
node_consumers(("Firewall and SIEM"))
node_feed_services(("Threat feed services"))

node_operator -->|"invokes"| node_cli
node_cli -->|"runs"| node_collect
node_cli -->|"runs"| node_write
node_cli -.->|"configures"| node_health_report
node_cli -->|"constructs"| node_http
node_cli -->|"configures"| node_global_feeds
node_cli -->|"configures"| node_regional_feeds
node_cli -->|"configures"| node_api_feeds
node_cli -->|"configures"| node_source_cache
node_cli -->|"configures"| node_whitelist
node_cli -->|"configures"| node_health_store
node_cli -->|"configures"| node_report_writer
node_cli -->|"configures"| node_notifier
node_cli -->|"configures"| node_raw_writer
node_cli -->|"configures"| node_csv_writer
node_cli -->|"configures"| node_json_writer
node_cli -->|"configures"| node_stix_writer
node_collect -->|"fetches from"| node_global_feeds
node_collect -->|"fetches from"| node_regional_feeds
node_collect -->|"fetches from"| node_api_feeds
node_collect -->|"loads entries"| node_whitelist
node_collect -->|"reads and saves"| node_source_cache
node_collect -->|"updates health"| node_health_store
node_collect -->|"filters and analyzes"| node_rules
node_collect -->|"builds results"| node_entities
node_global_feeds -->|"uses adapters"| node_source_base
node_regional_feeds -->|"uses adapters"| node_source_base
node_global_feeds -.->|"requests feeds"| node_http
node_regional_feeds -.->|"requests feeds"| node_http
node_api_feeds -->|"requests APIs"| node_http
node_global_feeds -->|"uses endpoints"| node_source_urls
node_regional_feeds -->|"uses endpoints"| node_source_urls
node_api_feeds -->|"uses endpoints"| node_source_urls
node_write -.->|"writes via"| node_raw_writer
node_write -.->|"writes via"| node_csv_writer
node_write -.->|"writes via"| node_json_writer
node_write -.->|"writes via"| node_stix_writer
node_raw_writer -.->|"publishes feeds"| node_consumers
node_csv_writer -.->|"provides analysis"| node_consumers
node_stix_writer -.->|"provides bundle"| node_consumers
node_feed_services -.->|"supplies indicators"| node_global_feeds
node_feed_services -.->|"supplies indicators"| node_regional_feeds
node_health_report -->|"loads health"| node_health_store
node_health_report -->|"writes report"| node_report_writer
node_health_report -.->|"alerts on issues"| node_notifier

click node_cli "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/presentation/cli.py"
click node_collect "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/application/use_cases/collect_threat_intel.py"
click node_write "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/application/use_cases/write_outputs.py"
click node_health_report "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/application/use_cases/report_health.py"
click node_entities "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/domain/entities.py"
click node_ports "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/domain/ports.py"
click node_rules "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/domain/services.py"
click node_http "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/http/requests_client.py"
click node_global_feeds "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/sources/global_sources.py"
click node_regional_feeds "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/sources/regional_sources.py"
click node_api_feeds "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/sources/api_sources.py"
click node_source_base "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/sources/base.py"
click node_source_urls "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/sources/urls.py"
click node_source_cache "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/cache/source_cache.py"
click node_whitelist "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/whitelist/file_repository.py"
click node_health_store "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/health/json_repository.py"
click node_report_writer "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/health/markdown_report_writer.py"
click node_notifier "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/notification/github_notifier.py"
click node_raw_writer "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/writers/raw_writer.py"
click node_csv_writer "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/writers/csv_writer.py"
click node_json_writer "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/writers/json_writer.py"
click node_stix_writer "https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/writers/stix_writer.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_collect,node_write,node_health_report toneBlue
class node_entities,node_ports,node_rules toneAmber
class node_http,node_global_feeds,node_regional_feeds,node_api_feeds,node_source_base,node_source_urls toneMint
class node_source_cache,node_whitelist,node_health_store,node_report_writer,node_notifier,node_raw_writer,node_csv_writer,node_json_writer,node_stix_writer toneRose
class node_operator,node_consumers,node_feed_services toneIndigo
```

## Components

### Entry and orchestration

- [CLI composition](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/presentation/cli.py): `threat_intel/presentation/cli.py`
- [Collect feeds](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/application/use_cases/collect_threat_intel.py): `threat_intel/application/use_cases/collect_threat_intel.py`
- [Write outputs](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/application/use_cases/write_outputs.py): `threat_intel/application/use_cases/write_outputs.py`
- [Health reporting](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/application/use_cases/report_health.py): `threat_intel/application/use_cases/report_health.py`

### Threat domain

- [Threat entities](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/domain/entities.py): `threat_intel/domain/entities.py`
- [Domain ports](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/domain/ports.py): `threat_intel/domain/ports.py`
- [Filtering and analysis](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/domain/services.py): `threat_intel/domain/services.py`

### Feed integrations

- [HTTP client](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/http/requests_client.py): `threat_intel/infrastructure/http/requests_client.py`
- [Global feeds](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/sources/global_sources.py): `threat_intel/infrastructure/sources/global_sources.py`
- [Regional feeds](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/sources/regional_sources.py): `threat_intel/infrastructure/sources/regional_sources.py`
- [API feeds](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/sources/api_sources.py): `threat_intel/infrastructure/sources/api_sources.py`
- [Feed base adapter](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/sources/base.py): `threat_intel/infrastructure/sources/base.py`
- [Feed endpoints](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/sources/urls.py): `threat_intel/infrastructure/sources/urls.py`

### State and reporting

- [Feed cache](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/cache/source_cache.py): `threat_intel/infrastructure/cache/source_cache.py`
- [Whitelist file](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/whitelist/file_repository.py): `threat_intel/infrastructure/whitelist/file_repository.py`
- [Health records](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/health/json_repository.py): `threat_intel/infrastructure/health/json_repository.py`
- [Health report file](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/health/markdown_report_writer.py): `threat_intel/infrastructure/health/markdown_report_writer.py`
- [GitHub notifier](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/notification/github_notifier.py): `threat_intel/infrastructure/notification/github_notifier.py`
- [Raw IP feeds](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/writers/raw_writer.py): `threat_intel/infrastructure/writers/raw_writer.py`
- [CSV output](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/writers/csv_writer.py): `threat_intel/infrastructure/writers/csv_writer.py`
- [JSON output](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/writers/json_writer.py): `threat_intel/infrastructure/writers/json_writer.py`
- [STIX bundle](https://github.com/ziyadnz/threat-intel-ip-feeds/blob/main/threat_intel/infrastructure/writers/stix_writer.py): `threat_intel/infrastructure/writers/stix_writer.py`

### Other components

- **Hourly runner**
- **Firewall and SIEM**
- **Threat feed services**

## Connections

- Hourly runner → CLI composition: invokes
- CLI composition → Collect feeds: runs (evidence: `threat_intel/presentation/cli.py`)
- CLI composition → Write outputs: runs (evidence: `threat_intel/presentation/cli.py`)
- CLI composition → Health reporting: configures (evidence: `threat_intel/presentation/cli.py`)
- CLI composition → HTTP client: constructs (evidence: `threat_intel/presentation/cli.py`)
- CLI composition → Global feeds: configures (evidence: `threat_intel/presentation/cli.py`)
- CLI composition → Regional feeds: configures (evidence: `threat_intel/presentation/cli.py`)
- CLI composition → API feeds: configures (evidence: `threat_intel/presentation/cli.py`)
- CLI composition → Feed cache: configures (evidence: `threat_intel/presentation/cli.py`)
- CLI composition → Whitelist file: configures (evidence: `threat_intel/presentation/cli.py`)
- CLI composition → Health records: configures (evidence: `threat_intel/presentation/cli.py`)
- CLI composition → Health report file: configures (evidence: `threat_intel/presentation/cli.py`)
- CLI composition → GitHub notifier: configures (evidence: `threat_intel/presentation/cli.py`)
- CLI composition → Raw IP feeds: configures (evidence: `threat_intel/presentation/cli.py`)
- CLI composition → CSV output: configures (evidence: `threat_intel/presentation/cli.py`)
- CLI composition → JSON output: configures (evidence: `threat_intel/presentation/cli.py`)
- CLI composition → STIX bundle: configures (evidence: `threat_intel/presentation/cli.py`)
- Collect feeds → Global feeds: fetches from (evidence: `threat_intel/application/use_cases/collect_threat_intel.py`)
- Collect feeds → Regional feeds: fetches from (evidence: `threat_intel/application/use_cases/collect_threat_intel.py`)
- Collect feeds → API feeds: fetches from (evidence: `threat_intel/application/use_cases/collect_threat_intel.py`)
- Collect feeds → Whitelist file: loads entries (evidence: `threat_intel/application/use_cases/collect_threat_intel.py`)
- Collect feeds → Feed cache: reads and saves (evidence: `threat_intel/application/use_cases/collect_threat_intel.py`)
- Collect feeds → Health records: updates health (evidence: `threat_intel/application/use_cases/collect_threat_intel.py`)
- Collect feeds → Filtering and analysis: filters and analyzes (evidence: `threat_intel/application/use_cases/collect_threat_intel.py`)
- Collect feeds → Threat entities: builds results (evidence: `threat_intel/application/use_cases/collect_threat_intel.py`)
- Global feeds → Feed base adapter: uses adapters (evidence: `threat_intel/infrastructure/sources/global_sources.py`)
- Regional feeds → Feed base adapter: uses adapters (evidence: `threat_intel/infrastructure/sources/regional_sources.py`)
- Global feeds → HTTP client: requests feeds
- Regional feeds → HTTP client: requests feeds
- API feeds → HTTP client: requests APIs (evidence: `threat_intel/infrastructure/sources/api_sources.py`)
- Global feeds → Feed endpoints: uses endpoints (evidence: `threat_intel/infrastructure/sources/global_sources.py`)
- Regional feeds → Feed endpoints: uses endpoints (evidence: `threat_intel/infrastructure/sources/regional_sources.py`)
- API feeds → Feed endpoints: uses endpoints (evidence: `threat_intel/infrastructure/sources/api_sources.py`)
- Write outputs → Raw IP feeds: writes via
- Write outputs → CSV output: writes via
- Write outputs → JSON output: writes via
- Write outputs → STIX bundle: writes via
- Raw IP feeds → Firewall and SIEM: publishes feeds (evidence: `README.md`)
- CSV output → Firewall and SIEM: provides analysis (evidence: `README.md`)
- STIX bundle → Firewall and SIEM: provides bundle (evidence: `README.md`)
- Threat feed services → Global feeds: supplies indicators (evidence: `README.md`)
- Threat feed services → Regional feeds: supplies indicators (evidence: `README.md`)
- Health reporting → Health records: loads health (evidence: `threat_intel/application/use_cases/report_health.py`)
- Health reporting → Health report file: writes report (evidence: `threat_intel/application/use_cases/report_health.py`)
- Health reporting → GitHub notifier: alerts on issues
