API SwarmHawk

API SwarmHawk zapewnia programowy dostęp do 27 zautomatyzowanych kontroli bezpieczeństwa oraz 3000+ aktywnych szablonów nuclei CVE — SSL, DNS, CVE z potwierdzeniem aktywnego exploita, ekspozycja naruszeń danych, typosquatting, analiza zagrożeń AI i więcej — dla dowolnej domeny. Użyj go do budowania workflow'ów bezpieczeństwa, automatyzacji due diligence lub integracji SwarmHawk z własną platformą.

Istnieją dwie powierzchnie API:

• /api/v2 — starsze powierzchnia uwierzytelniana sesją/JWT używana przez dashboard. Większość operacji odczytu i zapisu jest również dostępna tutaj dla kompatybilności.
• /api/v1 — nowoczesny publiczny interfejs API Business / Enterprise, zabezpieczony kluczami API nośnika (swh_…). To jest cel, na który powinny być skierowane nowe integracje.

Szybki start — skanuj domenę w 30 sekund

# 1. Create an API key at www.swarmhawk.com → Account → API Keys (Business or Enterprise)
# 2. Add and start scanning a domain:

curl -X POST https://api.swarmhawk.com/api/v1/domains \
  -H "Authorization: Bearer swh_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

# Poll the latest report:
curl https://api.swarmhawk.com/api/v1/jobs/<job_id> \
  -H "Authorization: Bearer swh_your_key_here"

import requests

API_KEY = "swh_your_key_here"
BASE = "https://api.swarmhawk.com/api/v1"
H = {"Authorization": f"Bearer {API_KEY}"}

resp = requests.post(f"{BASE}/domains", headers=H, json={"domain": "example.com"})
job_id = resp.json()["job_id"]

job = requests.get(f"{BASE}/jobs/{job_id}", headers=H).json()
print(f"State: {job['state']}")

const BASE = "https://api.swarmhawk.com/api/v1";
const H = { "Authorization": "Bearer swh_your_key_here", "Content-Type": "application/json" };

const add = await fetch(`${BASE}/domains`, {
  method: "POST",
  headers: H,
  body: JSON.stringify({ domain: "example.com" })
}).then(r => r.json());

const job = await fetch(`${BASE}/jobs/${add.job_id}`, { headers: H }).then(r => r.json());
console.log(`State: ${job.state}`);

Uwierzytelnianie

SwarmHawk wykorzystuje dwie metody uwierzytelniania w zależności od punktu końcowego:

Format klucza API

swh_3f8a2b1c4d5e6f7a8b9c0d1e2f3a4b5c

Błędy i limity szybkości

Kody stanu HTTP

Struktura odpowiedzi błędu

{
  "detail": "Invalid API key"
}

Limity szybkości

Skanuj domenę

Nie istnieje jeden "skanowanie jednorazowe" endpoint. Aby skanować domenę za pośrednictwem API:

1. Dodaj (i zweryfikuj) domenę za pomocą POST /api/v1/domains — pierwsza skanowanie jest automatycznie kolejkowane.
2. Aby ponownie przeskanować już dodaną domenę, wywołaj POST /api/v1/domains/{domain_id}/scan.
3. Odpytuj GET /api/v1/jobs/{job_id} w celu sprawdzenia statusu oraz GET /api/v2/domains/{domain_id}/report aby uzyskać najnowsze wyniki.
4. W przypadku jednorazowych anonimowych skanów bez konta użyj POST /public-scan (ograniczone szybkością, wyniki nie są przechowywane).

POST /public-scan

Anonimowe skanowanie — nie jest wymagany klucz API. Zwraca podzbiór kontroli z niektórymi wynikami zablokowanymi. Użyj tego do demonstracji lub osadzania. Wyniki nie są zapisywane.

{
  "domain": "example.com",
  "risk_score": 42,
  "critical": 1,
  "warnings": 3,
  "locked_count": 8,
  "checks": [/* 7 free checks visible, 8 locked */],
  "scanned_at": "2025-03-10T09:15:00Z"
}

GET /scan/passive

Szybkie skanowanie pasywne — wykrywa stos oprogramowania i sprawdza znane CVE bez pełnego skanowania. Odpowiedź w ~3 sekundy. Wynik nie jest zapisywany.

