Referencia de API

CSD dispone de una API dedicada en /api/shape/csd/ para gestionar dominios, scripts, mitigación y supervisión. CSD también puede habilitarse en balanceadores de carga HTTP mediante la API de configuración del balanceador de carga.

Autenticación

Todas las llamadas a la API requieren un token de API. Genere uno en la F5 XC Consola en Administración → Credenciales → Credenciales de API.

Configure sus variables de entorno tal como se describe en Automatización de API — Configuración del entorno:

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

Todos los ejemplos de curl utilizan el formato de marcador de posición xTOKENx. Sustitúyalo con sus variables de entorno o utilice el formulario interactivo en la parte superior de la página. Por ejemplo, xF5XC_API_TOKENx corresponde a $F5XC_API_TOKEN.

-H "Authorization: APIToken xF5XC_API_TOKENx"

Convenciones de la API

Nota

Estas convenciones se aplican a todos los endpoints de configuración de F5 Distributed Cloud (F5 XC) y de la API de CSD. Comprenderlas evita errores comunes de automatización.

Cuerpos de respuesta

• POST devuelve el objeto creado como JSON.
• PUT y DELETE devuelven un \{\} vacío con HTTP 200 — esto es normal, no un error. No interprete un cuerpo de respuesta vacío como un fallo.

Endpoints de lista vs. GET individual

Los endpoints de lista (p. ej., /healthchecks, /origin_pools, /protected_domains) y los endpoints GET individuales (p. ej., /healthchecks/\{name\}) devuelven estructuras de respuesta diferentes:

Tipo de endpoint	Ruta de ejemplo	Estructura de respuesta
Lista	/origin_pools	Los elementos tienen .name, .namespace, .tenant en el nivel superior con metadata: null y get_spec: null
GET individual	/origin_pools/\{name\}	El objeto tiene .metadata.name, .spec.* con la configuración completa

Utilice las rutas jq correctas para cada caso. Por ejemplo, para extraer nombres de un endpoint de lista use .items[].name, no .items[].metadata.name.

Identificador de dominio protegido

Para las operaciones GET y DELETE de dominios protegidos, el parámetro de ruta \{name\} es el valor del dominio en sí (p. ej., bankexample.com), no un nombre de objeto arbitrario. Esto difiere de otros objetos de F5 XC donde el nombre es un identificador elegido por el usuario.

Endpoints de la API de CSD

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

Estado e Inicialización

Operación	Método	Ruta
Habilitar CSD	POST	/api/shape/csd/namespaces/system/init
Obtener estado	GET	/api/shape/csd/namespaces/\{namespace\}/status
Obtener configuración JS	GET	/api/shape/csd/namespaces/\{namespace\}/js_configuration
Probar JS	POST	/api/shape/csd/namespaces/\{namespace\}/testjs
Actualizar dominios	POST	/api/shape/csd/namespaces/\{namespace\}/update_domains

Dominios protegidos

Operación	Método	Ruta
Listar	GET	/api/shape/csd/namespaces/\{namespace\}/protected_domains
Obtener	GET	/api/shape/csd/namespaces/\{namespace\}/protected_domains/\{name\}
Crear	POST	/api/shape/csd/namespaces/\{namespace\}/protected_domains
Eliminar	DELETE	/api/shape/csd/namespaces/\{namespace\}/protected_domains/\{name\}

Dominios detectados

Operación	Método	Ruta
Listar detectados	GET	/api/shape/csd/namespaces/\{namespace\}/detected_domains
Obtener detalles	GET	/api/shape/csd/namespaces/\{namespace\}/domain_details

Dominios permitidos

Operación	Método	Ruta
Listar	GET	/api/shape/csd/namespaces/\{namespace\}/allowed_domains
Obtener	GET	/api/shape/csd/namespaces/\{namespace\}/allowed_domains/\{name\}
Crear	POST	/api/shape/csd/namespaces/\{namespace\}/allowed_domains
Eliminar	DELETE	/api/shape/csd/namespaces/\{namespace\}/allowed_domains/\{name\}

