API.tr.md

English: For the English version of this document, see here.

OSIRIS API Başvurusu

Sürüm: 0.2.0 · İnteraktif doküman: GET /docs (Swagger UI), Nginx arkasında /api/docs Taban URL (üretim): http://<sunucu>/api · Doğrudan (dev): http://localhost:8001

Tüm uçlar JSON döner. Zamanlar ISO-8601 UTC'dir. ID'ler UUID dizgisidir.

İçindekiler

1. Kimlik Doğrulama
2. Roller & Yetki Matrisi
3. Uzlaşımlar
4. Sağlık
5. Auth Uçları
6. Plugin & Toplama
7. Arama
8. Kaynaklar
9. Öğeler & Varlıklar
10. Graf
11. Uyarılar
12. Raporlar
13. İstatistik
14. Hatalar
15. Hız Sınırları
16. Değişiklikler

---

1. Kimlik Doğrulama

İstek başına bir kimlik bilgisi gönderilir:

# Operatör / kullanıcı API anahtarı
curl -H "X-API-Key: <anahtar>" http://<sunucu>/api/plugins

# Kısa ömürlü JWT (1 saat, HS256)
curl -H "Authorization: Bearer <jeton>" http://<sunucu>/api/plugins

Jeton üretimi (operatör anahtarı gerekir):

curl -X POST http://<sunucu>/api/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"<OSIRIS_API_KEY>","role":"analyst"}'
# → {"access_token":"...","token_type":"bearer","expires_in":3600}

Kullanıcı anahtarları (yalnızca admin) — ham değer bir kez döner, saklanmaz:

curl -X POST http://<sunucu>/api/auth/keys \
  -H "X-API-Key: <OSIRIS_API_KEY>" -H 'Content-Type: application/json' \
  -d '{"username":"ali","role":"analyst","name":"laptop"}'
# → {"id":"...","api_key":"osiris_...","role":"analyst"}

OSIRIS_API_KEY tanımsızsa API açık çalışır (güvenilir-ağ modu, uyarı loglanır).

2. Roller & Yetki Matrisi

Roller yükselir: viewer → analyst → admin. Bilinmeyen rol reddedilir.

Uç	viewer	analyst	admin
GET /health	açık	açık	açık
POST /auth/token	gövdede operatör anahtarı	—	—
GET/POST /auth/keys, DELETE /auth/keys/{id}	✗	✗	✓
GET /plugins, GET /stats	✓	✓	✓
POST /search, /search/entity, GET /items/*, /entities/top	✓	✓	✓
GET /sources, /saved-queries, /graph	✓	✓	✓
POST /collect, /collect/batch	✗ (403)	✓	✓
POST /sources, DELETE /sources/*, /sources/*/collect	✗	✓	✓
POST /saved-queries, DELETE, /alerts/test	✗	✓	✓
POST /graph/relation, /reports/markdown	✗	✓	✓

3. Uzlaşımlar

• Sayfalama (liste uçları): ?limit= (varsayılan 100, en fazla 200) + ?offset= (≥0). /items/recent en fazla 50.
• Filtreler: GET /sources?enabled=true&plugin_id=rss&q=ad; GET /saved-queries?alert_enabled=true; GET /entities/top?entity_type=email&limit=20.
• Yoldaki ID'ler UUID olmalı — değilse 404 döner (500 asla).
• İstek sınırları: config nesneleri ≤ 50 anahtar ve serileşmiş ≤ 20 KB; sorgular ≤ 500 karakter; gövdelerde alan max_length sınırları.
• Kısmi başarı: /collect/batch her zaman 200 + iş başına {ok, items, error} ve {ok, total} özeti döner.

4. Sağlık

curl http://<sunucu>/api/health
# {"status":"ok","service":"osiris-api"}

5. Auth Uçları

Yöntem & Yol	Rol	Açıklama
POST /auth/token	gövdede operatör anahtarı	JWT üret (role: viewer/analyst/admin)
POST /auth/keys	admin	Kullanıcı anahtarı üret ({username, role, name?})
GET /auth/keys	admin	Anahtarları listele (yalnızca özet/önek, ham değer asla)
DELETE /auth/keys/{id}	admin	İptal et (satır kalır — denetim izi)

6. Plugin & Toplama

# Envanter + dinamik config şemaları (kaynak formlarını buradan besleyin)
curl -H "X-API-Key: <a>" http://<sunucu>/api/plugins
# [{"id":"rss","name":"RSS/Atom Feed","network_type":"rss",
#   "description":"...","config_schema":{"feed_url":{...}},"schedule_default":"*/15 * * * *"}]

# Tek iş
curl -X POST http://<sunucu>/api/collect -H "X-API-Key: <a>" \
  -H 'Content-Type: application/json' \
  -d '{"plugin_id":"rss","config":{"feed_url":"https://example.com/rss"}}'
# → {"items":3,"metadata":{...}}  (başarısızlıkta plugin mesajıyla 502)

# Toplu (≤10 iş, sıralı, iş başına sonuç)
curl -X POST http://<sunucu>/api/collect/batch -H "X-API-Key: <a>" \
  -H 'Content-Type: application/json' \
  -d '{"jobs":[{"plugin_id":"rss","config":{...}},{"plugin_id":"dns-whois","config":{"domain":"example.com"}}]}'
