API-Referenz

CSD verfügt über eine dedizierte API unter /api/shape/csd/ zur Verwaltung von Domänen, Skripten, Abwehrmaßnahmen und Überwachung. CSD kann auch über die Load-Balancer-Konfigurations-API auf HTTP-Load-Balancern aktiviert werden.

Authentifizierung

Alle API-Aufrufe erfordern ein API-Token. Generieren Sie eines in der XC Konsole unter Verwaltung → Credentials → API Credentials.

Richten Sie Ihre Umgebungsvariablen wie unter API-Automatisierung — Umgebungseinrichtung beschrieben ein:

set -a && source .env && set +a

Alle curl-Beispiele verwenden das Platzhalterformat xTOKENx. Ersetzen Sie dieses durch Ihre Umgebungsvariablen oder verwenden Sie das interaktive Formular oben auf der Seite. Beispielsweise entspricht xF5XC_API_TOKENx dem Wert $F5XC_API_TOKEN.

-H "Authorization: APIToken xF5XC_API_TOKENx"

API-Konventionen

Hinweis

Diese Konventionen gelten für alle F5 Distributed Cloud (F5 XC)-Konfigurations- und CSD-API-Endpunkte. Das Verständnis dieser Konventionen verhindert häufige Automatisierungsfehler.

Antworttexte

• POST gibt das erstellte Objekt als JSON zurück.
• PUT und DELETE geben bei HTTP 200 ein leeres \{\} zurück – dies ist normal und kein Fehler. Behandeln Sie einen leeren Antworttext nicht als Fehler.

Listen- vs. GET-Endpunkte

Listen-Endpunkte (z. B. /healthchecks, /origin_pools, /protected_domains) und individuelle GET-Endpunkte (z. B. /healthchecks/\{name\}) geben unterschiedliche Antwortstrukturen zurück:

Endpunkttyp	Beispielpfad	Antwortstruktur
Liste	/origin_pools	Einträge haben .name, .namespace, .tenant auf oberster Ebene mit metadata: null und get_spec: null
Individueller GET	/origin_pools/\{name\}	Objekt hat .metadata.name, .spec.* mit vollständiger Konfiguration

Verwenden Sie die korrekten jq-Pfade für jeden Fall. Um beispielsweise Namen aus einem Listen-Endpunkt zu extrahieren, verwenden Sie .items[].name und nicht .items[].metadata.name.

Bezeichner für geschützte Domänen

Bei GET- und DELETE-Operationen für geschützte Domänen ist der \{name\}-Pfadparameter der Domänenwert selbst (z. B. bankexample.com) und kein beliebig gewählter Objektname. Dies unterscheidet sich von anderen F5 XC-Objekten, bei denen der Name ein benutzerdefinierter Bezeichner ist.

CSD-API-Endpunkte

Basispfad: /api/shape/csd/namespaces/\{namespace\}/

Status und Initialisierung

Vorgang	Methode	Pfad
CSD aktivieren	POST	/api/shape/csd/namespaces/system/init
Status abrufen	GET	/api/shape/csd/namespaces/\{namespace\}/status
JS-Konfiguration abrufen	GET	/api/shape/csd/namespaces/\{namespace\}/js_configuration
JS testen	POST	/api/shape/csd/namespaces/\{namespace\}/testjs
Domänen aktualisieren	POST	/api/shape/csd/namespaces/\{namespace\}/update_domains

Geschützte Domänen

Vorgang	Methode	Pfad
Auflisten	GET	/api/shape/csd/namespaces/\{namespace\}/protected_domains
Abrufen	GET	/api/shape/csd/namespaces/\{namespace\}/protected_domains/\{name\}
Erstellen	POST	/api/shape/csd/namespaces/\{namespace\}/protected_domains
Löschen	DELETE	/api/shape/csd/namespaces/\{namespace\}/protected_domains/\{name\}

Erkannte Domänen

Vorgang	Methode	Pfad
Erkannte auflisten	GET	/api/shape/csd/namespaces/\{namespace\}/detected_domains
Details abrufen	GET	/api/shape/csd/namespaces/\{namespace\}/domain_details

Erlaubte Domänen

Vorgang	Methode	Pfad
Auflisten	GET	/api/shape/csd/namespaces/\{namespace\}/allowed_domains
Abrufen	GET	/api/shape/csd/namespaces/\{namespace\}/allowed_domains/\{name\}
Erstellen	POST	/api/shape/csd/namespaces/\{namespace\}/allowed_domains
Löschen	DELETE	/api/shape/csd/namespaces/\{namespace\}/allowed_domains/\{name\}

Abgewehrte Domänen

Vorgang	Methode	Pfad
Auflisten	GET	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains
Abrufen	GET	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains/\{name\}
Erstellen	POST	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains
Löschen	DELETE	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains/\{name\}

Skripte

Vorgang	Methode	Pfad
Skripte auflisten	POST	/api/shape/csd/namespaces/\{namespace\}/scripts
Skripte auflisten (Legacy)	GET	/api/shape/csd/namespaces/\{namespace\}/scripts
Skriptübersicht abrufen	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/dashboard
Verhalten auflisten	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/behaviors
Netzwerkinteraktionen auflisten	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/networkInteractions
Begründung aktualisieren	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/justification
Begründung löschen	DELETE	/api/shape/csd/namespaces/\{namespace\}/script/justification/\{justification_id\}
Lesestatus aktualisieren	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/readStatus
Betroffene Benutzer auflisten	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/affectedUsers

Formularfelder

