Zum Hauptinhalt springen

ServiceNow

fremforge kann für jedes Sicherheitsereignis einen ServiceNow-Incident öffnen: einen neuen kritischen oder hohen Befund, einen Malware-Treffer, einen blockierten Pull, einen Richtlinienverstoß oder eine abgelaufene Risikoakzeptanz. Das Ziel sendet direkt an die Table API (POST /api/now/table/incident), sodass ServiceNow nur einen Integrationsbenutzer braucht und weder eine Scripted REST API noch einen MID-Server.

1. ServiceNow-Seite: ein Integrationsbenutzer

  1. Lege einen Benutzer für fremforge an, zum Beispiel fremforge.integration. Setze den Haken bei Web service access only.
  2. Gib ihm eine Rolle, die über die Table API Incidents anlegen darf, typischerweise itil, oder eine engere benutzerdefinierte Rolle mit create auf incident.
  3. Wähle, wie sich fremforge authentifiziert:
    • Basic: Name und Passwort des Benutzers, gesendet als Authorization: Basic <base64 of user:password>.
    • OAuth bearer: ein OAuth-Token für diesen Benutzer, gesendet als Authorization: Bearer <token>. Ein OAuth-Zugriffstoken von ServiceNow läuft ab, ein ablaufendes Token muss also am Ziel ersetzt werden, bevor es abläuft. Für einen Maschinenbenutzer ist Basic die einfachere Wahl.
  4. Optional: Notiere dir die sys_id der Zuweisungsgruppe, die die Incidents erhalten soll, und die des Anrufers, der eingetragen werden soll.

ServiceNow muss Anfragen von der ausgehenden Adresse von fremforge annehmen. Schränkt deine Instanz die Quell-IPs ein, frag den Support nach der aktuellen Adresse.

2. fremforge-Seite: ein Ziel im ServiceNow-Format

Mit der API (Scope webhooks:write):

AUTH="Basic $(printf '%s' 'fremforge.integration:<password>' | base64)"

curl -sS -X POST "https://frem.sh/_app/api/v1/orgs/acme/webhooks/destinations" \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "name": "ServiceNow incidents",
  "target_url": "https://acme.service-now.com/api/now/table/incident",
  "events": ["security.finding.created", "security.malware.matched",
             "security.pull.blocked", "security.policy.violation",
             "security.exception.expired"],
  "payload_format": "servicenow",
  "security_min_severity": "critical",
  "security_hourly_cap": 50,
  "servicenow": { "assignment_group": "<sys_id>", "category": "security" },
  "auth_header": { "name": "Authorization", "value": "$AUTH" }
}
EOF

Der Wert von auth_header wird verschlüsselt gespeichert und nie wieder angezeigt. Die Antwort enthält "auth_header_set": true. Um das Passwort zu ersetzen, sende einen PATCH mit einem neuen auth_header.

Sende dann einen Test-Incident und lies sein Ergebnis:

curl -sS -X POST "https://frem.sh/_app/api/v1/orgs/acme/webhooks/destinations/$ID/test" \
  -H "Authorization: Bearer $FREMFORGE_TOKEN"
curl -sS "https://frem.sh/_app/api/v1/orgs/acme/webhooks/deliveries?destination_id=$ID&limit=1" \
  -H "Authorization: Bearer $FREMFORGE_TOKEN"

Ein 201 in response_status bedeutet, dass ServiceNow den Incident angelegt hat. Ein 401 bedeutet, dass die Zugangsdaten falsch sind. Ein 403 bedeutet, dass dem Benutzer die Rolle zum Anlegen von Incidents fehlt.

Was der Incident enthält

Incident-FeldWert
short_description[fremforge] und der Titel des Ereignisses, zum Beispiel [fremforge] CVE-2026-12345 in lodash 4.17.20 (höchstens 160 Zeichen)
descriptionName des Ereignisses, Organisation, Repository, Schweregrad, Zeitpunkt, Korrelationsschlüssel, ein Link zur fremforge-Konsole und die Details des Ereignisses als JSON
urgency, impact1 bei kritisch, 2 bei hoch, sonst 3
correlation_idfremforge: gefolgt vom Korrelationsschlüssel des Befunds. Ein Schlüssel, der für das Feld zu lang ist, wird durch einen stabilen SHA-256-Hash davon ersetzt
correlation_displayfremforge
assignment_group, caller_id, category, subcategoryNur wenn am Ziel gesetzt (Objekt servicenow)

ServiceNow berechnet die Priorität des Incidents wie üblich aus Dringlichkeit und Auswirkung.

Jedes Ereignis legt einen neuen Incident an. Die Table API aktualisiert keinen vorhandenen Datensatz. Ereignisse zum selben Befund tragen dieselbe correlation_id, zum Beispiel ein Befund und später der Ablauf einer Risikoakzeptanz dazu. Nutze diesen Wert in einer Business Rule oder einem Listenfilter von ServiceNow, um sie zu gruppieren. Die Obergrenze pro Stunde begrenzt, wie viele Incidents ein Ziel pro Stunde öffnen kann. Ist sie erreicht, folgt nach Ablauf der Stunde ein zusammenfassender Incident.

Die Anfrage ist außerdem signiert (X-Fremforge-Signature). Die Table API ignoriert die Signatur; die Anfrage wird über den Auth-Header authentifiziert.

Alternative: eigene Logik in einer Scripted REST API

Willst du einen vorhandenen Incident aktualisieren, statt einen neuen anzulegen, oder Felder anders zuordnen, belasse das Format des Ziels auf Generic und richte es auf eine Ressource einer Scripted REST API. Das Skript erhält den generischen Body. Suche über correlation_id nach einem offenen Incident und aktualisiere ihn, oder lege einen neuen an. Um die Signatur im Skript zu prüfen, berechne HMAC-SHA256 über <X-Fremforge-Timestamp>.<raw body> mit dem Signatur-Secret des Ziels und vergleiche das Ergebnis mit dem v1-Teil von X-Fremforge-Signature. Schütze die Ressource mit demselben Integrationsbenutzer und dem auth_header.

Verwandte Themen

Plane