Censys Platform API ile Arama, Sayfalama ve Veri İndirme – Ahmet Tabanlıoğlu

Seride şimdiye kadar sorgu düşüncesi, sınır çizimi ve zaman boyutunu konuştuk. Bu yazıda aynı disiplini programatik hale getiriyorum: Censys Platform API ile nasıl arama yapılır, sonuçlar nasıl sayfalanır ve çıktıyı nasıl güvenli biçimde yerel dosyaya dökersiniz?

Önemli çerçeve: API, tarayıcıdaki “gezinme”nin yerine geçen resmi yoldur; kullanım Censys kullanım şartlarına tabidir ve kota / eşzamanlılık sınırları vardır.

1. Legacy mi, Platform mu?

Eski “Search API v2” dünyası ile Censys Platform API (v3) farklı taban URL’leri ve farklı kimlik doğrulama modeli kullanır. Platform tarafında birleşik arama uç noktası POST /v3/global/search/query eşleniğindedir; tek tek host çekmek için GET /v3/global/asset/host/{ip} gibi varlık uçları vardır. Eşleme tablosu için geçiş rehberine bakmak iyi fikir: Platform API Transition Guide.

2. Kimlik doğrulama ve organizasyon

Platform API, Personal Access Token (PAT) ile çalışır. Özet akış konsolda: kullanıcı menüsü → API Access → token üret → token’ı kopyala ve asla repoya koyma. İsteklerde tipik olarak Authorization: Bearer <token> kullanılır.

Çoğu kurumsal senaryoda ayrıca organization ID gerekir; Python SDK örnekleri de organization_id ile başlar. Organizasyon içinde API’yi kimlerin kullanabileceği rol ile sınırlanabilir (dokümantasyonda “API Access role” vurgusu var).

Güvenlik notu: Token’ı ortam değişkeninde tutun (CENSYS_PAT), CI’da secret store kullanın, loglara ham yanıt basmayın.

3. En kritik uyarı: hesap seviyesi ve “search” erişimi

Bunu yazının ortasında değil başta söylemek isterim: Platform API’ye erişim, üyelik seviyesine göre kısıtlanır. Resmi özet metinde, ücretsiz katman için çoğunlukla arama (search) yerine varlık okuma / lookup uçları anılır; tam Global Data araması üst seviyelerle ilişkilidir. Yani yazdığınız script’i bir ortamda çalıştırıp diğerinde “403/ yetkisiz” görmek, çoğu zaman “kod bozuk” değil “plan kapsamı” meselesidir. Yayından önce kendi hesabınızda hangi uçlara izin var diye kontrol edin: Get Started with Censys APIs.

4. Arama: sorgu + alan projeksiyonu

Aramanın amacı genelde iki şeydir:

Filtre: CenQL ile dar bir kümeyi üretmek (serinin önceki yazılarında kurduğumuz mantık burada kodlanır).
Projeksiyon: fields ile yalnızca ihtiyaç duyulan alanları istemek.

Neden projeksiyon? Çünkü host kaydı “her şeyiyle” geldiğinde hem ağır hem gereksiz veri biriktirir. Savunma otomasyonunda tipik minimum set: IP / host tanımlayıcı, port, servis kimliği, tarama zamanı, sertifika veya hostname ile ilgili birkaç stabil alan.

Tam alan sözlüğü sürüme göre değişebildiği için pratikte Platform’daki data definitions ekranını/tanımlarını referans alırsınız; blog yazısında tek tek alan avcılığı yapmak yerine okuyucuya “sözlüğe bağlan” demek daha doğru.

5. Sayfalama: `page_token` ve `next_page_token`

“Tüm eşleşmeleri indir” dendiğinde mesele sayfalamaya indirgenir. Platform tarafında sayfalar arasında next_page_token ile ilerlenir; boş / yok ise son sayfadasınızdır. Topluluk yanıtında Censys ekibi şunu özellikle vurguluyor: token’lar uzun süre bekletilerek kullanılmaya uygun değildir; mümkünse ardışık ve kısa sürede tüketilmelidir — aksi halde tutarsızlık veya hata riski artar (özet tartışma).

Bu, operasyonel tasarlıkta şunu gerektirir:

İndirme işini batch düşünün (ör. her gece bir job).
Ortada saatlerce durdurup aynı token ile devam etmeyin.

6. Python SDK ile minimal örnek (anlatım amaçlı)

Aşağıdaki örnek, Platform Python SDK üzerinden arama + sayfalama fikrini gösterir; sorgu ve alan listesini kendi CenQL’inize göre değiştirmeniz gerekir. Paket adı/sürüm için resmi PyPI/SDK sayfasını baz alın (censys_platform / güncel dokümantasyon).

import os
from censys_platform import SDK
from censys_platform import models


ORG = os.environ["CENSYS_ORG_ID"]
PAT = os.environ["CENSYS_PAT"]


QUERY = 'host.services: (protocol = "SSH")' # örnek — kendi dar sorgunuzu koyun
FIELDS = ["host.ip", "host.services.port", "host.services.scan_time"]
PAGE_SIZE = 100
OUT_PATH = "censys_page_dump.jsonl"


# Uyarı: çok geniş sorgular çok sayfa üretir; kota ve kurallara dikkat.


def main():
page_token = ""
with SDK(organization_id=ORG,personal_access_token=PAT)as sdk,open(OUT_PATH,"a",encoding="utf-8")as fh:
whileTrue:
res = sdk.global_data.search(
search_query_input_body=models.SearchQueryInputBody(
query=QUERY,
page_size=PAGE_SIZE,
fields=FIELDS,
page_token=page_token,
)
)
r = res.result.result
for hit in r.hits:
fh.write(hit.model_dump_json() + "\n")


page_token = r.next_page_token or ""
ifnot page_token:
break


if __name__ == "__main__":
main()

Bu kod “veri indirme”nin ham halidir: gerçek üretimde yeniden deneme, 429/backoff, hata ayıklama logları ve dosya rotasyonu eklenir.

7. REST (curl) düşüncesi

SDK istemiyorsanız aynı fikir POST https://api.platform.censys.io/v3/global/search/query ile yürür; gövdede query, page_size, fields, page_token benzeri alanlar taşınır. Base URL ve sürüm için: Get Started ve arama referansı: v3 global search query.

8. İndirilen veriyi disipline etmek

JSON Lines (JSONL): sayfa sayfa eklemek kolay; satır başına bir kayıt.
Parquet: analitik için iyi; ek bağımlılık.
CSV: düz alanlar için cazip ama iç içe yapılarda hata edersiniz.

Sonra bir önceki yazıdaki gibi diff için anahtar seçin (ör. ip + port + protocol).

9. Etik, hukuk ve veri minimizasyonu

Yalnızca yetkili envanter ve sözleşme kapsamı içinde çalışın.
Dış paylaşımlı çıktılarda gereksiz kişisel / iç meta veri taşımayın.
Token ve ham bulgu arşivlerini erişimle sınırlayın.

Özet: Censys Platform API, aramayı search/query üzerinden, detayı ise asset/host gibi uçlardan tüketir. Veri indirmenin kalbi dar sorgu + alan projeksiyonu + doğru sayfalamadır; hesap planınız search iznini belirler. Token güvenliği ve sayfa token’larının “hemen tüketilmesi” gerekliliği ise üretimde en çok unutulan iki detaydır.

NOT: Bana bu postları hazırlarken kullandığın veriler ve kullanım hesabı için Censys’e teşekkür ederim.