SPHIOR

SPHIOR · API-Referenz

Ein Endpoint. JSON rein, JSON raus.

Die SPHIOR Security API ermöglicht es, Code auf Schwachstellen zu scannen und deterministische Fix-Anleitungen an Ihren eigenen KI-Agenten zu übergeben — aus jeder Sprache oder Umgebung.

https://api.sphior.com|v1 (stable)|REST / JSON

API-Schlüssel erhalten API-Übersicht

Terminal

$ curl -X POST https://api.sphior.com/v1/scan \
  -H "Authorization: Bearer sk_live_..." \
  -d '{"code": "...", "language": "javascript"}'

// Response
{
  "findings": [
    { "type": "sql_injection",
      "severity": "critical",
      "cvss": 9.8 }
  ]
}

SPHIOR API

API-Referenz

Die SPHIOR Security API ermöglicht es, Code auf Schwachstellen zu scannen und deterministische Fix-Anleitungen an Ihren eigenen KI-Agenten zu übergeben — aus jeder Sprache oder Umgebung.

Authentifizierung

Alle Anfragen müssen Ihren API-Schlüssel im Authorization-Header als Bearer-Token enthalten.

bash

curl https://api.sphior.com/v1/scan \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json"

Geben Sie Ihren API-Schlüssel niemals in clientseitigem Code oder öffentlichen Repositories preis. Verwenden Sie Umgebungsvariablen oder einen Secrets-Manager.

API-Schlüssel generieren und verwalten in der API-Konsole. Maximal 5 aktive Schlüssel pro Konto.

POST/v1/scan

Code scannen

Analysiert einen Code-Ausschnitt auf Sicherheitslücken. Gibt Ergebnisse mit Schweregrad, CVSS-Score, Zeilennummer und Korrekturempfehlung zurück. Vollständig deterministisch (keine KI): derselbe Code liefert immer dieselben Ergebnisse — reproduzierbar und auditfähig.

Request-Body

Parameter	Typ	Beschreibung
coderequired	string	Der zu analysierende Quellcode. Max. Größe planabhängig (10KB–10MB).
languagerequired	string	Programmiersprache: javascript, typescript, python, go, java, ruby, php, sql
policy_id	string	Benutzerdefinierte Policy-ID (Business+ Pläne). Standard: OWASP-Regelsatz.

Beispiel-Request

bash

curl -X POST https://api.sphior.com/v1/scan \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "app.get(\"/user\", (req, res) => { db.query(\"SELECT * FROM users WHERE id=\" + req.query.id) })",
    "language": "javascript"
  }'

Beispiel-Response

json

{
  "scan_id": "scan_01j9x7z3k8q4b5c2d6e7f8g9h0",
  "status": "completed",
  "language": "javascript",
  "findings": [
    {
      "id": "find_001",
      "type": "sql_injection",
      "severity": "critical",
      "cvss": 9.8,
      "line": 2,
      "column": 11,
      "message": "Unsanitized user input passed directly to SQL query",
      "cwe": "CWE-89",
      "owasp": "A03:2021",
      "fix_hint": "Use parameterized queries: db.query('SELECT * FROM users WHERE id = ?', [req.query.id])"
    }
  ],
  "summary": {
    "critical": 1, "high": 0, "medium": 0, "low": 0, "info": 0
  },
  "ai_calls": 0,
  "cached": false,
  "latency_ms": 12
}

POST/v1/fix

Fix-Anleitung abrufen

Gibt für eine finding ID eines vorherigen Scans eine deterministische Fix-Anleitung zurück — warum es wichtig ist, Behebungsschritte, Ort und Anweisungen für Ihren KI-Agenten. SPHIOR schreibt keine Patches und überträgt Ihren Quellcode nicht; Ihre eigene KI (via MCP) wendet den Fix an.

Request-Body

Parameter	Typ	Beschreibung
scan_idrequired	string	Von einem vorherigen /v1/scan-Aufruf zurückgegebene ID.
finding_idrequired	string	Spezifischer Fund für den ein Fix generiert werden soll.
context	string	Zusätzlicher Code-Kontext (vollständige Datei empfohlen).

Beispiel-Response

json

{
  "fix_id": "fix_01j9x8a1b2c3d4e5f6g7h8i9j0",
  "scan_id": "scan_01j9x7z3k8q4b5c2d6e7f8g9h0",
  "finding_id": "find_001",
  "patched_code": null,
  "fix_context": {
    "finding_id": "find_001",
    "rule_id": "pattern.js.sql_concat",
    "severity": "critical",
    "cwe": "CWE-89",
    "owasp": "A03:2021",
    "why": "OS command / SQL injection: untrusted input reaches the query and can execute arbitrary statements.",
    "remediation_steps": [
      "Review the flagged code and identify the interpolated value.",
      "Use a parameterized query (e.g. WHERE id = ?) with bound parameters.",
      "Add a regression test covering the fixed behavior."
    ],
    "agent_instructions": "Open the file in your workspace and read the actual code yourself (it is NOT included here). Apply the remediation steps. A human must review your change before merge.",
    "data_boundary_note": "SPHIOR does not transmit your source code. This payload contains only finding metadata and deterministic remediation guidance."
  },
  "latency_ms": 9
}