# → {"jobs":[{"plugin_id":"rss","ok":true,"items":3,"error":null},...],"ok":1,"total":2}

7. Arama

curl -X POST http://<sunucu>/api/search -H "X-API-Key: <a>" \
  -H 'Content-Type: application/json' -d '{"query":"saldırı","limit":20}'
# → [{"id":"...","title":"...","url":"...","cleaned_content":"...","collected_at":"..."}]

curl -X POST http://<sunucu>/api/search/entity -H "X-API-Key: <a>" \
  -H 'Content-Type: application/json' -d '{"entity_type":"email","value":"a@b.co","limit":20}'

Varlık türleri: person, org, location, ip, domain, email, phone, crypto_address, hash, username, cve, custom.

8. Kaynaklar

# Liste (filtre + sayfalama)
curl -H "X-API-Key: <a>" "http://<sunucu>/api/sources?enabled=true&limit=50"

# Oluştur — plugin'e özel ayarlar config'e (/plugins şemalarına bakın)
curl -X POST http://<sunucu>/api/sources -H "X-API-Key: <a>" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Örnek RSS","plugin_id":"rss","network_type":"rss",
       "url":"https://example.com/rss","schedule":"*/15 * * * *",
       "config":{"feed_url":"https://example.com/rss","max_items":50}}'
# → {"id":"..."}

# Tek seferlik çalıştır (source_id işlenir → sources/source_metrics'e sağlık düşer)
curl -X POST http://<sunucu>/api/sources/<id>/collect -H "X-API-Key: <a>"

# Sil
curl -X DELETE http://<sunucu>/api/sources/<id> -H "X-API-Key: <a>"

Kaynak satırları sağlık taşır: last_crawled_at, last_success_at, failure_count, avg_response_ms.

9. Öğeler & Varlıklar

curl -H "X-API-Key: <a>" "http://<sunucu>/api/items/recent?limit=20&offset=0"
curl -H "X-API-Key: <a>" http://<sunucu>/api/items/<id>        # + gömülü entities[]
curl -H "X-API-Key: <a>" "http://<sunucu>/api/entities/top?entity_type=domain&limit=20"
# → [{"type":"domain","value":"example.com","mentions":12,"last_seen":"..."}]

10. Graf

curl -H "X-API-Key: <a>" http://<sunucu>/api/graph
# {"nodes":[{"id":"..."}],"edges":[{"source":"...","target":"...","relation_type":"..."}]}

curl -X POST http://<sunucu>/api/graph/relation -H "X-API-Key: <a>" \
  -H 'Content-Type: application/json' \
  -d '{"source":"example.com","target":"1.2.3.4","relation_type":"resolves"}'
# graph_edges'e yazılır (yeniden başlatmada korunur)

11. Uyarılar

curl -X POST http://<sunucu>/api/saved-queries -H "X-API-Key: <a>" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Kritik","query_text":"saldırı","query_type":"fts","alert_enabled":true}'
# query_type ∈ fts|semantic|regex|entity|graph

# Metni kurallara karşı kuru-sıkı dene (kayıt oluşmaz)
curl -X POST http://<sunucu>/api/alerts/test -H "X-API-Key: <a>" \
  -H 'Content-Type: application/json' -d '{"text":"büyük saldırı oldu"}'
# → [{"query_id":"...","query_name":"Kritik","item_id":null,"matched":"saldırı"}]

12. Raporlar

curl -X POST http://<sunucu>/api/reports/markdown -H "X-API-Key: <a>" \
  -H 'Content-Type: application/json' \
  -d '{"title":"R","scope":"S","summary":"O",
       "findings":[{"title":"B","description":"D"}],"sources":["k"]}'
# → {"markdown":"# R\n..."}

13. İstatistik

curl -H "X-API-Key: <a>" http://<sunucu>/api/stats
# {"sources":4,"sources_enabled":4,"items":128,"entities":342,"edges":57,
#  "saved_queries":3,"alerts":2,"latest_item_at":"..."}

14. Hatalar

Kod	Anlam
400	Hatalı değer (query_type, entity_type, rol, ağ)
401	Eksik/geçersiz kimlik
403	Kimlik geçerli, rol yetersiz
404	Bilinmeyen plugin/kaynak/öğe/anahtar veya bozuk UUID
413	Config nesnesi çok büyük
422	Şema ihlali (ayrıntı detail dizisinde)
500	Sunucu/DB hatası (iç detay sızmaz)
502	Plugin çalıştı ama başarısız oldu (detail plugin mesajını taşır)

15. Hız Sınırları

Nginx'te zorunlu: /api/* üzerinde 10 istek/sn (taşma 20). Anahtar başına kota henüz yok — büyük toplu işlerde /collect/batch (≤10) kullanın ve istemcide tempo koyun.

16. Değişiklikler

• 0.2.0 — listelerde sayfalama + filtreler; GET /items/{id} (+varlıklar), GET /entities/top, POST /collect/batch; UUID-güvenli id yolları; OpenAPI etiket/özetleri; q filtresinde LIKE-joker kaçışı.
• 0.1.x — sources CRUD + çalıştırma tetikleme, saved-queries CRUD, /alerts/test, /reports/markdown, /stats, /items/recent, JWT + RBAC, /auth/keys.