Skip to content

README.md

Latest commit

 

History

History
447 lines (350 loc) · 23 KB

README.md

File metadata and controls

447 lines (350 loc) · 23 KB
Raw

English | Türkçe

TC-SGB-API-to-List

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

CI Scheduled Pipeline CodeQL Pages Hygiene Link Check GitLab Pipeline GitLab Coverage Python 3.11+ License: MIT Ruff

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):

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ı

CI Scheduled Pipeline CodeQL Pages Hygiene Link Check GitLab Pipeline GitLab Coverage Python 3.11+ License: MIT Ruff

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):

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.