SwarmHawk API

SwarmHawk API vám umožňuje programový prístup k 27 automatizovaným bezpečnostným skúškam a 3000+ aktívnym šablónam CVE nástroja nuclei — SSL, DNS, CVE s potvrdeným aktívnym exploitom, vystavenie pri breach, typosquatting, analýza hrozieb AI a ďalšie — pre ľubovoľnú doménu. Používajte ho na budovanie bezpečnostných workfloov, automatizáciu due diligence alebo integráciu SwarmHawk do vlastnej platformy.

Existujú dve API plochy:

• /api/v2 — starší surface s autentifikáciou session/JWT používaný dashboardom. Väčšina operácií čítania a zápisu je dostupná aj tu z dôvodu kompatibility.
• /api/v1 — moderné verejné API pre Business / Enterprise, zabezpečené pomocou bearer API kľúčov (swh_…). Toto je cieľ pre nové integrácie.

Rýchly štart — skenujem doménu za 30 sekúnd

# 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}`);

Autentifikácia

SwarmHawk používa dve metódy autentifikácie v závislosti od koncového bodu:

Formát API kľúča

swh_3f8a2b1c4d5e6f7a8b9c0d1e2f3a4b5c

Chyby a limity sadzby

HTTP stavové kódy

Tvar chybovej odpovede

{
  "detail": "Invalid API key"
}

Limity rýchlosti

Skenovať doménu

Neexistuje žiadny jednotný endpoint "jednorazového skenu". Ak chcete skenovať doménu cez API:

1. Pridajte (a overte) doménu pomocou POST /api/v1/domains — prvá kontrola sa automaticky zaradí do frontu.
2. Ak chcete znova skenovat už pridanú doménu, zavolajte POST /api/v1/domains/{domain_id}/scan.
3. Dotazujte sa na stav cez GET /api/v1/jobs/{job_id} a na najnovšie výsledky cez GET /api/v2/domains/{domain_id}/report.
4. Pre jednorazové anonymné skeny bez účtu použite POST /public-scan (s obmedzenou frekvenciou, výsledky sa neuchovávajú).

POST /public-scan

Anonymný scan — nevyžaduje sa API kľúč. Vracia podmnožinu kontrol s niektorými výsledkami uzamknutými. Použite to na demo alebo embedy. Výsledky nie sú uložené.

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

Rýchla pasívna skúška — detekuje software stack a kontroluje známe CVE bez plnej skúšky. Odpoveď za ~3 sekundy. Výsledok sa neukladá.

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

Vypíšte všetky domény vo vašom účte s ich najnovší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

Pridajte doménu na svoj účet a zaraďte jej do frontu na skenování na pozadí.

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

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

Získajte najnovšiu úplnú správu skúšky pre doménu. Bezplatní používatelia vidí podmnožinu; platení používatelia vidia všetkých 27 skúšok vrátane validácie aktívnych CVE nástroja nuclei a zhrnutia 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

Vráťte živú výzvu vlastníctva vydanú orchestrátorom verifikácie. SwarmHawk podporuje dve metódy verifikácie — DNS TXT záznam alebo HTTP upload súboru. Zavolajte POST /domains/{domain_id}/verify s method: "dns" alebo "http" po publikovaní záznamu/súboru.

