SwarmHawk API

Die SwarmHawk API gibt Ihnen programmatischen Zugriff auf 27 automatisierte Sicherheitsprüfungen plus 3.000+ aktive Nuclei CVE-Templates — SSL, DNS, CVEs mit aktiver Exploit-Bestätigung, Breach-Exposure, Typosquats, KI-Threat-Analyse und mehr — für jede Domain. Nutzen Sie sie, um Sicherheits-Workflows zu erstellen, Due Diligence zu automatisieren oder SwarmHawk in Ihre eigene Plattform zu integrieren.

Es gibt zwei API-Oberflächen:

• /api/v2 — die Legacy-Session-/JWT-authentifizierte Oberfläche, die vom Dashboard verwendet wird. Die meisten Lese- und Schreibvorgänge sind hier ebenfalls für Kompatibilität verfügbar.
• /api/v1 — die moderne öffentliche Business / Enterprise API, gesichert mit Bearer API Keys (swh_…). Dies ist das Ziel für neue Integrationen.

Quick Start — eine Domain in 30 Sekunden scannen

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

Authentifizierung

SwarmHawk verwendet je nach Endpunkt zwei Authentifizierungsmethoden:

API-Schlüsselformat

swh_3f8a2b1c4d5e6f7a8b9c0d1e2f3a4b5c

Fehler & Rate Limits

HTTP-Statuscodes

Fehlerantwort-Struktur

{
  "detail": "Invalid API key"
}

Ratenbegrenzungen

Eine Domain scannen

Es gibt keinen einzelnen "One-Shot-Scan"-Endpunkt. Um eine Domain über die API zu scannen:

1. Fügen Sie die Domain mit POST /api/v1/domains hinzu (und verifizieren Sie sie) – der erste Scan wird automatisch in die Warteschlange eingereiht.
2. Um eine bereits hinzugefügte Domain erneut zu scannen, rufen Sie POST /api/v1/domains/{domain_id}/scan auf.
3. Rufen Sie GET /api/v1/jobs/{job_id} für den Status ab und GET /api/v2/domains/{domain_id}/report für die neuesten Ergebnisse.
4. Für einmalige anonyme Scans ohne Konto verwenden Sie POST /public-scan (Rate-Limited, Ergebnisse werden nicht gespeichert).

POST /public-scan

Anonymer Scan — kein API-Schlüssel erforderlich. Gibt eine Teilmenge von Prüfungen mit einigen gesperrten Ergebnissen zurück. Verwenden Sie dies für Demos oder Einbettungen. Ergebnisse werden nicht gespeichert.

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

Schnelle Fingerprint-Analyse — erkennt den Software-Stack und prüft auf bekannte CVEs ohne vollständige Scan. Antwort in ~3 Sekunden. Keine Ergebnisse gespeichert.

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

Zeigen Sie alle Domains in Ihrem Konto mit ihren neuesten Risikobewertungen und Prüfungen an.

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

Fügen Sie eine Domain zu Ihrem Konto hinzu und starten Sie einen Hintergrund-Scan.

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

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

Rufen Sie den neuesten vollständigen Scan-Bericht für eine Domain ab. Kostenlose Benutzer sehen eine Teilmenge; zahlende Benutzer sehen alle 27 Prüfungen einschließlich Nuclei Active CVE Validierung und KI-Zusammenfassung.

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

Geben Sie die Live-Eigentümerschaftsprüfung zurück, die vom Verification Orchestrator ausgegeben wurde. SwarmHawk unterstützt zwei Verifizierungsmethoden — DNS-TXT-Eintrag oder HTTP-Datei-Upload. Rufen Sie POST /domains/{domain_id}/verify mit method: "dns" oder "http" auf, sobald der Eintrag/die Datei veröffentlicht ist.

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

Fordern Sie den Orchestrator auf, den Besitz mit der ausgewählten Methode zu bestätigen. Bei erfolgreicher Verifizierung wird domains.verified_at geschrieben und in nachfolgenden Report-Responses zurückgegeben. Der Orchestrator speichert positive Verifizierungen 7 Tage lang.

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

Risiko-Score-Trend im Zeitverlauf — nützlich für die Erstellung von Dashboards oder Warnungen bei Score-Anstieg.

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

