Référence API

CSD dispose d’une API dédiée à /api/shape/csd/ pour la gestion des domaines, des scripts, de la mitigation et de la surveillance. CSD peut également être activé sur les équilibreurs de charge HTTP via l’API de configuration des équilibreurs de charge.

Authentification

Tous les appels API nécessitent un jeton API. Générez-en un dans la console XC sous Administration → Credentials → API Credentials.

Configurez vos variables d’environnement comme décrit dans Automatisation API — Configuration de l’environnement :

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

Tous les exemples curl utilisent le format de substitution xTOKENx. Remplacez par vos variables d’environnement ou utilisez le formulaire interactif en haut de la page. Par exemple, xF5XC_API_TOKENx correspond à $F5XC_API_TOKEN.

-H "Authorization: APIToken xF5XC_API_TOKENx"

Conventions de l’API

Note

Ces conventions s’appliquent à tous les points de terminaison de configuration F5 Distributed Cloud (F5 XC) et de l’API CSD. Les comprendre permet d’éviter les erreurs courantes d’automatisation.

Corps des réponses

• POST renvoie l’objet créé au format JSON.
• PUT et DELETE renvoient un \{\} vide avec HTTP 200 — c’est normal, pas une erreur. Ne traitez pas un corps de réponse vide comme un échec.

Points de terminaison List vs GET

Les points de terminaison de liste (ex. /healthchecks, /origin_pools, /protected_domains) et les points de terminaison GET individuels (ex. /healthchecks/\{name\}) renvoient des structures de réponse différentes :

Type de point de terminaison	Exemple de chemin	Structure de réponse
List	/origin_pools	Les éléments ont .name, .namespace, .tenant au niveau supérieur avec metadata: null et get_spec: null
GET individuel	/origin_pools/\{name\}	L’objet possède .metadata.name, .spec.* avec la configuration complète

Utilisez les chemins jq appropriés pour chacun. Par exemple, pour extraire des noms d’un point de terminaison de liste, utilisez .items[].name et non .items[].metadata.name.

Identifiant de domaine protégé

Pour les opérations GET et DELETE sur les domaines protégés, le paramètre de chemin \{name\} est la valeur du domaine lui-même (ex. bankexample.com), et non un nom d’objet arbitraire. Cela diffère des autres objets F5 XC où le nom est un identifiant choisi par l’utilisateur.

Points de terminaison de l’API CSD

Chemin de base : /api/shape/csd/namespaces/\{namespace\}/

Statut et initialisation

Opération	Méthode	Chemin
Activer CSD	POST	/api/shape/csd/namespaces/system/init
Obtenir le statut	GET	/api/shape/csd/namespaces/\{namespace\}/status
Obtenir la configuration JS	GET	/api/shape/csd/namespaces/\{namespace\}/js_configuration
Tester JS	POST	/api/shape/csd/namespaces/\{namespace\}/testjs
Mettre à jour les domaines	POST	/api/shape/csd/namespaces/\{namespace\}/update_domains

Domaines protégés

Opération	Méthode	Chemin
Lister	GET	/api/shape/csd/namespaces/\{namespace\}/protected_domains
Obtenir	GET	/api/shape/csd/namespaces/\{namespace\}/protected_domains/\{name\}
Créer	POST	/api/shape/csd/namespaces/\{namespace\}/protected_domains
Supprimer	DELETE	/api/shape/csd/namespaces/\{namespace\}/protected_domains/\{name\}

Domaines détectés

Opération	Méthode	Chemin
Lister les détectés	GET	/api/shape/csd/namespaces/\{namespace\}/detected_domains
Obtenir les détails	GET	/api/shape/csd/namespaces/\{namespace\}/domain_details

Domaines autorisés

Opération	Méthode	Chemin
Lister	GET	/api/shape/csd/namespaces/\{namespace\}/allowed_domains
Obtenir	GET	/api/shape/csd/namespaces/\{namespace\}/allowed_domains/\{name\}
Créer	POST	/api/shape/csd/namespaces/\{namespace\}/allowed_domains
Supprimer	DELETE	/api/shape/csd/namespaces/\{namespace\}/allowed_domains/\{name\}

Domaines atténués

Opération	Méthode	Chemin
Lister	GET	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains
Obtenir	GET	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains/\{name\}
Créer	POST	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains
Supprimer	DELETE	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains/\{name\}

Scripts

Opération	Méthode	Chemin
Lister les scripts	POST	/api/shape/csd/namespaces/\{namespace\}/scripts
Lister les scripts (legacy)	GET	/api/shape/csd/namespaces/\{namespace\}/scripts
Obtenir la vue d’ensemble du script	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/dashboard
Lister les comportements	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/behaviors
Lister les interactions réseau	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/networkInteractions
Mettre à jour la justification	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/justification
Supprimer la justification	DELETE	/api/shape/csd/namespaces/\{namespace\}/script/justification/\{justification_id\}
Mettre à jour le statut de lecture	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/readStatus
Lister les utilisateurs affectés	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/affectedUsers

Champs de formulaire

Opération	Méthode	Chemin
Lister les champs de formulaire	GET	/api/shape/csd/namespaces/\{namespace\}/formFields
Lister les champs de formulaire (POST)	POST	/api/shape/csd/namespaces/\{namespace\}/formFields
Obtenir un champ de formulaire	GET	/api/shape/csd/namespaces/\{namespace\}/formFields/\{id\}
Lister par script	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/formFields
Mettre à jour l’analyse du champ	POST	/api/shape/csd/namespaces/\{namespace\}/formFields/analysis

Activer CSD

Initialiser CSD pour le tenant :

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

Obtenir le statut CSD

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

Domaines protégés

Lister les domaines protégés

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

Ajouter un domaine protégé

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 .

Supprimer un domaine protégé

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

Domaines détectés

Lister les domaines détectés

Paramètres de requête : locations (filtrer par localisation), risk (filtrer par niveau de risque).

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

Filtrer par risque élevé :

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

Obtenir les détails d’un domaine

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

Scripts

Lister tous les scripts

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 .

Obtenir la vue d’ensemble d’un script

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 .

Lister les comportements d’un script

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

Lister les interactions réseau

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

Mitigation

Ajouter un domaine atténué

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 .

Lister les domaines atténués

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

Supprimer une mitigation

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

Domaines autorisés

Ajouter un domaine autorisé

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 .

Lister les domaines autorisés

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

Supprimer un domaine autorisé

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

Configuration d’injection JS

Obtenir la configuration actuelle

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

Configuration CSD sur l’équilibreur de charge HTTP

L’injection JavaScript CSD peut également être activée directement sur un équilibreur de charge HTTP via l’API de configuration à /api/config/namespaces/\{namespace\}/http_loadbalancers/\{name\}.

Le champ client_side_defense dans la spécification de l’équilibreur de charge contrôle l’injection :

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

Le champ policy accepte l’une des valeurs suivantes :

Champ	Description
js_insert_all_pages	Injecter sur toutes les pages
js_insert_all_pages_except	Injecter sur toutes les pages sauf les règles d’exclusion
js_insertion_rules	Injecter uniquement sur les pages correspondant aux règles
disable_js_insert	Ne pas injecter

Pour désactiver CSD sur un équilibreur de charge, remplacez client_side_defense par disable_client_side_defense: \{\}.

Lire la configuration CSD depuis l’équilibreur de charge

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'

Activer CSD sur un équilibreur de charge

Récupérer, modifier et appliquer :

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'

Correspondance de domaine et de chemin pour les règles d’exclusion

Lors de l’utilisation de js_insert_all_pages_except ou js_insertion_rules, chaque règle correspond à une combinaison domaine et chemin.

Domaine (choisir l’un) :

Champ	Exemple
any_domain: \{\}	Tous les domaines
domain.exact_value	"app.example.com"
domain.suffix_value	".example.com"
domain.regex_value	".*\\.example\\.com"

Chemin (choisir l’un) :

Champ	Exemple
path.path	"/login"
path.prefix	"/checkout"
path.regex	"/user/[0-9]+"

Référence API

• Référence API CSD — Documentation complète des points de terminaison
• Configurer CSD — Guide de configuration via la console
• Identifiants API — Générer des jetons API