Referência da API

O CSD possui uma API dedicada em /api/shape/csd/ para gerenciamento de domínios, scripts, mitigação e monitoramento. O CSD também pode ser habilitado em Balanceadores de Carga HTTP por meio da API de configuração do balanceador de carga.

Autenticação

Todas as chamadas de API requerem um token de API. Gere um no Console XC em Administration → Credentials → API Credentials.

Configure suas variáveis de ambiente conforme descrito em Automação de API — Configuração do Ambiente:

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

Todos os exemplos com curl utilizam o formato de placeholder xTOKENx. Substitua pelas suas variáveis de ambiente ou utilize o formulário interativo no topo da página. Por exemplo, xF5XC_API_TOKENx corresponde a $F5XC_API_TOKEN.

-H "Authorization: APIToken xF5XC_API_TOKENx"

Convenções da API

Nota

Essas convenções se aplicam a todos os endpoints de configuração do F5 Distributed Cloud (F5 XC) e da API CSD. Compreendê-las evita erros comuns de automação.

Corpos de Resposta

• POST retorna o objeto criado como JSON.
• PUT e DELETE retornam um \{\} vazio no HTTP 200 — isso é normal, não é um erro. Não trate um corpo de resposta vazio como falha.

Endpoints de Lista vs. GET

Endpoints de lista (p. ex., /healthchecks, /origin_pools, /protected_domains) e endpoints GET individuais (p. ex., /healthchecks/\{name\}) retornam estruturas de resposta diferentes:

Tipo de endpoint	Exemplo de caminho	Estrutura da resposta
Lista	/origin_pools	Itens possuem .name, .namespace, .tenant no nível superior, com metadata: null e get_spec: null
GET individual	/origin_pools/\{name\}	O objeto possui .metadata.name, .spec.* com a configuração completa

Utilize os caminhos jq corretos para cada caso. Por exemplo, para extrair nomes de um endpoint de lista, use .items[].name, não .items[].metadata.name.

Identificador de Domínio Protegido

Para operações GET e DELETE de domínios protegidos, o parâmetro de caminho \{name\} é o próprio valor do domínio (p. ex., bankexample.com), e não um nome de objeto arbitrário. Isso difere de outros objetos F5 XC, nos quais o nome é um identificador escolhido pelo usuário.

Endpoints da API CSD

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

Status e Inicialização

Operação	Método	Caminho
Habilitar CSD	POST	/api/shape/csd/namespaces/system/init
Obter Status	GET	/api/shape/csd/namespaces/\{namespace\}/status
Obter Configuração JS	GET	/api/shape/csd/namespaces/\{namespace\}/js_configuration
Testar JS	POST	/api/shape/csd/namespaces/\{namespace\}/testjs
Atualizar Domínios	POST	/api/shape/csd/namespaces/\{namespace\}/update_domains

Domínios Protegidos

Operação	Método	Caminho
Listar	GET	/api/shape/csd/namespaces/\{namespace\}/protected_domains
Obter	GET	/api/shape/csd/namespaces/\{namespace\}/protected_domains/\{name\}
Criar	POST	/api/shape/csd/namespaces/\{namespace\}/protected_domains
Excluir	DELETE	/api/shape/csd/namespaces/\{namespace\}/protected_domains/\{name\}

Domínios Detectados

Operação	Método	Caminho
Listar Detectados	GET	/api/shape/csd/namespaces/\{namespace\}/detected_domains
Obter Detalhes	GET	/api/shape/csd/namespaces/\{namespace\}/domain_details

Domínios Permitidos

Operação	Método	Caminho
Listar	GET	/api/shape/csd/namespaces/\{namespace\}/allowed_domains
Obter	GET	/api/shape/csd/namespaces/\{namespace\}/allowed_domains/\{name\}
Criar	POST	/api/shape/csd/namespaces/\{namespace\}/allowed_domains
Excluir	DELETE	/api/shape/csd/namespaces/\{namespace\}/allowed_domains/\{name\}