Ordnen Sie Scan-Erkenntnisse den Artikeln der NIS2-Richtlinie zu. Liefert eine Compliance-Bewertung und Status pro Artikel — geeignet als Audit-Nachweis für Regulierungsbehörden.

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

Erstellen Sie ein KI-gestütztes Threat-Briefing für Ihr Domain-Portfolio mit Claude. Liefert ein strukturiertes Briefing mit Executive Summary, kritischen Erkenntnissen und Remediation-Prioritäten.

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

POST /api/v2/keys

Erstellen Sie einen neuen API-Schlüssel für Ihr Konto. Gibt alle Schlüssel einschließlich des neuen zurück.

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

Alle API-Schlüssel und deren Nutzung für den aktuellen Monat auflisten.

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

DELETE /api/v2/keys/{key}

Widerrufen Sie einen API-Schlüssel sofort. Alle zukünftigen Anfragen mit diesem Schlüssel werden abgelehnt.

{ "revoked": "swh_3f8a2b1c…" }

Business / Enterprise API — /api/v1

Die /api/v1/* Oberfläche ist die produktive Schreib-API für Business- und Enterprise-Kunden. Jeder Endpunkt akzeptiert entweder X-API-Key: swh_… (empfohlen für Server-zu-Server) oder Authorization: Bearer <jwt> (für interne Tools).

Tier-Gating

• Kostenlos — API-Zugriff verweigert (403 API_ACCESS_REQUIRED).
• Pro — 10-Aufrufe schreibgeschützter Test. Schreib-Endpunkte geben 403 business_required zurück.
• Business — 500 Aufrufe/Monat, Wallet-/Berechtigungsabzug pro Scan/Pentest/Breach.
• Enterprise — unbegrenzte Aufrufe; Admin-gesteuert mit einer kundenspezifischen max_domains-Obergrenze und Pro-Aufruf-Abrechnung (Details).

Typischer Reseller-Workflow

# 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

Geben Sie einen API-Schlüssel für den aktuellen Benutzer aus. Business: ein Schlüssel, 500 Aufrufe/Monat. Enterprise: ein Schlüssel, unbegrenzt (von Admin über /admin/api/v1/enterprise/* verwaltet). Nur Bearer JWT — Sie können Ihren ersten Schlüssel nicht mit sich selbst bootstrappen; die Dashboard-Anmeldung (oder Admin-Registrierung für Enterprise) ist der Einstiegspunkt.

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

Aktive Schlüssel + Nutzung des laufenden Monats auflisten. Klartext wird nie erneut angezeigt. Nur Bearer JWT — Key-Management-Endpunkte sind nicht mit einem API-Schlüssel erreichbar.

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

Widerrufen Sie den vorhandenen Schlüssel und geben Sie einen neuen aus. Der neue Klartext wird einmal in der Antwort angezeigt — der vorherige Schlüssel funktioniert sofort nicht mehr. Nur Bearer JWT.

DELETE /api/v1/keys/{key_id}

Einen Schlüssel widerrufen. Idempotent. Nur Bearer JWT.

GET /api/v1/domains

Listet die Domänen des Aufrufers auf. Paginiert; berücksichtigt ?limit und ?offset.

POST /api/v1/domains

Fügen Sie eine Domäne hinzu und initialisieren Sie atomisch die Orchestrator-Verifizierung. Gibt die DNS-TXT-Herausforderung inline zurück, sodass Sie diese ohne weiteren Anruf an Ihren Mandanten übermitteln können. Kostenlos für den Kunden — Domänenzusätze belasten das Wallet nicht.

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

Einzelne Domain-Details: risk_score, last_scanned_at, verified_at, country, etc. 404 bei Nichtübereinstimmung.

PATCH /api/v1/domains/{domain_id}

Schalten Sie auto_rescan_enabled für eine Domain um (das einzige derzeit änderbare Feld auf diesem Endpunkt). Das Aktivieren erfordert Pro-Tier oder höher (das daily_rescan Feature Gate); Deaktivieren ist immer erlaubt. Um industry, primary_contact oder country zu ändern, löschen und fügen Sie die Domain erneut hinzu.

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}

Domain endgültig löschen. Die Zeile, ihr Verifizierungsstatus und alle zugehörigen Job-Datensätze werden entfernt. Gibt einen Slot gegen das Tier-Limit frei. Kontingent +1.

POST /api/v1/domains/bulk-import

Mehrteil-Upload einer CSV-Datei — jede Zeile ist domain,country (country ist erforderlich, 2-stelliger ISO-Code). Die erste Zeile kann ein domain,country-Header sein — dieser wird übersprungen. Beachtet das kundenseitige Limit; Zeilen, die das Limit überschreiten, landen in der rejected-Liste mit Grund quota exceeded. Quota +1 pro Aufruf (nicht pro Zeile).

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

Zeitlich geordnete Liste früherer Scans + Überprüfungsunterschiede für eine Domain.

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

Schreibgeschützter Abruf des aktuellen Autorisierungsherausforderungsstatus vom Orchestrator (DNS + HTTP-Pfad + Datensatzwerte + Ablauf). Verwenden Sie dies, wenn Sie die Herausforderung nach Verlust der ursprünglichen POST /api/v1/domains-Antwort erneut anzeigen müssen.

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

Bitten Sie den Orchestrator, die Überprüfung tatsächlich auszuführen. method=dns (Standard) führt eine TXT-Abfrage durch; method=http ruft https://<Domain><http_path> auf und vergleicht mit 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

Übermitteln Sie einen Angriffsflächen-Scan an den Orchestrator. Keine Domain-Verifizierungsprüfung — jede hinzugefügte Domain ist berechtigt. Business: belastet Wallet/Entitlement pro service_prices.attack_surface. Enterprise: erfasst eine usage_events-Zeile mit effektivem Preis pro Kunde, kein Wallet-Zugriff. Quota +1 bei 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

Reichen Sie einen KI-Pentest ein. Das optionale rate_profile steuert die Scan-Intensität: stealth (3 rps) · regular (10 rps, Standard) · aggressive (25 rps). Alle anderen Parameter bleiben auf Orchestrator-Standardwerten. Gleiche Wallet-/Gebührenaufteilung wie /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

Starten Sie einen Darknet-Recherche-Job, der Darknet-Quellen auf Anmeldedaten, Hashes und PII abgleicht, die an diese Domain gebunden sind. Asynchron — gibt sofort eine job_id zurück; rufen Sie GET /api/v1/breach-intel/{job_id} ab, um Status und Ergebnisse zu überwachen. Typische End-to-End-Fertigstellung: 30–90 s. Domain muss verifiziert sein. Business: belastet Wallet/Berechtigung pro service_prices.breach_intel. Enterprise: schreibt eine usage_events-Zeile mit effektivem Kundenpreis, kein Wallet-Zugriff. Kontingent +1 bei akzeptierter Einreichung. Pro-Domain-Abkühlzeit: 7 Tage (Darknet-Fenster des Orchestrators).

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

Überwachen Sie einen Darknet-Recherche-Job. Eigentümerprüfung durchgeführt; kein Kontingent. Das Backend fragt den Orchestrator träge ab (5 s Drosselung), während die lokale Zeile noch running ist, sodass dieser Endpoint häufig aufgerufen werden kann, ohne den Upstream zu überlasten. Sobald der Job einen Endzustand erreicht (completed | failed | cancelled), geben nachfolgende Aufrufe die zwischengespeicherte Zeile zurück, ohne einen Orchestrator-Roundtrip zu durchlaufen.

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

Entschlüsseln Sie ein Klartextpasswort aus einem Darknet-Befund. Nur Eigentümer (mandantenübergreifende Versuche geben 404 zurück — Existenz-privat). Domain muss zum Zeitpunkt des Aufrufs vom Orchestrator verifiziert sein. Klartext wird inline zurückgegeben und ist NIEMALS in SwarmHawks DB persistent; jeder Aufrufe schreibt eine admin_audit_log-Zeile. Keine Kontingentkosten.

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

GET /api/v1/jobs/{job_id}

Job-Status-Proxy zum Orchestrator. Die job_id hier ist die vom Orchestrator zurückgegebene ID von POST /scan oder /pentest. Ownership wird serverseitig durchgesetzt — 404 bei Nichtübereinstimmung (Existence-Private). GET = keine Kontingentbelastung.

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

Strukturierte Findings-Liste (Schwachstellen, exponierte Services, schwache Konfigurationen, etc.). Wird zurückgegeben, sobald 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

Vollständiger JSON-Bericht (Zusammenfassung für die Geschäftsleitung + Ergebnisse + Empfehlungen). Verfügbar sobald 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

Derselbe Bericht als PDF gerendert (Binärstrom mit upstream Content-Disposition). Geeignet für direkte Weitergabe an Ihren Mandanten.

Enterprise-Stufe

Der Enterprise-Plan ist für Hosting-Provider, MSSPs und andere Reseller konzipiert, die SwarmHawk als White-Label-API für viele Mandanten betreiben. Die Anmeldung erfolgt durch Administratoren (kein Self-Service-Checkout) und wird vertraglich vereinbart — kontaktieren Sie den Vertrieb, um zu starten.

Was unterscheidet sich von Business

• Strikte Pro-Kunde-Domain-Obergrenze — Ihr Vertrag legt max_domains fest (z. B. 100, 500, 5000); der (N+1)-te POST /api/v1/domains gibt 403 tier_locked mit feature:"domains" und einen limit/current-Body zurück.
• Unbegrenzte API-Aufrufe — Ihr Schlüssel trägt limit_per_month: null; das monatliche Kontingent, das für Pro/Business gilt, wird umgangen.
• Pro-Aufruf-Abrechnung — jeder Scan, Pentest und Breach-Intel-Aufruf wird in einem unveränderlichen usage_events-Log mit dem effektiven kundenspezifischen Preis aufgezeichnet und ist über GET /api/v1/usage abrufbar. Pro-Service-Preise können von einem Administrator vertraglich überschrieben werden (andernfalls wird auf den globalen Tarif zurückgegriffen).
• Keine Geldbörse / kein Stripe — Enterprise-Abrechnung erfolgt außerhalb der Plattform in einem monatlichen Rechnungszyklus. Ihr Reseller-Wallet-Saldo ist irrelevant.
• Nur API — Enterprise-Kunden melden sich nicht am Dashboard an. Der Vertrieb übergibt Ihren Bearer Key außerhalb des Systems; alles Nachfolgende funktioniert mit X-API-Key: swh_….

Verfügbare Endpunkte

Enterprise-Kunden nutzen die bestehende Business /api/v1/* Oberfläche plus die neue GET /api/v1/usage:

• POST /api/v1/keys, GET /api/v1/keys — Zeigen Sie Ihre eigenen Schlüsselmetadaten an (der Klartextschlüssel wird nur einmal bei der Registrierung/Erneuerung angezeigt).
• POST /api/v1/domains — unterliegt der kundenspezifischen max_domains-Obergrenze.
• 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 — Nur für Enterprise (siehe unten).

GET /api/v1/usage

Pro-Domain-Nutzungsaggregate für einen Enterprise-Kunden in einem bestimmten monatlichen Abrechnungszeitraum. Verwenden Sie dies, um Ihre monatliche Rechnung abzustimmen oder um Ihre eigenen Mandanten pro Domain abzurechnen.

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

Deaktivierungsverhalten

Wenn Ihr Enterprise-Konto von einem Administrator pausiert wird (Zahlungsausfall, Vertragsende usw.), gibt jeder /api/v1/*-Aufruf — Lese- und Schreibvorgänge — folgende Antwort zurück:

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

Der API-Schlüssel wird nicht widerrufen (daher stellt die Reaktivierung den Zugriff wieder her, ohne Schlüssel neu auszustellen), und historische usage_events + domains bleiben erhalten. Kontaktieren Sie den Vertrieb zur Reaktivierung.

Python SDK

Das SwarmHawk Python SDK bietet Sicherheitsplattformen eine saubere programmatische Schnittstelle zum Abrufen von Findings, zur Konfiguration von Push-Integrationen und zum Verbrauch von STIX 2.1 Bundles — ohne rohes HTTP erforderlich.

SDK-Methoden

Integrations-API

Wenn aktiviert, konfigurieren Sie Push-Integrationen, damit SwarmHawk kritische Erkenntnisse automatisch an Ihre Security-Plattformen sendet, sobald sie erkannt werden (Risiko ≥ 70).

GET /integrationen

Listet alle konfigurierten Integrationen für den authentifizierten Benutzer auf. Secrets sind maskiert.

POST /integrationen/{service}

Integrationskonfiguration speichern oder aktualisieren. service ist einer von: splunk · sentinel · crowdstrike · gravityzone · cortex · jira · servicenow · webhook · stix

POST /integrations/{service}/test

Testen Sie die Konnektivität ohne zu speichern. Gibt {"ok": true, "message": "..."} zurück

DEL /integrationen/{service}

Integrationskonfiguration entfernen.

Unterstützte Dienste

STIX / TAXII 2.1

SwarmHawk stellt einen TAXII-2.1-konformen Endpoint bereit. Verbinden Sie jede Threat-Intelligence-Plattform (OpenCTI, MISP, ThreatConnect, Anomali), um SwarmHawk-Ergebnisse als STIX-2.1-Objekte abzurufen.

GET /taxii/collections/

TAXII-Erkennungsendpunkt — gibt Sammlungsmetadaten zurück.

GET /taxii/collections/swarmhawk/objects/

Gibt ein STIX 2.1-Bundle Ihrer Domänen mit hohem Risiko als domain-name-, vulnerability- und relationship-Objekte zurück.

Zurückgegebene STIX-Objekttypen

Alle Objekt-IDs sind deterministisch (UUID5) — dieselbe Domain erzeugt immer dieselbe STIX-ID über Bundle-Generierungen hinweg, was eine ordnungsgemäße Deduplizierung in nachgelagerten TIPs ermöglicht.

Adapter-Skripte

Eigenständige Python-Skripte für Plattformen, auf denen Sie einen geplanten Pull (cron / Lambda / Azure Function) dem Always-On-Push-Connector vorziehen. Jedes Skript ruft SwarmHawk-Warnungen ab und übermittelt sie in einem Durchlauf an die Zielplattform.

Splunk TA Adapter

Gibt sourcetype=swarmhawk:scan-Events mit CIM-kompatiblen Feldern aus: dest, vendor_product, category, severity.

Microsoft Sentinel Adapter

Daten landen in der benutzerdefinierten Tabelle SwarmHawk_CL. KQL-Beispiel: SwarmHawk_CL | where RiskScore_d >= 80 | sort by TimeGenerated desc

CrowdStrike Falcon Adapter

Pushed Domains als IOCs (type=domain) in Batches von 200. Aktion ist prevent für bestätigte Malware/Phishing, detect für CVE-Exposition.

Bitdefender GravityZone Adapter

Erstellt benutzerdefinierte Netzwerkregeln über createCustomRule. Aktion ist block für Malware/Phishing, report für CVE-Exposures.

Palo Alto Cortex XDR Adapter

Sendet externe Warnungen mit MITRE ATT&CK-Technik-Tags (T1566, T1190, T1046, T1557…). Batches zu je 100 pro API-Aufruf.

Jira-Adapter

Erstellt strukturierte ADF-Issues mit Risikozusammenfassung, CVE-Findings, Software-Stack, fehlgeschlagene Checks, Remediations-Punkte und NIS2-Label. Wird nur ausgelöst, wenn Risiko ≥ 70 UND CVSS ≥ min_cvss, um Ticket-Spam zu vermeiden.

ServiceNow-Adapter

Antwortobjekte

Objekt prüfen

Interpretation des Risiko-Scores

Namen überprüfen

Jeder Eintrag im checks[]-Array eines Scan-Berichts trägt eine check-Kennung. Die vollständige Liste der Kennungen, die der Scanner heute ausgibt (Quelle: backend/scanhawk_translator.py + backend/post_scan_processor.py):

Granulare Checks (z.B. tls_protocol, tls_cipher) werden im Dashboard unter übergeordneten Kategorien (TLS, DNS, Header, etc.) gruppiert. Der PDF-Report nutzt zusätzliche benutzerfreundliche Bezeichnungen (siehe backend/main.py:CHECK_LABELS), aber die JSON-Identifizierer oben sind die kanonische Attack Surface.

Live ausprobieren

Full interactive API explorer — execute real requests against the SwarmHawk API directly from your browser. Paste your API key into the Authorize button to unlock authenticated endpoints.