{
  "domain": "example.com",
  "software": [
    {"product": "nginx", "version": "1.18.0"},
    {"product": "WordPress", "version": "6.3.1"}
  ],
  "cve_hits": [
    {
      "product": "WordPress 6.3.1",
      "top_cve": "CVE-2023-39320",
      "top_cvss": 9.8,
      "cve_count": 3
    }
  ],
  "max_cvss": 9.8,
  "priority": "CRITICAL"
}

GET /api/v2/domains

Wyświetl listę wszystkich domen na Twoim koncie wraz z najnowszymi wynikami ryzyka i kontrolami.

{
  "domains": [
    {
      "id": "uuid",
      "domain": "example.com",
      "country": "DE",
      "status": "active",
      "paid": true,
      "risk_score": 42,
      "scanned_at": "2025-03-10T09:15:00Z",
      "checks": [/* latest check array */],
      "scan_history": [{"date":"…","risk":42}]
    }
  ]
}

POST /api/v2/domains

Dodaj domenę do swojego konta i umieść skan w kolejce.

{
  "id": "uuid",
  "domain": "mycompany.cz",
  "status": "scanning",
  "message": "Domain added — scan starting now"
}

GET /api/v2/domains/{domain_id}/report

Pobierz najnowszy pełny raport skanowania dla domeny. Użytkownicy darmowi widzą podzbiór; użytkownicy premium widzą wszystkie 27 kontroli, w tym walidację aktywnych CVE nuclei i podsumowanie AI.

{
  "domain": "example.com",
  "risk_score": 42,
  "scanned_at": "2025-03-10T09:15:00Z",
  "paid": true,
  "critical": 1,
  "warnings": 3,
  "informational": 2,
  "locked_count": 0,
  "verified_at": "2026-04-08T10:00:00Z",
  "checks": [
    {
      "check": "ssrf",
      "status": "info",
      "confidence": "informational",
      "title": "A10: 3 SSRF surface indicator(s)",
      "detail": "Surface area detected (not confirmed vulnerabilities)…",
      "score_impact": 0
    }
  ]
}

GET /domains/{domain_id}/verify-token

Zwróć aktywne wyzwanie weryfikacji wydane przez koordynatora weryfikacji. SwarmHawk obsługuje dwie metody weryfikacji — rekord DNS TXT lub przesyłanie pliku HTTP. Wywołaj POST /domains/{domain_id}/verify z method: "dns" lub "http" po opublikowaniu rekordu/pliku.

{
  "domain": "example.com",
  "verified_at": null,
  "orchestrator_state": "pending",
  "method": {
    "name": "DNS TXT record",
    "record_name": "_swarmhawk-verify.example.com",
    "record_value": "swarmhawk-verify=a3f7b2c1…",
    "hint": "Add a TXT record named _swarmhawk-verify.example.com with the value above. Click 'Check DNS' once propagated."
  },
  "methods": [
    {
      "type": "dns",
      "name": "DNS TXT record",
      "record_name": "_swarmhawk-verify.example.com",
      "record_value": "swarmhawk-verify=a3f7b2c1…",
      "hint": "Add a TXT record …"
    },
    {
      "type": "http",
      "name": "File upload",
      "path": "/.well-known/swarmhawk-verify.txt",
      "url": "https://example.com/.well-known/swarmhawk-verify.txt",
      "body": "swarmhawk-verify=a3f7b2c1…",
      "hint": "Upload a file at the URL containing the body above. Click 'Check File' once it returns 200."
    }
  ]
}

POST /domains/{domain_id}/verify

Poproś orkiestrator o potwierdzenie własności przy użyciu wybranej metody. W przypadku powodzenia wartość domains.verified_at zostaje zapisana i zwrócona w kolejnych odpowiedziach raportu. Orkiestrator buforuje pozytywne weryfikacje przez 7 dni.

{ "method": "dns" }   // or "http"

{ "verified": true, "method": "dns" }

{ "verified": false, "state": "pending", "method": "dns", "detail": "DNS-TXT record not found yet" }

GET /api/v2/domains/{domain_id}/history

Trend wyniku ryzyka w czasie — przydatny do budowania dashboardów lub alertowania o wzroście wyniku.