Vorgang	Methode	Pfad
Formularfelder auflisten	GET	/api/shape/csd/namespaces/\{namespace\}/formFields
Formularfelder auflisten (POST)	POST	/api/shape/csd/namespaces/\{namespace\}/formFields
Formularfeld abrufen	GET	/api/shape/csd/namespaces/\{namespace\}/formFields/\{id\}
Nach Skript auflisten	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/formFields
Feldanalyse aktualisieren	POST	/api/shape/csd/namespaces/\{namespace\}/formFields/analysis

CSD aktivieren

CSD für den Mandanten initialisieren:

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/system/init"

CSD-Status abrufen

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/status" \
  | jq .

Geschützte Domänen

Geschützte Domänen auflisten

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/protected_domains" \
  | jq .

Eine geschützte Domäne hinzufügen

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "my-app",
      "namespace": "xF5XC_NAMESPACEx"
    },
    "spec": {}
  }' \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/protected_domains" \
  | jq .

Eine geschützte Domäne löschen

curl -s -X DELETE \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/protected_domains/my-app"

Erkannte Domänen

Erkannte Domänen auflisten

Abfrageparameter: locations (nach Standort filtern), risk (nach Risikostufe filtern).

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/detected_domains" \
  | jq .

Nach hohem Risiko filtern:

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/detected_domains?risk=high" \
  | jq .

Domänendetails abrufen

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/domain_details?name=suspicious.example.com" \
  | jq .

Skripte

Alle Skripte auflisten

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/scripts" \
  | jq .

Skriptübersicht abrufen

SCRIPT_ID="your-script-id"

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/scripts/${SCRIPT_ID}/dashboard" \
  | jq .

Skriptverhalten auflisten

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/scripts/${SCRIPT_ID}/behaviors" \
  | jq .

Netzwerkinteraktionen auflisten

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/scripts/${SCRIPT_ID}/networkInteractions" \
  | jq .

Abwehr

Eine abgewehrte Domäne hinzufügen

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "blocked-domain",
      "namespace": "xF5XC_NAMESPACEx"
    },
    "spec": {}
  }' \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/mitigated_domains" \
  | jq .

Abgewehrte Domänen auflisten

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/mitigated_domains" \
  | jq .

Abwehr aufheben

curl -s -X DELETE \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/mitigated_domains/blocked-domain"

Erlaubte Domänen

Eine erlaubte Domäne hinzufügen

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "trusted-cdn",
      "namespace": "xF5XC_NAMESPACEx"
    },
    "spec": {}
  }' \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/allowed_domains" \
  | jq .

Erlaubte Domänen auflisten

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/allowed_domains" \
  | jq .

Eine erlaubte Domäne entfernen

curl -s -X DELETE \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/allowed_domains/trusted-cdn"

JS-Injektionskonfiguration

Aktuelle Konfiguration abrufen

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/js_configuration" \
  | jq .

HTTP-Load-Balancer-CSD-Konfiguration

Die CSD-JavaScript-Injektion kann auch direkt auf einem HTTP-Load-Balancer über die Konfigurations-API unter /api/config/namespaces/\{namespace\}/http_loadbalancers/\{name\} aktiviert werden.

Das Feld client_side_defense innerhalb der Load-Balancer-Spezifikation steuert die Injektion:

{
  "client_side_defense": {
    "policy": {
      "js_insert_all_pages": {}
    }
  }
}

Das Feld policy akzeptiert einen der folgenden Werte:

Feld	Beschreibung
js_insert_all_pages	Auf allen Seiten injizieren
js_insert_all_pages_except	Auf allen Seiten außer den Ausschlussregeln injizieren
js_insertion_rules	Nur auf Seiten injizieren, die den Regeln entsprechen
disable_js_insert	Nicht injizieren

Um CSD auf einem Load Balancer zu deaktivieren, ersetzen Sie client_side_defense durch disable_client_side_defense: \{\}.

CSD-Konfiguration vom Load Balancer lesen

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/config/namespaces/xF5XC_NAMESPACEx/http_loadbalancers/xF5XC_LB_NAMEx" \
  | jq '.spec.client_side_defense'

CSD auf einem Load Balancer aktivieren

Abrufen, ändern und anwenden:

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/config/namespaces/xF5XC_NAMESPACEx/http_loadbalancers/xF5XC_LB_NAMEx" \
  > lb-config.json

jq '.spec |= (
  del(.disable_client_side_defense) |
  .client_side_defense = {
    "policy": {
      "js_insert_all_pages": {}
    }
  }
)' lb-config.json > lb-config-updated.json

curl -s -X PUT \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d @lb-config-updated.json \
  "xF5XC_API_URLx/api/config/namespaces/xF5XC_NAMESPACEx/http_loadbalancers/xF5XC_LB_NAMEx" \
  | jq '.spec.client_side_defense'

Domänen- und Pfadabgleich für Ausschlussregeln

Bei der Verwendung von js_insert_all_pages_except oder js_insertion_rules gleicht jede Regel eine Kombination aus Domäne und Pfad ab.

Domäne (eine auswählen):

Feld	Beispiel
any_domain: \{\}	Alle Domänen
domain.exact_value	"app.example.com"
domain.suffix_value	".example.com"
domain.regex_value	".*\\.example\\.com"

Pfad (einen auswählen):

Feld	Beispiel
path.path	"/login"
path.prefix	"/checkout"
path.regex	"/user/[0-9]+"

API-Referenz

• CSD-API-Referenz — Vollständige Endpunktdokumentation
• CSD konfigurieren — Konfigurationsleitfaden für die Konsole
• API-Anmeldeinformationen — API-Token generieren