GET/v1/rules

Regeln auflisten

Listet alle aktiven Sicherheitsregeln für Ihren Plan auf. Gibt Regel-ID, Kategorie, Schweregrad und unterstützte Sprachen zurück.

bash

curl https://api.sphior.com/v1/rules \
  -H "Authorization: Bearer sk_live_..." \
  -G -d "language=javascript" -d "severity=critical"

Query-Parameter

Parameter	Typ	Beschreibung
language	string	Nach Sprache filtern (z.B. python, go). Weglassen für alle.
severity	string	Nach Schweregrad filtern: critical, high, medium, low, info
category	string	Nach OWASP-Kategorie filtern: injection, auth, crypto

Webhooks

Registrieren Sie eine Webhook-URL in der API-Konsole, um Echtzeit-Events bei Scan-Abschluss oder kritischen Funden zu erhalten.

Event-Typen

scan.completed

Wird bei Scan-Abschluss ausgelöst. Enthält scan_id, Zusammenfassung und Anzahl.

scan.critical_found

Wird sofort bei einem kritischen Fund ausgelöst.

spend_cap.reached

Wird ausgelöst wenn monatliche Ausgaben das konfigurierte Cap erreichen.

spend_cap.warning

Wird bei 80% des Spend-Caps ausgelöst.

Webhook-Payloads werden mit HMAC-SHA256 signiert. Überprüfen Sie immer den X-SPHIOR-Signature-Header vor der Verarbeitung.

Fehlercodes

Die SPHIOR API verwendet Standard-HTTP-Statuscodes. Fehlerantworten sind JSON mit error- und code-Feldern.

Status	Code	Bedeutung
401	unauthenticated	API-Schlüssel fehlt oder ist ungültig.
403	forbidden	Schlüssel hat keine Berechtigung für diese Operation.
400	invalid_request	Fehlerhaftes JSON, fehlende Pflichtfelder oder nicht unterstützte Sprache.
413	payload_too_large	Code-Größe überschreitet Ihr Plan-Limit.
429	spend_cap_reached	Monatliches Spend-Cap erreicht. Nur Regel-Ergebnisse werden zurückgegeben.
429	rate_limited	Zu viele Anfragen pro Sekunde. Backoff und Retry.
500	internal_error	Unerwarteter Serverfehler. Retry mit exponentiellem Backoff.

json

// Error response shape
{
  "error": "Missing required field: language",
  "code": "invalid_request",
  "status": 400
}

SDKs

Offizielle SDKs sind für TypeScript/JavaScript und Python verfügbar. Beide wrappen die REST-API mit typisierten Antworten, automatischen Retries und Spend-Cap-Awareness.

TypeScript / Node.js

bash

npm install @sphior/sdk

typescript

import { SphiorClient } from "@sphior/sdk";

const sphior = new SphiorClient({ apiKey: process.env.SPHIOR_API_KEY });

const result = await sphior.scan({
  code: fs.readFileSync("./auth.ts", "utf8"),
  language: "typescript",
});

for (const finding of result.findings) {
  console.log(`${finding.severity.toUpperCase()}: ${finding.message} (line ${finding.line})`);
  console.log("Fix hint:", finding.fix_hint);
}

// Hand a finding to your own AI agent to fix (deterministic guidance, no code sent):
const guidance = await sphior.fix({ scan_id: result.scan_id, finding_id: result.findings[0].id });
console.log(guidance.fix_context.remediation_steps);

Python

bash

pip install sphior-sdk

python

from sphior import SphiorClient

client = SphiorClient(api_key=os.environ["SPHIOR_API_KEY"])

result = client.scan(
    code=open("app.py").read(),
    language="python",
)

for finding in result.findings:
    print(f"{finding.severity.upper()}: {finding.message} (line {finding.line})")
    print("Fix hint:", finding.fix_hint)

# Hand a finding to your own AI agent to fix (deterministic guidance, no code sent):
guidance = client.fix(scan_id=result.scan_id, finding_id=result.findings[0].id)
print(guidance.fix_context["remediation_steps"])

Preise

Die API berechnet eine einfache Plattformgebühr für den Zugang. Scannen und Fix-Anleitungen laufen auf einer vollständig deterministischen Engine — keine Gebühr pro KI-Aufruf. Pläne unterscheiden sich in Rate-Limits, Code-Größe und Support.

Plan	Platform fee	Scanning	Fix guidance
Free	$0/mo	Included	Included
Developer	$29/mo	Included	Included
Business	$99/mo	Included	Included
Enterprise	$299+/mo	Included	Included

Die deterministische Engine hält die Kosten stabil und vorhersehbar. Rate-Limits pro Sekunde und Code-Größen-Limits skalieren je nach Plan; konfigurieren Sie sie in der API-Konsole.

Vollständige Preisdetails API-Schlüssel erhalten