Domínios Mitigados

Operação	Método	Caminho
Listar	GET	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains
Obter	GET	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains/\{name\}
Criar	POST	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains
Excluir	DELETE	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains/\{name\}

Scripts

Operação	Método	Caminho
Listar Scripts	POST	/api/shape/csd/namespaces/\{namespace\}/scripts
Listar Scripts (legado)	GET	/api/shape/csd/namespaces/\{namespace\}/scripts
Obter Visão Geral do Script	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/dashboard
Listar Comportamentos	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/behaviors
Listar Interações de Rede	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/networkInteractions
Atualizar Justificativa	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/justification
Excluir Justificativa	DELETE	/api/shape/csd/namespaces/\{namespace\}/script/justification/\{justification_id\}
Atualizar Status de Leitura	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/readStatus
Listar Usuários Afetados	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/affectedUsers

Campos de Formulário

Operação	Método	Caminho
Listar Campos de Formulário	GET	/api/shape/csd/namespaces/\{namespace\}/formFields
Listar Campos de Formulário (POST)	POST	/api/shape/csd/namespaces/\{namespace\}/formFields
Obter Campo de Formulário	GET	/api/shape/csd/namespaces/\{namespace\}/formFields/\{id\}
Listar por Script	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/formFields
Atualizar Análise de Campo	POST	/api/shape/csd/namespaces/\{namespace\}/formFields/analysis

Habilitar CSD

Inicializa o CSD para o 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"

Obter Status do CSD

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

Domínios Protegidos

Listar Domínios Protegidos

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

Adicionar um Domínio 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 .

Excluir um Domínio Protegido

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

Domínios Detectados

Listar Domínios Detectados

Parâmetros de consulta: locations (filtrar por localização), risk (filtrar por nível de risco).

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

Filtrar por alto risco:

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

Obter Detalhes do Domínio

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 os 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 .

Obter Visão Geral do 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 Comportamentos do Script

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

Listar Interações de Rede

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

Mitigação

Adicionar um Domínio 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 Domínios Mitigados

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

Remover Mitigação

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

Domínios Permitidos

Adicionar um Domínio 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 Domínios Permitidos

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

Remover um Domínio Permitido

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

Configuração de Injeção de JS

Obter Configuração Atual

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

Configuração do CSD no Balanceador de Carga HTTP

A injeção de JavaScript do CSD também pode ser habilitada diretamente em um Balanceador de Carga HTTP por meio da API de configuração em /api/config/namespaces/\{namespace\}/http_loadbalancers/\{name\}.

O campo client_side_defense dentro da especificação do balanceador de carga controla a injeção:

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

O campo policy aceita um dos seguintes valores:

Campo	Descrição
js_insert_all_pages	Injetar em todas as páginas
js_insert_all_pages_except	Injetar em todas as páginas, exceto pelas regras de exclusão
js_insertion_rules	Injetar apenas nas páginas que correspondam às regras
disable_js_insert	Não injetar

Para desabilitar o CSD em um balanceador de carga, substitua client_side_defense por disable_client_side_defense: \{\}.

Ler Configuração do CSD a partir do 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 em um Balanceador de Carga

Recupere, modifique e 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'

Correspondência de Domínio e Caminho para Regras de Exclusão

Ao utilizar js_insert_all_pages_except ou js_insertion_rules, cada regra corresponde a uma combinação de domínio e caminho.

Domínio (escolha um):

Campo	Exemplo
any_domain: \{\}	Todos os domínios
domain.exact_value	"app.example.com"
domain.suffix_value	".example.com"
domain.regex_value	".*\\.example\\.com"

Caminho (escolha um):

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

Referência da API

• Referência da API CSD — Documentação completa dos endpoints
• Configurar CSD — Guia de configuração pelo Console
• Credenciais de API — Gerar tokens de API