{
  "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žiadajte orchestrátor o potvrdenie vlastníctva pomocou vybranej metódy. Pri úspešnom overení sa domains.verified_at zapíše a vráti v následných odpovediach správ. Orchestrátor si ukladá pozitívne overenia do vyrovnávacej pamäte 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}/história

Trend skóre rizika v čase — užitočný na vytváranie dashboardov alebo upozorňovania na zvýšenie 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

Mapovať zistenia skenu na články NIS2 Direktívy. Vracia skóre zhody a stav podľa článku — vhodné ako dôkaz auditu pre 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

Vytvorte briefing hrozieb poháňaný AI pre váš portfólio domén pomocou Claude. Vracia štruktúrovaný briefing s výkonným zhrnutím, kritickými zisteniami a prioritami nápravy.

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

POST /api/v2/keys

Vytvorte nový kľúč API pre vašu účet. Vracia všetky kľúče vrátane nové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

Vypíšte všetky API kľúče a ich využitie za aktuálny mesiac.

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

DELETE /api/v2/keys/{key}

Okamžite zrušte kľúč API. Všetky budúce požiadavky s týmto kľúčom budú odmietnuté.

{ "revoked": "swh_3f8a2b1c…" }

Business / Enterprise API — /api/v1

Plocha /api/v1/* je produkčné API na zápis používané zákazníkmi Business a Enterprise. Každý endpoint nižšie akceptuje buď X-API-Key: swh_… (odporúčané pre komunikáciu server-to-server) alebo Authorization: Bearer <jwt> (pre interné nástroje).

Vrstvové brány

• Zadarmo — Prístup k API odmietnutý (403 API_ACCESS_REQUIRED).
• Pro — 10-hodinová skúšobná verzia len na čítanie. Koncové body zápisu vracajú 403 business_required.
• Business — 500 hovorov/mesiac, debet peňaženky/oprávnenia za sken/pentest/únik.
• Enterprise — neobmedzené volania; administrátorská registrácia s limitom max_domains na zákazníka a meraním podľa volania (detaily).

Typický tok predajcu

# 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

Vydajte kľúč API pre aktuálneho používateľa. Business: jeden kľúč, 500 volaní/mesiac. Enterprise: jeden kľúč, bez limitu (spravovaný správcom cez /admin/api/v1/enterprise/*). Iba Bearer JWT — nemôžete si spustiť svoj prvý kľúč sám sebou; vstupným bodom je prihlásenie na paneli (alebo enrolácia správcom pre 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

Zoznam aktívnych kľúčov + využitie v aktuálnom mesiaci. Obyčajný text sa nikdy znova nezobrazuje. Iba Bearer JWT — na endpointy správy kľúčov nie je možné pristúpiť pomocou API kľúča.

{ "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šiť existujúci kľúč a vydať nový. Nový otvorený text sa zobrazí raz v odpovedi — predchádzajúci kľúč prestane pracovať okamžite. Iba Bearer JWT.

DELETE /api/v1/keys/{key_id}

Zrušiť kľúč. Idempotentné. Iba Bearer JWT.

GET /api/v1/domains

Zoznam domén volajúceho. Stránkovaný; podporuje ?limit a ?offset.

POST /api/v1/domains

Pridajte doménu a automaticky inicializujte overovanie orchestrátora. Vráti DNS-TXT challenge bezprostredne, aby ste ho mohli poskytnúť svojmu tenantovi bez ďalšieho volania. Bezplatne pre zákazníka — pridávanie domén neodpočítava z peňaž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}

Detaily jednej domény: risk_score, last_scanned_at, verified_at, krajina, atď. 404 pri nezhode.

PATCH /api/v1/domains/{domain_id}

Prepínajte auto_rescan_enabled pre doménu (jedinou upraviteľné pole na tomto endpointe v súčasnosti). Povolenie vyžaduje tier Pro alebo vyšší (feature gate daily_rescan); vypnutie je vždy povolené. Ak chcete zmeniť industry, primary_contact alebo country, odstráňte a znova pridajte 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é vymazanie domény. Riadok, jej stav verifikácie a všetky súvisiace záznamy úloh sú odstránené. Uvoľňuje slot v rámci limitu úrovne. Kvóta +1.

POST /api/v1/domains/bulk-import

Multipart nahrávanie CSV — každý riadok je doména,krajina (krajina je povinná, 2-písmenový kód ISO). Prvý riadok môže byť hlavička doména,krajina — je preskočený. Rešpektuje limit pre každého zákazníka; riadky, ktoré limit prekročia, skončia v zozname rejected s dôvodom quota exceeded. Kvóta +1 na volanie (nie na riadok).

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

Chronologicky usporiadaný zoznam predchádzajúcich skanov + zmeny kontrol pre doménu.

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

Iba na čítanie dostupné načítanie aktuálneho stavu autorizačnej výzvy z orchestrátora (DNS + HTTP cesta + hodnoty záznamov + čas vypršania). Použite toto, ak potrebujete znova zobraziť výzvu po stratení pôvodnej odpovede 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žiadajte orchestrátor, aby skutočne spustil kontrolu. method=dns (predvolené nastavenie) vykonáva vyhľadávanie TXT záznamu; method=http načíta https://<doména><http_cesta> a porovná s http_telo.

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

Odošlite skenovanie povrchu útokov orchestrátoru. Bez overenia domény — ktorákoľvek pridaná doména je oprávnená. Business: odpisy peňaženky/oprávnenia podľa service_prices.attack_surface. Enterprise: zaznamenáva riadok usage_events s efektívnou cenou na zákazníka, bez dotyku peňaženky. Kvóta +1 pri 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

Odošlite AI pentest. Voliteľný parameter rate_profile kontroluje agresivitu skanu: stealth (3 rps) · regular (10 rps, predvolené) · aggressive (25 rps). Všetky ostatné parametre zostávajú na predvolených hodnotách orchestrátora. Rovnaké rozdelenie peňaženky/merania ako /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

Spustite úlohu výskumu darknet, ktorá skontroluje zdroje darknet na poverenia, hashe a osobné údaje viazané na túto doménu. Asynchronne — okamžite vracia job_id; dotazujte GET /api/v1/breach-intel/{job_id} na stav a zistenia. Typické end-to-end dokončenie je 30–90 s. Doména musí byť overená. Business: odpíše peňaženku/oprávnenie podľa service_prices.breach_intel. Enterprise: zaznamenáva riadok usage_events s efektívnou cenou na zákazníka, bez dotyku peňaženky. Kvóta +1 pri prijatom odoslaní. Cooldown na doménu: 7 dní (okno darknet orchestrátora).

{
  "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 úlohu výskumu darknet. Skontrolované vlastníctvo; žiadna kvóta. Backend lenivo dotazuje orchestrátora (škrtenie 5 s) zatiaľ čo je lokálny riadok stále running, takže tento endpoint sa dá volať často bez zaplavenia upstream. Keď sa úloha dostane do terminálneho stavu (completed | failed | cancelled), nasledujúce volania vrátia uložený riadok bez akéhokoľvek round-trip orchestrátora.

{
  "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 čistom texte zo zistenia darknet. Len vlastník (pokusy cross-tenant vrátia 404 — existencia-privátna). Doména musí byť v čase volania stále overená orchestrátorom. Čistý text je vrátený inline a nikdy sa NEpersistuje v SwarmHawk DB; každé volanie zapíše jeden riadok admin_audit_log. Bez nákladov na kvótu.

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

GET /api/v1/jobs/{job_id}

Proxy stavu úlohy orchestrátoru. job_id je tu identifikátor orchestrátoru vrátený pomocou POST /scan alebo /pentest. Vlastníctvo je vynútené na strane servera — 404 pri neshode (existencia-privátna). 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

Štruktúrovaný zoznam zistení (zraniteľnosti, exponované služby, slabé konfigurácie atď.). Vrátený 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

Úplná JSON správa (zhrnutie pre vedenie + zistenia + odporúčania). 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

Rovnaká správa vykreslená ako PDF (binárny tok s upstream Content-Disposition). Vhodné na priamu redistribúciu vašemu nájomcovi.

Podniková úroveň

Úroveň Enterprise je určená pre poskytovateľov hostingu, MSSP a ďalších predajcov, ktorí prevádzkujú SwarmHawk ako white-label API v prospech mnohých tenantov. Vyžaduje registráciu správcu (bez samoobslužného nákupu) a zmluvnú dohodu — kontaktujte obchodný tím pre zaradenie.

Čo je iné oproti Business

• Pevný limit domén na zákazníka — vaša zmluva nastavuje max_domains (napr. 100, 500, 5000); (N+1)-ty POST /api/v1/domains vráti 403 tier_locked s feature:"domains" a telom s limit/current.
• Neobmedzené API volania — váš kľúč má nastavené limit_per_month: null; mesačná kvóta platná pre Pro/Business je obídená.
• Metriky na základe volaní — každé volanie scan, pentest a breach-intel je zaznamenané v nezmeneniteľnom protokole usage_events s efektívnou cenou na zákazníka, ktorú je možné získať prostredníctvom GET /api/v1/usage. Ceny jednotlivých služieb je možné administrátorom prepísať v zmluve (inak sa používajú globálne cenové tabuľky).
• Bez peňaženky / bez Stripe — Faktúrácia Enterprise prebieha mimo platformy s mesačným cyklom faktúr. Zostatok peňaženky vášho resellera je irelevantný.
• Iba API — Podnikoví zákazníci sa neprihlasujú do ovládacieho panela. Predajný tím vám odovzdá kľúč nosiča mimo pásma; všetko nižšie funguje s X-API-Key: swh_….

Dostupné koncové body

Zákazníci Enterprise používajú existujúci Business /api/v1/* povrch plus nový GET /api/v1/usage:

• POST /api/v1/keys, GET /api/v1/keys — zobraziť svoje vlastné metadáta kľúča (samotný kľúč v otvorenom texte sa zobrazuje len raz pri registrácii / regenerácii).
• POST /api/v1/domains — podlieha 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 — Len pre podnikanie (pozri nižšie).

GET /api/v1/usage

Agregácia použitia na jednotlivé domény pre zákazníka Enterprise v danom mesačnom fakturačnom období. Použite to na zosúladenie svojej mesačnej faktúry alebo na fakturáciu vašich vlastných nájomcov na jednotlivé domény.

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

Správanie pri deaktivácii

Ak je váš podnikový účet pozastavený správcom (neplatenie, koniec zmluvy atď.), každé volanie /api/v1/* — čítanie aj zápis — vráti:

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

Kľúč API nie je odvolaný (takže reaktivácia obnoví prístup bez opätovného vydania kľúčov) a historické usage_events + domains sú zachované. Kontaktujte oddel predaja na reaktiváciu.

Python SDK

Súprava SwarmHawk Python SDK poskytuje bezpečnostným platformám čisté programové rozhranie na sťahovanie zistení, konfiguráciu push integrácií a konzumáciu STIX 2.1 balíkov — bez potreby surových HTTP požiadaviek.

Metódy SDK

API integrácie

Po aktivácii nakonfigurujte push integrácie tak, aby SwarmHawk automaticky odosielal kritické zistenia do vašich bezpečnostných platforiem v momente ich detekcie (riziko ≥ 70).

GET /integrácie

Zoznam všetkých nakonfigurovaných integácií pre autentifikovaného používateľa. Tajomstvá sú maskované.

POST /integrácie/{service}

Uložiť alebo aktualizovať konfiguráciu integrácie. service je jeden z: splunk · sentinel · crowdstrike · gravityzone · cortex · jira · servicenow · webhook · stix

POST /integrations/{service}/test

Testujte konektivitu bez uloženia. Vracia {"ok": true, "message": "..."}

DEL /integracie/{service}

Odstráňte konfiguráciu integrácie.

Podporované služby

STIX / TAXII 2.1

SwarmHawk poskytuje kompatibilný endpoint TAXII 2.1. Pripojte akúkoľvek platformu hromadenia dômyselnosti o hrozbách (OpenCTI, MISP, ThreatConnect, Anomali) na načítavanie zistení SwarmHawk ako objekty STIX 2.1.

GET /taxii/collections/

TAXII discovery endpoint — vracia metadáta kolekcie.

GET /taxii/collections/swarmhawk/objects/

Vracia STIX 2.1 balík vašich domén s vysokým rizikom ako objekty domain-name, vulnerability a relationship.

Vrátené typy objektov STIX

Všetky ID objektov sú deterministické (UUID5) — rovnaná doména vždy generuje rovnaké STIX ID v rámci generácií balíkov, čo umožňuje správnu deduplicitu v nadväzujúcich TIP systémoch.

Skripty adaptérov

Samostatné Python skripty pre platformy, kde uprednostňujete naplánovaný pull (cron / Lambda / Azure Function) namiesto vždy aktívneho push konektora. Každý skript načíta výstrahy SwarmHawk a v jednom behu ich pošle do cieľovej platformy.

Adapter Splunk TA

Emituje sourcetype=swarmhawk:scan udalosti s poľami zladenými s CIM: dest, vendor_product, category, severity.

Adaptér Microsoft Sentinel

Údaje sú uložené v vlastnej tabuľke SwarmHawk_CL. Príklad KQL: SwarmHawk_CL | where RiskScore_d >= 80 | sort by TimeGenerated desc

Adaptér CrowdStrike Falcon

Posúva domény ako IOCs (type=domain) v dávkach po 200. Akcia je prevent pre potvrdenú malvér/phishing, detect pre CVE expozíciu.

Adaptér Bitdefender GravityZone

Vytvára vlastné pravidlá siete prostredníctvom createCustomRule. Akcia je block pre malware/phishing, report pre CVE expozíciu.

Adaptér Palo Alto Cortex XDR

Posiela externými upozorneniami s značkami techník MITRE ATT&CK (T1566, T1190, T1046, T1557…). Dávky po 100 na jedno volanie API.

Jira adaptér

Vytvárajú štruktúrované ADF issues so súhrnnou tabuľkou rizík, zisteniami CVE, softvérovým stackom, neúspešnými kontrolami, bodmi na nápraву a nálepkou NIS2. Spúšťajú sa len keď riziko ≥ 70 A cvss ≥ min_cvss, aby sa predišlo spam ticketom.

Adaptér ServiceNow

Objekty odozvy

Kontrola objektu

Interpretácia skóre rizika

Kontrola mien

Každá položka v poli checks[] správy o skenovaní má identifikátor check. Úplný zoznam identifikátorov vydávaných skenerom v súčasnosti (zdroj: backend/scanhawk_translator.py + backend/post_scan_processor.py):

Granulárne kontroly (napr. tls_protocol, tls_cipher) sú zoskupené pod širšie kategórie (TLS, DNS, Headers, atď.) na zobrazenie v dashboarde. Správa PDF používa dodatočné používateľsky prívlasť označenia (pozri backend/main.py:CHECK_LABELS, ale identifikátory JSON vyššie sú kľúčovým povrchom útoku.

Vyskúšajte Live

Úplný interaktívny API prehliadač — vykonávajte reálne požiadavky proti SwarmHawk API priamo z vášho prehliadača. Vložte svoj API kľúč do tlačidla Authorize na odomknutie autentifikovaných koncových bodov.