{
  "domain": "example.com",
  "scans": [
    {"risk_score":42,"critical":1,"warnings":3,"scanned_at":"2025-03-10T09:15:00Z"},
    {"risk_score":38,"critical":0,"warnings":4,"scanned_at":"2025-02-10T08:00:00Z"}
  ]
}

GET /api/v2/domains/{domain_id}/nis2

Mapuj wyniki skanowania na artykuły Dyrektywy NIS2. Zwraca wynik zgodności i status dla każdego artykułu — odpowiedni jako dowód audytu dla organów regulacyjnych.

{
  "domain": "example.com",
  "risk_score": 42,
  "nis2_score": 71,
  "articles": [
    {
      "article": "Art.21(2)(i)",
      "requirement": "Secure communications",
      "status": "met"
    },
    {
      "article": "Art.21(2)(h)",
      "requirement": "Supply chain security",
      "status": "warning"
    }
  ]
}

POST /intel

Generuj zasilany sztuczną inteligencją raport zagrożeń dla swojego portfela domen za pomocą Claude. Zwraca ustrukturyzowany raport zawierający streszczenie dla kierownictwa, krytyczne ustalenia i priorytety remediacji.

{
  "text": "## Executive Summary\n\nYour domain portfolio shows...",
  "briefing": "…"
}

POST /api/v2/keys

Utwórz nowy klucz API dla swojego konta. Zwraca wszystkie klucze, włączając nowo utworzony.

{
  "keys": [
    {
      "key": "swh_3f8a2b1c4d5e6f7a8b9c0d1e2f3a4b5c",
      "calls_this_month": 0,
      "limit_per_month": 10,
      "active": true,
      "created_at": "2025-03-10T09:00:00Z"
    }
  ]
}

GET /api/v2/keys

Wyświetl listę wszystkich kluczy API i ich użycie w bieżącym miesiącu.

curl https://api.swarmhawk.com/api/v2/keys \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

DELETE /api/v2/keys/{key}

Natychmiast odwołaj klucz API. Wszystkie przyszłe żądania z tym kluczem zostaną odrzucone.

{ "revoked": "swh_3f8a2b1c…" }

Business / Enterprise API — /api/v1