Dominios mitigados

Operación	Método	Ruta
Listar	GET	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains
Obtener	GET	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains/\{name\}
Crear	POST	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains
Eliminar	DELETE	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains/\{name\}

Scripts

Operación	Método	Ruta
Listar scripts	POST	/api/shape/csd/namespaces/\{namespace\}/scripts
Listar scripts (heredado)	GET	/api/shape/csd/namespaces/\{namespace\}/scripts
Obtener resumen del script	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/dashboard
Listar comportamientos	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/behaviors
Listar interacciones de red	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/networkInteractions
Actualizar justificación	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/justification
Eliminar justificación	DELETE	/api/shape/csd/namespaces/\{namespace\}/script/justification/\{justification_id\}
Actualizar estado de lectura	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/readStatus
Listar usuarios afectados	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/affectedUsers

Campos de formulario

Operación	Método	Ruta
Listar campos de formulario	GET	/api/shape/csd/namespaces/\{namespace\}/formFields
Listar campos de formulario (POST)	POST	/api/shape/csd/namespaces/\{namespace\}/formFields
Obtener campo de formulario	GET	/api/shape/csd/namespaces/\{namespace\}/formFields/\{id\}
Listar por script	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/formFields
Actualizar análisis de campo	POST	/api/shape/csd/namespaces/\{namespace\}/formFields/analysis

Habilitar CSD

Inicialice CSD para el 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"

Obtener el estado de CSD

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

Dominios protegidos

Listar dominios protegidos

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

Agregar un dominio protegido

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 .

Eliminar un dominio protegido

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

Dominios detectados

Listar dominios detectados

Parámetros de consulta: locations (filtrar por ubicación), risk (filtrar por nivel de riesgo).

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

Filtrar por riesgo alto:

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

Obtener detalles 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 .

Scripts

Listar todos los 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 .

Obtener resumen del 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 .

Listar comportamientos del script

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

Listar interacciones de red

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

Mitigación

Agregar un dominio mitigado

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 .

Listar dominios mitigados

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

Eliminar una mitigación

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

Dominios permitidos

Agregar un dominio permitido

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 .

Listar dominios permitidos

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

Eliminar un dominio permitido

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

Configuración de inyección de JS

Obtener la configuración actual

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

Configuración de CSD en el balanceador de carga HTTP

La inyección de JavaScript de CSD también puede habilitarse directamente en un balanceador de carga HTTP mediante la API de configuración en /api/config/namespaces/\{namespace\}/http_loadbalancers/\{name\}.

El campo client_side_defense dentro del spec del balanceador de carga controla la inyección:

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

El campo policy acepta uno de los siguientes:

Campo	Descripción
js_insert_all_pages	Inyectar en todas las páginas
js_insert_all_pages_except	Inyectar en todas las páginas excepto las indicadas en las reglas de exclusión
js_insertion_rules	Inyectar solo en las páginas que coincidan con las reglas
disable_js_insert	No inyectar

Para deshabilitar CSD en un balanceador de carga, reemplace client_side_defense con disable_client_side_defense: \{\}.

Leer la configuración de CSD desde el balanceador de carga

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'

Habilitar CSD en un balanceador de carga

Recupere, modifique y aplique:

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'

Coincidencia de dominio y ruta para reglas de exclusión

Al utilizar js_insert_all_pages_except o js_insertion_rules, cada regla coincide con una combinación de dominio y ruta.

Dominio (elija uno):

Campo	Ejemplo
any_domain: \{\}	Todos los dominios
domain.exact_value	"app.example.com"
domain.suffix_value	".example.com"
domain.regex_value	".*\\.example\\.com"

Ruta (elija una):

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

Referencia de API

• Referencia de la API de CSD — Documentación completa de endpoints
• Configurar CSD — Guía de configuración en la consola
• Credenciales de API — Generar tokens de API