SwarmHawk API

SwarmHawk API vám poskytuje programový přístup k 27 automatizovaným bezpečnostním kontrolám plus více než 3000 aktivním šablonám nuclei CVE — SSL, DNS, CVE s potvrzením aktivního exploitu, expozice breachů, typosquaty, AI analýza hrozeb a další — pro jakoukoli doménu. Využijte jej k vytváření bezpečnostních workflowů, automatizaci due diligence nebo integraci SwarmHawk do vaší vlastní platformy.

Existují dva API povrchy:

• /api/v2 — starší povrch ověřený pomocí session/JWT používaný dashboardem. Nejvíce operací čtení a zápisu je dostupných také zde pro zajištění kompatibility.
• /api/v1 — moderní veřejné Business / Enterprise API, zabezpečené pomocí bearer API klíčů (swh_…). Toto by měly cílit nové integrace.

Rychlý start — naskenujte doménu za 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}`);

Ověřování

SwarmHawk používá dvě metody ověřování v závislosti na koncovém bodu:

Formát API klíče

swh_3f8a2b1c4d5e6f7a8b9c0d1e2f3a4b5c

Chyby a omezení četnosti

HTTP stavové kódy

Struktura chybové odpovědi

{
  "detail": "Invalid API key"
}

Omezení rychlosti

Skenovat doménu

Neexistuje jediný "single-shot scan" endpoint. Chcete-li pomocí API skenovat doménu:

1. Přidejte (a ověřte) doménu pomocí POST /api/v1/domains — první scan se zařadí do fronty automaticky.
2. Chcete-li znovu prohledat již přidanou doménu, zavolejte POST /api/v1/domains/{domain_id}/scan.
3. Dotazujte se GET /api/v1/jobs/{job_id} na stav a GET /api/v2/domains/{domain_id}/report na nejnovější výsledky.
4. Pro jednorázové anonymní skenování bez účtu použijte POST /public-scan (s omezením rychlosti, výsledky se neukládají).

POST /public-scan

Anonymní sken — není vyžadován API klíč. Vrací podmnožinu kontrol s některými výsledky zamčenými. Použijte pro демонstrace nebo vkládání. Výsledky nejsou ukládány.

{
  "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

Rychlá pasivní analýza — detekuje softwarový stack a kontroluje známé CVE bez plné skenování. Odpověď přibližně za 3 sekundy. Žádný výsledek se neukládá.

{
  "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

Seznamte všechny domény ve vašem účtu s jejich nejnovějšími skóre rizika a 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

Přidejte doménu do svého účtu a zařaďte ji do fronty pro běžné skenování na pozadí.

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

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

Načtěte nejnovější úplnou zprávu ze skanu domény. Bezplatní uživatelé vidí podmnožinu; placení uživatelé vidí všech 27 kontrol včetně validace aktivních CVE nuclei a shrnutí z 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

Vraťte live ověřovací challenge vydaný orchestrátorem ověření. SwarmHawk podporuje dvě metody ověření — DNS TXT záznam nebo HTTP upload souboru. Zavolejte POST /domains/{domain_id}/verify s parametrem method: "dns" nebo "http" poté, co je záznam/soubor publikován.

{
  "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

Požádejte orchestrátor, aby potvrdil vlastnictví pomocí vybrané metody. Po úspěšném ověření se domains.verified_at zapíše a vrátí v následujících odpovědích reportu. Orchestrátor ukládá kladná ověření do mezipaměti na 7 dní.

{ "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 skóre rizika v čase — užitečné pro vytváření řídicích panelů nebo upozornění na zvýšení skóre.

{
  "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

Mapujte zjištění skenů na články Směrnice NIS2. Vrací skóre compliance a stav pro jednotlivé články — vhodné jako důkazní materiál pro regulační orgány.

{
  "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

Generujte briefing hrozeb poháněný umělou inteligencí pro vaše portfolio domén pomocí Claude. Vrací strukturovaný briefing se shrnutím pro vedení, kritickými zjišťováními a prioritami nápravy.

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

POST /api/v2/keys

Vytvořte nový klíč API pro váš účet. Vrátí všechny klíče včetně nově vytvořeného.

{
  "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

Vypište seznam všech API klíčů a jejich využití za aktuální měsíc.

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

DELETE /api/v2/keys/{key}

Okamžitě zrušte klíč API. Všechny budoucí požadavky s tímto klíčem budou zamítnuty.

{ "revoked": "swh_3f8a2b1c…" }

Business / Enterprise API — /api/v1

Plocha /api/v1/* je produkční write API používané zákazníky Business a Enterprise. Každý endpoint níže přijímá buď X-API-Key: swh_… (doporučeno pro komunikaci server-to-server) nebo Authorization: Bearer <jwt> (pro interní nástroje).

Vrstvení přístupu

• Zdarma — Přístup k API odepřen (403 API_ACCESS_REQUIRED).
• Pro — 10 volání zkušební verze pouze pro čtení. Koncové body zápisu vrací 403 business_required.
• Business — 500 volání za měsíc, účtování peněženky/nároku za sken/penetrační test/bezpečnostní incident.
• Enterprise — neomezené volání; správcovská registrace s limitem max_domains na zákazníka a měřením na volání (podrobnosti).

Typický tok prodejce

# 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

Vydejte klíč API pro aktuálního uživatele. Business: jeden klíč, 500 volání/měsíc. Enterprise: jeden klíč, bez omezení (spravuje admin přes /admin/api/v1/enterprise/*). Pouze Bearer JWT — první klíč nelze spustit pomocí sebe sama; vstupním bodem je přihlášení do dashboardu (nebo registrace adminem pro Enterprise).

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

Seznam aktivních klíčů + využití v aktuálním měsíci. Prostý text se nikdy znovu nezobrazuje. Pouze Bearer JWT — endpointy pro správu klíčů nejsou dosažitelné pomocí API klíče.

{ "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

Zrušte existující klíč a vydejte nový. Nový prostý text se zobrazí jednou v odpovědi — předchozí klíč přestane fungovat okamžitě. Pouze Bearer JWT.

DELETE /api/v1/keys/{key_id}

Zrušit klíč. Idempotentní operace. Pouze Bearer JWT.

GET /api/v1/domains

Vypsat domény volajícího. S stránkováním; respektuje ?limit a ?offset.

POST /api/v1/domains

Přidejte doménu a atomicky inicializujte ověření orchestratoru. Vrátí DNS-TXT challenge inline, takže jej můžete doručit svému tenantovi bez následného hovoru. Zdarma pro zákazníka — přidání domén se neodečítá z peněženky.

{
  "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}

Detail jedné domény: risk_score, last_scanned_at, verified_at, country, atd. 404 při neshodě.

PATCH /api/v1/domains/{domain_id}

Přepněte auto_rescan_enabled pro doménu (jediné měnitelné pole na tomto endpointu). Povolení vyžaduje tier Pro nebo vyšší (feature gate daily_rescan); zakázání je vždy povoleno. Pro změnu industry, primary_contact nebo country smažte a znovu přidejte doménu.

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}

Trvalé smazání domény. Řádek, její stav ověření a všechny přidružené záznamy úloh jsou odstraněny. Uvolňuje slot proti limitu úrovně. Kvóta +1.

POST /api/v1/domains/bulk-import

Víceúčelové nahrání CSV — každý řádek obsahuje doména,země (země je povinná, 2místný kód ISO). První řádek může být záhlavím doména,země — bude přeskočen. Respektuje limit na zákazníka; řádky, které překročí limit, jsou zařazeny do seznamu rejected s důvodem quota exceeded. Kvóta +1 za volání (ne za řádek).

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

Chronologicky seřazený seznam minulých skenů + změny kontrol domény.

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

Přístup pouze pro čtení k aktuálnímu stavu autorizační výzvy z orchestrátoru (DNS + HTTP path + hodnoty záznamů + vypršení platnosti). Použijte toto, pokud potřebujete znovu zobrazit výzvu poté, co dojde ke ztrátě počáteční odpovědi 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

Požádejte orchestrátor, aby skutečně spustil kontrolu. method=dns (výchozí) provede vyhledání TXT záznamu; method=http načte https://<domain><http_path> a porovná s 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

Odešlete scan povrchu útoků orchestrátoru. Bez ověření domény — každá přidaná doména je způsobilá. Business: debituje peněženku/oprávnění podle service_prices.attack_surface. Enterprise: zaznamenává řádek usage_events s efektivní cenou na zákazníka, bez doteku peněženky. Kvóta +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

Odešlete AI pentest. Volitelný parametr rate_profile řídí agresivitu skenování: stealth (3 rps) · regular (10 rps, výchozí) · aggressive (25 rps). Všechny ostatní parametry zůstávají na výchozích hodnotách orchestrátoru. Stejné rozdělení peněženky/měření jako /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

Zařadit úlohu darknet-research, která křížově kontroluje darknet zdroje na přihlašovací údaje, haše a PII navázané na tuto doménu. Asynchronní — vrátí job_id okamžitě; dotazujte se GET /api/v1/breach-intel/{job_id} na stav a nálezy. Typické end-to-end dokončení trvá 30–90 s. Doména musí být ověřena. Business: strhne peněženku/nárok podle service_prices.breach_intel. Enterprise: zaznamená řádek usage_events s efektivní cenou na zákazníka, bez doteku peněženky. Kvóta +1 při přijatém odeslání. Chladnutí na doménu: 7 dní (darknet okno orchestrátoru).

{
  "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}

Dotazujte se na úlohu darknet-research. Ověření vlastnictví; bez kvóty. Backend líně dotazuje orchestrátor (5 s omezení) zatímco lokální řádek je stále running, takže tento endpoint lze volat často bez zaplavení upstream. Jakmile se úloha dostane do terminálního stavu (completed | failed | cancelled), následující volání vrátí uložený řádek bez jakéhokoliv round-trip orchestrátoru.

{
  "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}

Dešifrujte jedno heslo v prostém textu z darknet nálezu. Pouze vlastník (pokusy z více tenantů vrátí 404 — existence-privátní). Doména musí být v čase volání stále ověřena orchestrátorem. Prostý text je vrácen inline a NIKDY není uchováván v SwarmHawk DB; každé volání zapíše jeden řádek admin_audit_log. Bez nákladů na kvótu.

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

GET /api/v1/jobs/{job_id}

Proxy stavu úlohy pro orchestrátor. job_id zde je ID orchestrátoru vrácené metodou POST /scan nebo /pentest. Vlastnictví je vynucováno na straně serveru — 404 při neshodě (existence-private). GET = bez kvóty.

{
  "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

Strukturovaný seznam zjištění (zranitelnosti, exponované služby, slabé konfigurace atd.). Vrácen poté, co 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

Úplná JSON zpráva (executive summary + zjištění + doporučení). Dostupná 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

Stejná zpráva vykreslená jako PDF (binární proud s upstream Content-Disposition). Vhodné pro přímou redistribuci vašemu tenantovi.

Podniková úroveň

Úroveň Enterprise je určena pro poskytovatele hostingu, MSSP a další prodejce, kteří provozují SwarmHawk jako bílou značku API jménem mnoha tenantů. Vyžaduje enrollování administrátorem (bez self-service nákupu) a smluvní vyjednávání — kontaktujte prodej pro zapojení.

Co se liší od Business

• Pevný limit domén na zákazníka — vaše smlouva nastavuje max_domains (např. 100, 500, 5000); (N+1). POST /api/v1/domains vrací 403 tier_locked s feature:"domains" a tělem limit/current.
• Neomezená volání API — váš klíč má nastaveno limit_per_month: null; měsíční kvóta platná pro Pro/Business je obejita.
• Měření po jednotlivých voláních — každé volání scan, pentest a breach-intel je zaznamenáno do neměnného protokolu usage_events s efektivní cenou na zákazníka, kterou lze získat prostřednictvím GET /api/v1/usage. Ceny za jednotlivé služby mohou být administrátorem přepsány smlouvou (v opačném případě se použije globální ceník).
• Bez peněženky / bez Stripe — Fakturace pro podnikové řešení probíhá mimo platformu na měsíční bázi. Zůstatek peněženky vašeho prodejce je irelevantní.
• Pouze API — Podnikoví zákazníci se nepřihlašují na dashboard. Prodejní tým vám předá váš bearer key mimo kanál; vše níže funguje s X-API-Key: swh_….

Dostupné endpointy

Firemní zákazníci používají existující plochu Business /api/v1/* plus nové GET /api/v1/usage:

• POST /api/v1/keys, GET /api/v1/keys — zobrazit vlastní metadata klíče (samotný klíč v plain textu se zobrazí pouze jednou při registraci / regeneraci).
• POST /api/v1/domains — podléhá limitu max_domains na zákazníka.
• 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 — Pouze pro Enterprise (viz níže).

GET /api/v1/usage

Agregované užití na doménu pro zákazníka Enterprise v daném měsíčním fakturačním období. Použijte k odsouhlasení své měsíční faktury nebo k fakturaci vlastních tenantů na doménu.

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
  }
}

Chování deaktivace

Pokud je váš Enterprise účet administratorem pozastaven (nezaplacení, konec smlouvy atd.), každé volání /api/v1/* — čtení i zápis — vrátí:

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

Klíč API není odvolán (takže reaktivace obnoví přístup bez opětovného vydání klíčů) a historické usage_events + domains jsou zachovány. Reaktivaci můžete provést kontaktováním obchodního týmu.

Python SDK

SwarmHawk Python SDK poskytuje bezpečnostním platformám čistý programový interface pro stahování zjištění, konfiguraci push integrací a konzumaci STIX 2.1 balíčků — bez potřeby surových HTTP požadavků.

Metody SDK

Integrační API

Po aktivaci nakonfigurujte push integraci tak, aby SwarmHawk automaticky odesílal kritické nálezy vaším bezpečnostním platformám ihned po jejich detekci (riziko ≥ 70).

GET /integrace

Vypsat všechny nakonfigurované integrace pro ověřeného uživatele. Tajné údaje jsou maskované.

POST /integrations/{service}

Uložit nebo aktualizovat konfiguraci integrace. service je jeden z: splunk · sentinel · crowdstrike · gravityzone · cortex · jira · servicenow · webhook · stix

POST /integrations/{service}/test

Otestujte připojení bez uložení. Vrací {"ok": true, "message": "..."}

DEL /integrations/{service}

Odebrat konfiguraci integrace.

Podporované služby

STIX / TAXII 2.1

SwarmHawk poskytuje TAXII 2.1-kompatibilní koncový bod. Připojte jakoukoli platformu pro analýzu hrozeb (OpenCTI, MISP, ThreatConnect, Anomali) a stahujte zjištění SwarmHawk jako STIX 2.1 objekty.

GET /taxii/collections/

TAXII discovery endpoint — vrací metadata kolekce.

GET /taxii/collections/swarmhawk/objects/

Vrací STIX 2.1 balíček vašich vysoce rizikových domén jako objekty domain-name, vulnerability a relationship.

Vrácené typy objektů STIX

Všechny ID objektů jsou deterministická (UUID5) — stejná doména vždy generuje stejné STIX ID při vytváření balíčků, což umožňuje správnou deduplicaci v downstream TIPs.

Skripty adaptérů

Samostatné Python skripty pro platformy, kde upřednostňujete plánované stahování (cron / Lambda / Azure Function) před stále aktivním push connectorem. Každý skript načte upozornění SwarmHawk a odešle je do cílové platformy v jednom spuštění.

Splunk TA adaptér

Vysílá sourcetype=swarmhawk:scan události s poli zarovnanými podle CIM: dest, vendor_product, category, severity.

Adaptér Microsoft Sentinel

Data se ukládají do vlastní tabulky SwarmHawk_CL. Příklad KQL: SwarmHawk_CL | where RiskScore_d >= 80 | sort by TimeGenerated desc

Adaptér CrowdStrike Falcon

Odesílá domény jako IOC (typ=doména) v dávkách po 200. Akce je prevent pro potvrzený malware/phishing, detect pro CVE expozici.

Adaptér Bitdefender GravityZone

Vytváří vlastní síťová pravidla prostřednictvím createCustomRule. Akce je block pro malware/phishing, report pro CVE expozici.

Adaptér Palo Alto Cortex XDR

Odesílá externí upozornění s tagy technik MITRE ATT&CK (T1566, T1190, T1046, T1557…). Dávky po 100 na volání API.

Adaptér Jira

Vytváří strukturované ADF úkoly se souhrnem rizik, tabulkou zjištění CVE, zásobníkem softwaru, neúspěšnými kontrolami, odrážkami náprav a štítkem NIS2. Aktivuje se pouze při riziku ≥ 70 A cvss ≥ min_cvss, aby se předešlo spamování tiketů.

Adaptér ServiceNow

Objekty odpovědi

Kontrola objektu

Interpretace skóre rizika

Ověření Názvů

Každá položka v poli checks[] zprávy o skenování obsahuje identifikátor check. Úplný seznam identifikátorů vydávaných skenerem dnes (zdroj: backend/scanhawk_translator.py + backend/post_scan_processor.py):

Granulární kontroly (např. tls_protocol, tls_cipher) jsou v dashboardu seskupeny pod širší kategorie (TLS, DNS, Headers atd.). Zpráva v PDF používá dodatečné uživatelsky přívětivé popisky (viz backend/main.py:CHECK_LABELS), ale výše uvedené identifikátory JSON jsou kanonickým povrchem.

Vyzkoušejte Live

Plně interaktivní průzkumník API — provádějte skutečné požadavky proti rozhraní SwarmHawk API přímo z vašeho prohlížeče. Vložte svůj klíč API do tlačítka Autorizace a odemkněte autentizované endpointy.