Powierzchnia /api/v1/* to produkcyjny interfejs API zapisu używany przez klientów Business i Enterprise. Każdy endpoint poniżej akceptuje X-API-Key: swh_… (rekomendowane dla komunikacji serwer-do-serwera) lub Authorization: Bearer <jwt> (dla narzędzi first-party).

Ograniczenia wersji

• Bezpłatny — dostęp do API niedozwolony (403 API_ACCESS_REQUIRED).
• Pro — 10-wywołań bezpłatny okres próbny tylko do odczytu. Endpoints zapisu zwracają 403 business_required.
• Business — 500 wywołań/miesiąc, obciążenie portfela/uprawnień na skan/test penetracyjny/naruszenie.
• Enterprise — nieograniczone zapytania; rejestracja przez administratora z limitem max_domains na klienta i pomiarem na zapytanie (szczegóły).

Typowy przepływ dla sprzedawcy

# 1. Add a domain (returns the DNS challenge inline)
curl -X POST https://api.swarmhawk.com/api/v1/domains \
  -H "X-API-Key: swh_…" -H "Content-Type: application/json" \
  -d '{"domain":"acme.com"}'
# {"id":"…","domain":"acme.com","verification":{"state":"pending","dns_record_name":"_swarmhawk.acme.com","dns_record_value":"swh-verify=…"}}

# 2. Tenant adds the DNS TXT record, then verify
curl -X POST https://api.swarmhawk.com/api/v1/domains/{id}/verify \
  -H "X-API-Key: swh_…"
# {"verified":true,"state":"verified","method":"dns"}

# 3. Kick off a scan / pentest / breach lookup (returns job_id)
curl -X POST https://api.swarmhawk.com/api/v1/domains/{id}/scan -H "X-API-Key: swh_…"
# {"job_id":"…","status":"queued","domain":"acme.com","swarmhawk_job_id":"…"}

# 4. Poll the orchestrator-side job and pull results when status=done
curl https://api.swarmhawk.com/api/v1/jobs/{job_id} -H "X-API-Key: swh_…"
curl https://api.swarmhawk.com/api/v1/jobs/{job_id}/findings -H "X-API-Key: swh_…"
curl https://api.swarmhawk.com/api/v1/jobs/{job_id}/report -H "X-API-Key: swh_…"

POST /api/v1/keys

Wydaj klucz API dla bieżącego użytkownika. Business: jeden klucz, 500 wywołań/miesiąc. Enterprise: jeden klucz, nieograniczony (zarządzany przez administratora poprzez /admin/api/v1/enterprise/*). Tylko Bearer JWT — nie możesz bootstrapować swojego pierwszego klucza samym sobą; logowanie do panelu (lub rejestracja admin dla Enterprise) to punkt wejścia.

curl -X POST https://api.swarmhawk.com/api/v1/keys -H "Authorization: Bearer …"
# { "keys": [{ "id":"…", "key_prefix":"swh_…", "calls_this_month":0, "limit_per_month":500 }],
#   "created": true, "is_trial": false, "full_key": "swh_…" }  ← plaintext shown ONCE

GET /api/v1/keys

Wyświetl aktywne klucze + użycie w bieżącym miesiącu. Tekst jawny nigdy nie jest ponownie wyświetlany. Tylko Bearer JWT — punkty końcowe zarządzania kluczami nie są osiągalne za pomocą klucza API.

{ "keys": [{ "id":"…", "key_prefix":"swh_3f8a2b1c",
            "calls_this_month":142, "limit_per_month":500,
            "cost_this_month_usd":"23.50", "last_used_at":"2026-05-12T19:01:00Z" }] }

POST /api/v1/keys/{key_id}/regenerate

Odwołaj istniejący klucz i wydaj nowy. Nowy tekst jawny jest wyświetlany jednokrotnie w odpowiedzi — poprzedni klucz przestaje działać natychmiast. Tylko Bearer JWT.

DELETE /api/v1/keys/{key_id}

Odwołaj klucz. Idempotentne. Tylko Bearer JWT.

GET /api/v1/domains

Wyświetl domeny rozmówcy. Paginacja; obsługuje ?limit i ?offset.

POST /api/v1/domains

Dodaj domenę i atomowo uruchom weryfikację orkiestratora. Zwraca wyzwanie DNS-TXT w treści odpowiedzi, dzięki czemu możesz dostarczyć je swojemu klientowi bez konieczności dodatkowego kontaktu. Bezpłatnie dla klienta — dodanie domeny nie obciąża portfela.

{
  "id": "d1-uuid",
  "domain": "acme.example.com",
  "country": "US",
  "verification": {
    "state": "pending",
    "dns_record_name": "_swarmhawk.acme.example.com",
    "dns_record_value": "swh-verify=Xk2…",
    "http_path": "/.well-known/swarmhawk-verify.txt",
    "http_body": "swh-verify=Xk2…",
    "expires_at": "2026-05-19T20:00:00Z"
  }
}

GET /api/v1/domains/{domain_id}

Szczegóły pojedynczej domeny: risk_score, last_scanned_at, verified_at, country, itd. 404 przy niezgodności.

PATCH /api/v1/domains/{domain_id}

Przełącz auto_rescan_enabled dla domeny (jedyne pole modyfikowalne na tym endpoincie). Włączenie wymaga warstwy Pro lub wyższej (bramka funkcji daily_rescan); wyłączenie jest zawsze dozwolone. Aby zmienić industry, primary_contact lub country, usuń i ponownie dodaj domenę.

curl -X PATCH https://api.swarmhawk.com/api/v1/domains/{id} \
  -H "Authorization: Bearer …" -H "Content-Type: application/json" \
  -d '{"auto_rescan_enabled": true}'
# { "ok": true }

DELETE /api/v1/domains/{domain_id}

Trwałe usunięcie domeny. Wiersz, jego stan weryfikacji i wszystkie powiązane rekordy zadań są usuwane. Zwalnia slot w limicie poziomu. Przywrócenie limitu przydziału +1.

POST /api/v1/domains/bulk-import

Wieloczęściowe przesłanie pliku CSV — każdy wiersz to domena,kraj (kraj jest obowiązkowy, kod ISO dwuliterowy). Pierwszy wiersz może być nagłówkiem domena,kraj — zostanie pominięty. Respektuje limit dla danego klienta; wiersze przekraczające limit trafiają na listę rejected z powodem quota exceeded. Limit +1 per call (nie per wiersz).

GET /api/v1/domains/{domain_id}/history

Uporządkowana chronologicznie lista poprzednich skanów i zmian checksum dla domeny.

GET /api/v1/domains/{domain_id}/verification

Pobieranie tylko do odczytu bieżącego stanu wyzwania authz z orkiestratora (DNS + ścieżka HTTP + wartości rekordów + czas wygaśnięcia). Użyj tego, jeśli potrzebujesz ponownie wyświetlić wyzwanie po utracie początkowej odpowiedzi POST /api/v1/domains.

{
  "domain": "acme.example.com",
  "state": "pending",            // pending | verified | failed | expired
  "verified_at": null,
  "dns_record_name": "_swarmhawk.acme.example.com",
  "dns_record_value": "swh-verify=Xk2…",
  "http_path": "/.well-known/swarmhawk-verify.txt",
  "http_body": "swh-verify=Xk2…",
  "expires_at": "2026-05-19T20:00:00Z"
}

POST /api/v1/domains/{domain_id}/verify

Poproś orkiestrator o rzeczywiste uruchomienie sprawdzenia. method=dns (domyślnie) wykonuje wyszukiwanie TXT; method=http pobiera https://<domena><http_path> i porównuje do http_body.

curl -X POST https://api.swarmhawk.com/api/v1/domains/{id}/verify \
  -H "X-API-Key: swh_…" -H "Content-Type: application/json" \
  -d '{"method":"dns"}'
# {"verified":true,"state":"verified","method":"dns"}
# {"verified":false,"state":"pending","method":"dns","detail":"TXT record not found"}

POST /api/v1/domains/{domain_id}/scan

Prześlij skan powierzchni ataku do orkiestratora. Bez weryfikacji domeny — każda dodana domena jest uprawniona. Business: debetuje portfel/uprawnienia na podstawie service_prices.attack_surface. Enterprise: rejestruje wiersz usage_events z efektywną ceną na klienta, bez dotknięcia portfela. Przydział +1 na 201.

{
  "job_id": "orch-uuid",        // poll at GET /api/v1/jobs/{job_id}
  "status": "queued",
  "domain": "acme.example.com",
  "swarmhawk_job_id": "sw-uuid"     // internal id, kept for audit
}

POST /api/v1/domains/{domain_id}/pentest

Prześlij test penetracyjny AI. Opcjonalny parametr rate_profile kontroluje agresywność skanowania: stealth (3 rps) · regular (10 rps, domyślnie) · aggressive (25 rps). Wszystkie pozostałe parametry pozostają zgodne z ustawieniami domyślnymi orkiestratora. Ta sama logika podziału portfela/mierzenia, co w przypadku /scan.

curl -X POST https://api.swarmhawk.com/api/v1/domains/{id}/pentest \
  -H "X-API-Key: swh_…" -H "Content-Type: application/json" \
  -d '{"rate_profile":"regular"}'
# {"job_id":"…","status":"queued","domain":"…","swarmhawk_job_id":"…"}

POST /api/v1/domains/{domain_id}/breach-intel

Umieść w kolejce zadanie darknet-research, które przeprowadza weryfikację źródeł darknet pod kątem poświadczeń, haszy i danych osobowych powiązanych z tą domeną. Asynchroniczne — zwraca job_id natychmiast; odpytuj GET /api/v1/breach-intel/{job_id} w celu sprawdzenia statusu i wyników. Typowy czas realizacji end-to-end wynosi 30–90 s. Domena musi być zweryfikowana. Business: obciąża portfel/uprawnienia zgodnie z service_prices.breach_intel. Enterprise: rejestruje wiersz usage_events z efektywną ceną na klienta, bez dostępu do portfela. Limit +1 przy zaakceptowanym zgłoszeniu. Czas oczekiwania dla domeny: 7 dni (okno darknet orkiestratora).

{
  "job_id": "sw-uuid",               // poll GET /api/v1/breach-intel/{job_id}
  "orchestrator_job_id": "orch-uuid",  // upstream id, kept for audit
  "status": "running",
  "domain": "acme.example.com",
  "billing_source": "wallet"           // or "entitlement" | "admin_override" | "enterprise_metered"
}

GET /api/v1/breach-intel/{job_id}

Odpytuj zadanie darknet-research. Weryfikacja własności; brak limitu. Backend leniwie odpytuje orkiestrator (przepustnica 5 s), dopóki wiersz lokalny jest w stanie running, dlatego ten endpoint można wywoływać często bez przeciążania systemu upstream. Gdy zadanie osiągnie stan terminalny (completed | failed | cancelled), kolejne wywołania zwracają buforowany wiersz bez żadnej komunikacji z orkiestratorem.

{
  "job_id": "sw-uuid",
  "orchestrator_job_id": "orch-uuid",
  "domain": "acme.example.com",
  "status": "running",
  "leak_count": null,
  "findings": [],
  "pagination": { "page":1, "page_size":50, "total":0, "total_pages":0 },
  "error": null,
  "billing_source": "wallet",
  "requested_at": "2026-05-19T20:23:35Z",
  "completed_at": null
}

{
  "job_id": "sw-uuid",
  "domain": "acme.example.com",
  "status": "completed",
  "leak_count": 4,
  "findings": [
    {
      "id": 2,
      "email": "[email protected]",
      "username": "alice",
      "breach_name": "leakdb",
      "breach_date": null,
      "has_password": true,                              // plaintext available via /reveal
      "password": { "sha1":"6DD85DDA386874EC…", "encrypted":true },
      "risk_level": "high"
    }
  ],
  "pagination": { "page":1, "page_size":50, "total":4, "total_pages":1 },
  "error": null,
  "billing_source": "wallet",
  "requested_at": "2026-05-19T20:23:35Z",
  "completed_at": "2026-05-19T20:23:43Z"
}

{
  "job_id": "sw-uuid",
  "status": "failed",
  "error": "no_data_available",       // or "orchestrator_job_not_found" | "orchestrator_failed"
  "leak_count": null,
  "findings": [],
  "billing_source": "wallet",
  "requested_at": "2026-05-19T20:23:35Z",
  "completed_at": "2026-05-19T20:24:01Z"
}

POST /api/v1/breach-intel/{job_id}/reveal/{finding_id}

Odszyfruj jedno hasło w postaci jawnej z wynaleziska darknet. Tylko właściciel (próby wielo-dzierżawcy zwracają 404 — obecność jest prywatna). Domena musi być nadal zweryfikowana przez orkiestrator w momencie wywołania. Tekst jawny zwracany jest bezpośrednio i NIGDY nie jest utrwalony w bazie danych SwarmHawk; każde wywołanie zapisuje jeden wiersz admin_audit_log. Brak kosztów limitów.

{
  "plaintext": "Hunter2!",
  "revealed_at": "2026-05-19T20:25:10Z"
}

GET /api/v1/jobs/{job_id}

Proxy statusu zadania do orkiestratora. job_id tutaj to identyfikator orkiestratora zwrócony przez POST /scan lub /pentest. Własność jest egzekwowana po stronie serwera — 404 przy niezgodności (existence-private). GET = bez limitów quota.

{
  "id": "orch-uuid",
  "status": "running",       // queued | running | done | failed | cancelled
  "created_at": "…",
  "updated_at": "…",
  "progress_pct": 42,        // integer 0–100 (NOT a 0–1 fraction)
  "phase": "recon",          // free-form server label, display-only
  "target": "acme.example.com"
}

GET /api/v1/jobs/{job_id}/findings

Ustrukturyzowana lista wyników (podatności, odsłonięte usługi, słabe konfiguracje itp.). Zwracana po status == 'done'.

[
  {
    "id": "f-1",
    "severity": "high",        // info | low | medium | high | critical
    "title": "Exposed admin panel",
    "target": "admin.acme.example.com",
    "description": "…"
  }
]

GET /api/v1/jobs/{job_id}/report

Pełny raport JSON (streszczenie dla kierownictwa + ustalenia + rekomendacje). Dostępny po done.

{
  "status": "done",
  "generated_at": "2026-06-03T09:12:44Z",
  "model": "claude-…",
  "report": {
    "executive_summary": "…",
    "findings": [ /* same items as /findings */ ],
    "recommendations": [ "…" ]
  }
}

