TC-SGB-API-to-List

Automated Threat Intelligence Pipeline for the T.C. Siber Güvenlik Başkanlığı (Cyber Security Presidency) API

Overview

TC-SGB-API-to-List fetches IoC (Indicator of Compromise) data from the TC SGB public API (https://siberguvenlik.gov.tr/api/), processes it through a robust multi-stage pipeline, and outputs structured threat intelligence in 16 interoperable formats compatible with leading DNS filtering and security tools.

Features

Automated IoC Fetching — Paginated retrieval from the TC SGB API with retry logic and rate limiting
Validation & Normalization — Pydantic-based data models with IoC type inference and format normalization
Deduplication — Efficient set-based deduplication across fetches
Quality Scoring — Multi-factor quality assessment for each IoC
16 Output Formats:
- DNS: NextDNS, AdGuard, Pi-hole, dnsmasq, Unbound, RPZ, Technitium, MikroTik
- Firewall: nftables, ipset
- IDS/IPS: Suricata, CrowdSec
- Data: CSV, JSON, YAML, SQLite
Scheduled Pipeline — GitHub Actions cron for automated updates every day (19:00 UTC)
Bilingual Documentation — Full English and Turkish documentation

Quick Start

Prerequisites

Python 3.11+
pip or Poetry

Installation

git clone https://github.com/bayraktarozcan/TC-SGB-API-to-List.git
cd TC-SGB-API-to-List
pip install -e .

Usage

# Run the full pipeline
tc-sgb fetch

# Generate outputs from previously saved raw data
tc-sgb generate -i Output/raw_records.json

# Fetch and display health status
tc-sgb health

# Fetch third-party threat feeds (CERT.PL, CERT.SI, blacklist.gov.az)
tc-sgb fetch-external

# Verify published external lists against the safety policy (no fetching)
tc-sgb validate-external

Data Download

Latest pre-generated IoC outputs are published automatically (daily, 19:00 UTC) to the rolling GitHub Release ioc-data. The five large-format files are distributed through stable download URLs (small formats remain tracked in the Output/ directory):

Format	File	Size (approx.)
Raw records	raw_records.json	129 MB
Structured JSON	threat_intel_json.json	130 MB
SQLite database	threat_intel_sqlite.db	96 MB
Suricata JSON	threat_intel_suricata.json	203 MB
Structured YAML	threat_intel_yaml.yaml	97 MB

Download via wget/curl/Invoke-WebRequest or browse the release page. All other formats are generated to Output/ when you run the pipeline locally.

Brave / AdGuard users: release-asset links are served as file downloads, which Brave rejects as custom filter lists. Subscribe to the plain-text mirror instead (brave://adblock → Add filter list via URL); it is refreshed daily. Three more curated lists (Poland, Azerbaijan, Slovenia) are published on the same branch and refreshed by the same workflow; files are numbered so Brave shows them in country order (04 is reserved for Lithuania):

02-polonya-certpl_adguard.txt

03-azerbaycan-blacklist_adguard.txt

05-slovenya-certsi_adguard.txt

Publication safety

Syntax validation checks rule shape; the safety policy in Scripts/src/safety.py decides whether blocking a host wholesale is safe to publish. High-impact hosts are rejected outright, shared user-content infrastructure goes to review, and every held indicator lands in a per-feed audit file (Output/External/) with its reason — never silently dropped. The scheduled workflow publishes only lists passing tc-sgb validate-external; a failing feed keeps serving its last good snapshot.

Project Structure

TC-SGB-API-to-List/
├── Scripts/
│   ├── main.py                  # CLI entry point
│   └── src/
│       ├── models.py            # Pydantic data models
│       ├── client.py            # Async API client
│       ├── external_feeds.py    # Third-party threat-feed mirrors
│       ├── safety.py            # Publication safety policy (shared)
│       ├── validator.py         # IoC validation
│       ├── normalizer.py        # IoC normalization
│       ├── deduplicator.py      # Deduplication
│       ├── quality.py           # Quality scoring
│       ├── outputs.py           # 16 output format generators
│       └── pipeline.py          # Pipeline orchestrator
├── Tests/                       # Test suite
├── Docs/                        # Documentation (bilingual)
├── Schema/                      # JSON Schema & OpenAPI spec
├── Data/                        # Runtime data cache
├── Output/                      # Generated IoC output files (small formats tracked; large formats via `ioc-data` release)
├── Examples/                    # Usage examples
├── Benchmark/                   # Performance benchmarks
└── .github/workflows/           # CI/CD pipelines

Documentation

Document	Description
Architecture	System design and component overview
Data Flow	Pipeline data flow and transformations
Module Architecture	Module responsibilities and interfaces
Repository Structure	Directory layout and file purposes
API Analysis	TC SGB API endpoints and capabilities
Data Model	Pydantic models and schemas
Threat Model	STRIDE threat analysis
Security Analysis	Security posture and hardening
License Analysis	Legal and licensing considerations
Test Strategy	Testing approach and coverage
Regression Strategy	Regression testing methodology
Performance Strategy	Performance benchmarks and optimization
Versioning Strategy	Semantic versioning approach
Publishing Strategy	Distribution and publishing
Maintenance Plan	Ongoing maintenance procedures
Risk Analysis	Risk assessment and mitigation
Roadmap	Development roadmap
Legal Notices	Legal and compliance notices

Project documents

Document	Description
Changelog	Version history
Contributing	Contribution guidelines
Security	Security reporting process
Support	Where to ask questions and how to report an issue
Privacy	What the project collects, stores, and transmits
Code of Conduct	Code of conduct
Release notes	Skeleton that release notes follow
Agent guide	Operating rules for humans and coding agents
License	License terms
Notice	Third-party attribution and trademark notices
Code owners	Defines code owners

Configuration

Copy .env.example to .env and configure as needed:

cp .env.example .env

Development

# Install dev dependencies
pip install -e ".[dev]"
pip install -r requirements.txt

# Run tests
pytest Tests/ -v

# Run linter
ruff check Scripts/ Tests/

# Run type checker
mypy Scripts/

Roadmap

Core pipeline (fetch → validate → normalize → score → dedup → output)
16 output formats
CI/CD with GitHub Actions
Comprehensive test suite
Docker containerization
PyPI publishing
Additional threat intel sources (CISA KEV, Spamhaus, URLhaus)
Web dashboard

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

License

This project is licensed under the MIT License. See LEGAL_NOTICES for important legal information regarding data redistribution.

Disclaimer

This tool is provided as-is for legitimate cybersecurity research and defense purposes. Users are responsible for compliance with all applicable laws and regulations.

TC-SGB-API-to-List

T.C. Siber Güvenlik Başkanlığı (Cyber Security Presidency) API'si için Otomatik Tehdit İstihbaratı Hattı

Genel Bakış

TC-SGB-API-to-List, TC SGB kamu API'sinden (https://siberguvenlik.gov.tr/api/) IoC (İhlal Göstergesi) verilerini çeker, güçlü bir çok aşamalı hat üzerinden işler ve 16 birlikte çalışabilir biçimde yapılandırılmış tehdit istihbaratı çıktısı üretir.

Özellikler

Otomatik IoC Çekme — Yeniden deneme mantığı ve hız sınırlaması ile sayfalı veri çekme
Doğrulama ve Normalleştirme — Pydantic tabanlı veri modelleri ile IoC türü çıkarma ve biçim normalleştirme
Tekilleştirme — Çekimler arasında verimli küme tabanlı tekilleştirme
Kalite Puanlama — Her IoC için çok faktörlü kalite değerlendirmesi
16 Çıktı Formatı:
- DNS: NextDNS, AdGuard, Pi-hole, dnsmasq, Unbound, RPZ, Technitium, MikroTik
- Güvenlik Duvarı: nftables, ipset
- IDS/IPS: Suricata, CrowdSec
- Veri: CSV, JSON, YAML, SQLite
Zamanlanmış Hat — Her gün (19:00 UTC) otomatik güncellemeler için GitHub Actions cron zamanlayıcısı
Çift Dilli Dokümantasyon — Tam İngilizce ve Türkçe dokümantasyon

Hızlı Başlangıç

Ön Gereksinimler

Python 3.11+
pip veya Poetry

Kurulum

git clone https://github.com/bayraktarozcan/TC-SGB-API-to-List.git
cd TC-SGB-API-to-List
pip install -e .

Kullanım

# Tam hattı çalıştır
tc-sgb fetch

# Daha önce kaydedilmiş ham veriden çıktı üret
tc-sgb generate -i Output/raw_records.json

# Sağlık durumunu görüntüle
tc-sgb health

# Üçüncü taraf tehdit akışlarını çek (CERT.PL, CERT.SI, blacklist.gov.az)
tc-sgb fetch-external

# Yayımlanmış harici listeleri güvenlik politikasına göre doğrula (çekme yok)
tc-sgb validate-external

Veri İndirme

En güncel önceden üretilmiş IoC çıktıları (her gün, 19:00 UTC) yuvarlanan GitHub Release'i ioc-data'da otomatik olarak yayınlanır. Beş büyük biçim dosyası kararlı indirme bağlantıları üzerinden dağıtılır (küçük biçimler Output/ dizininde izlenmeye devam eder):

Biçim	Dosya	Yaklaşık Boyut
Ham kayıtlar	raw_records.json	129 MB
Yapılandırılmış JSON	threat_intel_json.json	130 MB
SQLite veritabanı	threat_intel_sqlite.db	96 MB
Suricata JSON	threat_intel_suricata.json	203 MB
Yapılandırılmış YAML	threat_intel_yaml.yaml	97 MB

wget/curl/Invoke-WebRequest ile indirin veya release sayfasını inceleyin. Diğer tüm biçimler hattı yerel olarak çalıştırdığınızda Output/ dizinine üretilir.

Brave / AdGuard kullanıcıları: release bağlantıları dosya indirme olarak sunulur ve Brave bunları özel filtre listesi olarak kabul etmez. Bunun yerine her gün güncellenen düz metin aynayı kullanın (brave://adblock → Add filter list via URL). Aynı dalda, aynı iş akışıyla güncellenen üç seçkin liste daha yayınlanır (Polonya, Azerbaycan, Slovenya); dosyalar numaralıdır, böylece Brave onları ülke sırasıyla gösterir (04 Litvanya için ayrılmıştır):

02-polonya-certpl_adguard.txt

03-azerbaycan-blacklist_adguard.txt

05-slovenya-certsi_adguard.txt

Yayımlama güvenliği

Sözdizimi doğrulaması kural biçimini denetler; Scripts/src/safety.py içindeki güvenlik politikası bir makinenin toptan engellenmesinin yayımlanmasının güvenli olup olmadığına karar verir. Yüksek etkili makineler doğrudan reddedilir, ortak kullanıcı içerik altyapısı incelemeye ayrılır ve tutulan her gösterge gerekçesiyle birlikte akış başına denetim dosyasına (Output/External/) yazılır — asla sessizce düşürülmez. Zamanlanmış iş akışı yalnızca tc-sgb validate-external geçen listeleri yayımlar; koşamayan akış son iyi anlık görüntüyü sunmaya devam eder.

Proje Yapısı

TC-SGB-API-to-List/
├── Scripts/
│   ├── main.py                  # CLI giriş noktası
│   └── src/
│       ├── models.py            # Pydantic veri modelleri
│       ├── client.py             # Asenkron API istemcisi
│       ├── external_feeds.py    # Üçüncü taraf tehdit akışı aynaları
│       ├── safety.py            # Yayımlama güvenlik politikası (ortak)
│       ├── validator.py         # IoC doğrulama
│       ├── normalizer.py        # IoC normalleştirme
│       ├── deduplicator.py      # Tekilleştirme
│       ├── quality.py           # Kalite puanlama
│       ├── outputs.py           # 16 çıktı biçimi üreteçleri
│       └── pipeline.py          # Hat koordinatörü
├── Tests/                       # Test paketi
├── Docs/                        # Dokümantasyon (çift dilli)
├── Schema/                      # JSON Schema ve OpenAPI belirtimi
├── Data/                        # Çalışma zamanı veri önbelleği
├── Output/                      # Üretilen IoC çıktı dosyaları (küçük biçimler izlenir; büyük biçimler `ioc-data` release'i aracılığıyla)
├── Examples/                    # Kullanım örnekleri
├── Benchmark/                   # Performans karşılaştırmaları
└── .github/workflows/           # CI/CD hatları

Dokümantasyon

Belge	Açıklama
Mimari	Sistem tasarımı ve bileşen genel bakışı
Veri Akışı	Hat veri akışı ve dönüşümleri
Modül Mimarisi	Modül sorumlulukları ve arayüzleri
Depo Yapısı	Dizin yerleşimi ve dosya amaçları
API Analizi	TC SGB API uç noktaları ve yetenekleri
Veri Modeli	Pydantic modelleri ve şemaları
Tehdit Modeli	STRIDE tehdit analizi
Güvenlik Analizi	Güvenlik duruşu ve sertleştirme
Lisans Analizi	Hukuki ve lisanslama hususları
Test Stratejisi	Test yaklaşımı ve kapsama
Regresyon Stratejisi	Regresyon test metodolojisi
Performans Stratejisi	Performans karşılaştırmaları ve optimizasyon
Sürüm Stratejisi	Semantik sürümleme yaklaşımı
Yayın Stratejisi	Dağıtım ve yayınlanma
Bakım Planı	Sürekli bakım prosedürleri
Risk Analizi	Risk değerlendirmesi ve azaltma
Yol Haritası	Geliştirme yol haritası
Yasal Bildirimler	Hukuki ve uyum bildirimleri

Proje belgeleri

Belge	Açıklama
Değişiklik Günlüğü	Sürüm geçmişi
Katkıda Bulunma	Katkı yönergeleri
Güvenlik	Güvenlik bildirim süreci
Destek	Soru sorma ve sorun bildirme yeri
Gizlilik	Projenin ne topladığı, sakladığı ve ilettiği
Davranış Kuralları	Davranış kuralları
Sürüm notları	Sürüm notlarının izlediği iskelet
Ajan kılavuzu	İnsanlar ve kodlama ajanları için çalışma kuralları
Lisans	Lisans koşulları
Bildirim	Üçüncü taraf atıfları ve marka bildirimleri
Kod sahipleri	Kod sahiplerini tanımlar

Yapılandırma

.env.example dosyasını .env olarak kopyalayın ve gerektiğince yapılandırın:

cp .env.example .env

Geliştirme

# Geliştirici bağımlılıklarını kur
pip install -e ".[dev]"
pip install -r requirements.txt

# Testleri çalıştır
pytest Tests/ -v

# Linter'ı çalıştır
ruff check Scripts/ Tests/

# Tip kontrolcüyü çalıştır
mypy Scripts/

Yol Haritası

Çekirdek hat (çek → doğrula → normalleştir → puanla → tekilleştir → çıktı)
16 çıktı biçimi
GitHub Actions ile CI/CD
Kapsamlı test paketi
Docker konteynerleştirme
PyPI yayınlama
Ek tehdit istihbaratı kaynakları (CISA KEV, Spamhaus, URLhaus)
Web kontrol paneli

Katkıda Bulunma

Katkılar memnuniyetle karşılanmaktadır! Lütfen pull request göndermeden önce katkı yönergelerimizi okuyun.

Lisans

Bu proje MIT Lisansı altında lisanslanmıştır. Veri yeniden dağıtımı ile ilgili önemli yasal bilgiler için YASAL BİLDİRİMLER dosyasına bakın.

Sorumluluk Reddi

Bu araç, meşru siber güvenlik araştırması ve savunma amaçları için olduğu gibi sağlanmaktadır. Kullanıcılar, geçerli tüm yasa ve düzenlemelere uymaktan sorumludur.

Name		Name	Last commit message	Last commit date
.github		.github
Benchmark		Benchmark
Data		Data
Docs		Docs
Examples		Examples
Output		Output
Schema		Schema
Scripts		Scripts
Site		Site
Tests		Tests
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODEOWNERS		CODEOWNERS
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NOTICE		NOTICE
PRIVACY.md		PRIVACY.md
README.md		README.md
RELEASE-NOTE-TEMPLATE.md		RELEASE-NOTE-TEMPLATE.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

TC-SGB-API-to-List

Overview

Features

Quick Start

Prerequisites

Installation

Usage

Data Download

Publication safety

Project Structure

Documentation

Project documents

Configuration

Development

Roadmap

Contributing

License

Disclaimer

TC-SGB-API-to-List

Genel Bakış

Özellikler

Hızlı Başlangıç

Ön Gereksinimler

Kurulum

Kullanım

Veri İndirme

Yayımlama güvenliği

Proje Yapısı

Dokümantasyon

Proje belgeleri

Yapılandırma

Geliştirme

Yol Haritası

Katkıda Bulunma

Lisans

Sorumluluk Reddi

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages