Riferimento API

CSD dispone di un’API dedicata in /api/shape/csd/ per la gestione di domini, script, mitigazione e monitoraggio. CSD può essere abilitato anche sugli HTTP Load Balancer tramite l’API di configurazione del load balancer.

Autenticazione

Tutte le chiamate API richiedono un token API. Generarne uno nella Console XC in Amministrazione → Credenziali → Credenziali API.

Configurare le variabili d’ambiente come descritto in Automazione API — Configurazione dell’ambiente:

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

Tutti gli esempi curl utilizzano il formato segnaposto xTOKENx. Sostituire con le proprie variabili d’ambiente o utilizzare il modulo interattivo nella parte superiore della pagina. Ad esempio, xF5XC_API_TOKENx corrisponde a $F5XC_API_TOKEN.

-H "Authorization: APIToken xF5XC_API_TOKENx"

Convenzioni API

Nota

Queste convenzioni si applicano a tutti gli endpoint di configurazione F5 Distributed Cloud (F5 XC) e CSD. Comprenderle evita errori comuni nell’automazione.

Corpo delle risposte

• POST restituisce l’oggetto creato come JSON.
• PUT e DELETE restituiscono un \{\} vuoto su HTTP 200 — questo è normale, non un errore. Non trattare un corpo di risposta vuoto come un fallimento.

Endpoint List vs GET

Gli endpoint list (ad es. /healthchecks, /origin_pools, /protected_domains) e i singoli endpoint GET (ad es. /healthchecks/\{name\}) restituiscono strutture di risposta differenti:

Tipo di endpoint	Percorso di esempio	Struttura della risposta
List	/origin_pools	Gli elementi hanno .name, .namespace, .tenant al livello superiore con metadata: null e get_spec: null
GET individuale	/origin_pools/\{name\}	L’oggetto ha .metadata.name, .spec.* con la configurazione completa

Utilizzare i percorsi jq corretti per ciascuno. Ad esempio, per estrarre i nomi da un endpoint list usare .items[].name, non .items[].metadata.name.

Identificatore del dominio protetto

Per le operazioni GET e DELETE sui domini protetti, il parametro di percorso \{name\} è il valore del dominio stesso (ad es. bankexample.com), non un nome oggetto arbitrario. Questo differisce dagli altri oggetti F5 XC in cui il nome è un identificatore scelto dall’utente.

Endpoint API CSD

Percorso base: /api/shape/csd/namespaces/\{namespace\}/

Stato e inizializzazione

Operazione	Metodo	Percorso
Abilita CSD	POST	/api/shape/csd/namespaces/system/init
Ottieni stato	GET	/api/shape/csd/namespaces/\{namespace\}/status
Ottieni configurazione JS	GET	/api/shape/csd/namespaces/\{namespace\}/js_configuration
Testa JS	POST	/api/shape/csd/namespaces/\{namespace\}/testjs
Aggiorna domini	POST	/api/shape/csd/namespaces/\{namespace\}/update_domains

Domini protetti

Operazione	Metodo	Percorso
Elenca	GET	/api/shape/csd/namespaces/\{namespace\}/protected_domains
Ottieni	GET	/api/shape/csd/namespaces/\{namespace\}/protected_domains/\{name\}
Crea	POST	/api/shape/csd/namespaces/\{namespace\}/protected_domains
Elimina	DELETE	/api/shape/csd/namespaces/\{namespace\}/protected_domains/\{name\}

Domini rilevati

Operazione	Metodo	Percorso
Elenca rilevati	GET	/api/shape/csd/namespaces/\{namespace\}/detected_domains
Ottieni dettagli	GET	/api/shape/csd/namespaces/\{namespace\}/domain_details

Domini consentiti

Operazione	Metodo	Percorso
Elenca	GET	/api/shape/csd/namespaces/\{namespace\}/allowed_domains
Ottieni	GET	/api/shape/csd/namespaces/\{namespace\}/allowed_domains/\{name\}
Crea	POST	/api/shape/csd/namespaces/\{namespace\}/allowed_domains
Elimina	DELETE	/api/shape/csd/namespaces/\{namespace\}/allowed_domains/\{name\}

Domini mitigati

Operazione	Metodo	Percorso
Elenca	GET	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains
Ottieni	GET	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains/\{name\}
Crea	POST	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains
Elimina	DELETE	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains/\{name\}

Script

Operazione	Metodo	Percorso
Elenca script	POST	/api/shape/csd/namespaces/\{namespace\}/scripts
Elenca script (legacy)	GET	/api/shape/csd/namespaces/\{namespace\}/scripts
Ottieni panoramica script	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/dashboard
Elenca comportamenti	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/behaviors
Elenca interazioni di rete	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/networkInteractions
Aggiorna giustificazione	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/justification
Elimina giustificazione	DELETE	/api/shape/csd/namespaces/\{namespace\}/script/justification/\{justification_id\}
Aggiorna stato di lettura	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/readStatus
Elenca utenti interessati	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/affectedUsers

Campi modulo

Operazione	Metodo	Percorso
Elenca campi modulo	GET	/api/shape/csd/namespaces/\{namespace\}/formFields
Elenca campi modulo (POST)	POST	/api/shape/csd/namespaces/\{namespace\}/formFields
Ottieni campo modulo	GET	/api/shape/csd/namespaces/\{namespace\}/formFields/\{id\}
Elenca per script	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/formFields
Aggiorna analisi campo	POST	/api/shape/csd/namespaces/\{namespace\}/formFields/analysis

Abilitare CSD

Inizializzare CSD per il 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"

Ottenere lo stato CSD

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

Domini protetti

Elencare i domini protetti

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

Aggiungere un dominio protetto

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 .

Eliminare un dominio protetto

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

Domini rilevati

Elencare i domini rilevati

Parametri di query: locations (filtra per posizione), risk (filtra per livello di rischio).

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

Filtra per rischio elevato:

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

Ottenere i dettagli del dominio

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

Script

Elencare tutti gli script

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 .

Ottenere la panoramica dello 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 .

Elencare i comportamenti dello script

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

Elencare le interazioni di rete

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

Mitigazione

Aggiungere un dominio mitigato

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 .

Elencare i domini mitigati

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

Rimuovere la mitigazione

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

Domini consentiti

Aggiungere un dominio consentito

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 .

Elencare i domini consentiti

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

Rimuovere un dominio consentito

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

Configurazione iniezione JS

Ottenere la configurazione corrente

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

Configurazione CSD su HTTP Load Balancer

L’iniezione JavaScript CSD può essere abilitata direttamente su un HTTP Load Balancer tramite l’API di configurazione in /api/config/namespaces/\{namespace\}/http_loadbalancers/\{name\}.

Il campo client_side_defense all’interno della specifica del load balancer controlla l’iniezione:

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

Il campo policy accetta uno dei seguenti valori:

Campo	Descrizione
js_insert_all_pages	Inietta su tutte le pagine
js_insert_all_pages_except	Inietta su tutte le pagine tranne le regole di esclusione
js_insertion_rules	Inietta solo sulle pagine corrispondenti alle regole
disable_js_insert	Non iniettare

Per disabilitare CSD su un load balancer, sostituire client_side_defense con disable_client_side_defense: \{\}.

Leggere la configurazione CSD dal Load Balancer

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'

Abilitare CSD su un Load Balancer

Recuperare, modificare e applicare:

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'

Corrispondenza di dominio e percorso per le regole di esclusione

Quando si utilizza js_insert_all_pages_except o js_insertion_rules, ogni regola corrisponde a una combinazione di dominio e percorso.

Dominio (sceglierne uno):

Campo	Esempio
any_domain: \{\}	Tutti i domini
domain.exact_value	"app.example.com"
domain.suffix_value	".example.com"
domain.regex_value	".*\\.example\\.com"

Percorso (sceglierne uno):

Campo	Esempio
path.path	"/login"
path.prefix	"/checkout"
path.regex	"/user/[0-9]+"

Riferimento API

• Riferimento API CSD — Documentazione completa degli endpoint
• Configurare CSD — Guida alla configurazione tramite Console
• Credenziali API — Generare token API