GET /api/v1/jobs/{job_id}/report.pdf

Ten sam raport renderowany jako PDF (strumień binarny z nagłówkiem Content-Disposition). Przeznaczony do bezpośredniego rozpowszechniania wśród Twoich użytkowników.

Warstwa Enterprise

Warstwa Enterprise jest przeznaczona dla dostawców hostingu, MSSP-ów i innych reselllerów, którzy uruchamiają SwarmHawk jako białą etykietę API w imieniu wielu dzierżawców. Wymaga rejestracji przez administratora (bez możliwości samodzielnego zakupu) i negocjacji umowy — skontaktuj się z działem sprzedaży, aby rozpocząć onboarding.

Czym różni się od Business

• Sztywny limit domen na klienta — umowa definiuje max_domains (np. 100, 500, 5000); (N+1)-te żądanie POST /api/v1/domains zwraca 403 tier_locked z feature:"domains" i treścią zawierającą limit/current.
• Nieograniczone wywołania API — Twój klucz zawiera limit_per_month: null; miesięczny limit obowiązujący dla planów Pro/Business jest pomijany.
• Pomiar na wywołanie — każde wywołanie scan, pentest i breach-intel jest rejestrowane w niezmiennym dzienniku usage_events z efektywną ceną na klienta, możliwą do pobrania za pośrednictwem GET /api/v1/usage. Ceny dla poszczególnych usług mogą być zastąpione kontraktowo przez administratora (w przeciwnym razie stosuje się globalny cennik).
• Bez portfela / bez Stripe — Rozliczenia Enterprise odbywają się poza platformą w cyklu miesięcznych faktur. Saldo portfela Twojego resellera jest nieistotne.
• Tylko API — Klienci Enterprise nie logują się do panelu. Dział sprzedaży przekazuje Ci klucz bearer poza kanałem; wszystko poniżej działa z X-API-Key: swh_….

Dostępne punkty końcowe

Klienci Enterprise wykorzystują istniejącą powierzchnię Business /api/v1/* oraz nowy endpoint GET /api/v1/usage:

• POST /api/v1/keys, GET /api/v1/keys — wyświetlaj własne metadane klucza (sam klucz w postaci zwykłego tekstu jest wyświetlany tylko raz podczas rejestracji / regeneracji).
• POST /api/v1/domains — z zastrzeżeniem limitu max_domains dla każdego klienta.
• POST /api/v1/domains/{id}/verify
• POST /api/v1/domains/{id}/scan
• POST /api/v1/domains/{id}/pentest
• POST /api/v1/domains/{id}/breach-intel · GET /api/v1/breach-intel/{job_id}
• GET /api/v1/usage — Tylko dla Enterprise (patrz poniżej).

GET /api/v1/usage

Zagregowane wykorzystanie na domenę dla klienta Enterprise w danym okresie rozliczeniowym. Użyj tego do uzgodnienia swojej faktury miesięcznej lub do rozliczenia swoich dzierżawców na domenę.

curl https://api.swarmhawk.com/api/v1/usage?period=2026-05 \
  -H "X-API-Key: swh_…"

{
  "period": "2026-05",
  "currency": "USD",
  "domains": [
    {
      "domain_id": "d1-uuid",
      "domain": "acme.example.com",
      "scans_count": 12,
      "pentests_count": 3,
      "breach_lookups_count": 8,
      "total_cost_usd": 234.50
    }
  ],
  "totals": {
    "scans_count": 47,
    "pentests_count": 11,
    "breach_lookups_count": 22,
    "total_cost_usd": 1284.75
  }
}

Zachowanie przy dezaktywacji

Jeśli Twoje konto Enterprise zostało wstrzymane przez administratora (brak płatności, koniec umowy itp.), każde wywołanie /api/v1/* — odczyt i zapis — zwraca:

HTTP 403
{ "detail": { "error": "enterprise_inactive" } }

Klucz API nie został odwołany (dlatego reaktywacja przywraca dostęp bez ponownego wydawania kluczy), a historyczne usage_events + domains są zachowane. Skontaktuj się z zespołem sprzedaży, aby reaktywować.

Python SDK

SwarmHawk Python SDK zapewnia platformom bezpieczeństwa czysty interfejs programistyczny do pobierania wyników, konfigurowania integracji push i konsumowania wiązek STIX 2.1 — bez konieczności bezpośredniego dostępu do HTTP.

Metody SDK

API Integracji

Po włączeniu skonfiguruj integracje push, aby SwarmHawk automatycznie wysyłał krytyczne odkrycia do Twoich platform bezpieczeństwa w momencie ich wykrycia (ryzyko ≥ 70).

GET /integracje

Wyświetl wszystkie skonfigurowane integracje dla uwierzytelnionego użytkownika. Sekrety są maskowane.

POST /integracje/{service}

Zapisz lub zaktualizuj konfigurację integracji. service to jeden z: splunk · sentinel · crowdstrike · gravityzone · cortex · jira · servicenow · webhook · stix

POST /integracje/{service}/test

Przetestuj łączność bez zapisywania. Zwraca {"ok": true, "message": "..."}

DEL /integracje/{service}

Usuń konfigurację integracji.

Obsługiwane usługi

STIX / TAXII 2.1

SwarmHawk udostępnia punkt końcowy zgodny ze standardem TAXII 2.1. Połącz dowolną platformę threat intelligence (OpenCTI, MISP, ThreatConnect, Anomali), aby pobierać ustalenia SwarmHawk jako obiekty STIX 2.1.

GET /taxii/collections/

Punkt odkrywania TAXII — zwraca metadane kolekcji.

GET /taxii/collections/swarmhawk/objects/

Zwraca pakiet STIX 2.1 Twoich domen wysokiego ryzyka jako obiekty domain-name, vulnerability i relationship.

Zwrócone typy obiektów STIX

Wszystkie identyfikatory obiektów są deterministyczne (UUID5) — ta sama domena zawsze generuje ten sam identyfikator STIX we wszystkich generacjach pakietów, umożliwiając prawidłową deduplikację w downstream TIP.

Skrypty adapterów

Autonomiczne skrypty Python dla platform, w których preferujesz zaplanowane pobieranie (cron / Lambda / Azure Function) zamiast zawsze aktywnego connectora push. Każdy skrypt pobiera alerty SwarmHawk i przesyła je do platformy docelowej w jednym uruchomieniu.

Adapter TA Splunk

Emituje zdarzenia sourcetype=swarmhawk:scan z polami zgodными z CIM: dest, vendor_product, category, severity.

Adapter Microsoft Sentinel

Dane trafiają do tabeli niestandardowej SwarmHawk_CL. Przykład KQL: SwarmHawk_CL | where RiskScore_d >= 80 | sort by TimeGenerated desc

Adapter CrowdStrike Falcon

Wysyła domeny jako IOC (type=domain) w partiach po 200. Akcja to prevent dla potwierdzonych złośliwych oprogramowań/phishingu, detect dla ekspozycji CVE.

Adapter Bitdefender GravityZone

Tworzy niestandardowe reguły sieci za pośrednictwem createCustomRule. Akcja to block dla złośliwego oprogramowania/phishingu, report dla ekspozycji CVE.

Adapter Palo Alto Cortex XDR

Wysyła zewnętrzne alerty ze znacznikami technik MITRE ATT&CK (T1566, T1190, T1046, T1557…). Partie po 100 na wywołanie API.

Adapter Jira

Tworzy uporządkowane problemy ADF ze streszczeniem ryzyka, tabelą wyników CVE, stosem oprogramowania, nieudanymi kontrolami, punktami naprawczymi oraz etykietą NIS2. Uruchamia się tylko, gdy ryzyko ≥ 70 I cvss ≥ min_cvss, aby uniknąć spamu zgłoszeń.

Adapter ServiceNow

Obiekty Odpowiedzi

Sprawdzenie obiektu

Interpretacja wyniku ryzyka

Weryfikacja Nazw

Każdy wpis w tablicy checks[] raportu skanowania zawiera identyfikator check. Pełna lista identyfikatorów emitowanych przez skaner dzisiaj (źródło: backend/scanhawk_translator.py + backend/post_scan_processor.py):

Szczegółowe kontrole (np. tls_protocol, tls_cipher) są grupowane w szersze kategorie (TLS, DNS, Headers, itp.) na potrzeby wyświetlania na pulpicie nawigacyjnym. Raport PDF wykorzystuje dodatkowe etykiety przyjazne dla użytkownika (zobacz backend/main.py:CHECK_LABELS), ale identyfikatory JSON powyżej są kanoniczną powierzchnią ataku.

Spróbuj na Żywo

Pełny interaktywny eksplorator API — wykonuj rzeczywiste żądania bezpośrednio do API SwarmHawk z przeglądarki. Wklej klucz API w przycisk Authorize, aby odblokować uwierzytelnione punkty końcowe.