API de perfis e pontuações de segurança

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Além de visualizar pontuações de segurança e perfis de segurança na IU da Apigee, também é possível acessá-los usando a API de perfis e pontuações de segurança. Nesta página, apresentamos alguns exemplos de uso da API de perfis e pontuações de segurança.

Limitações das pontuações de segurança ao usar as APIs

As pontuações de segurança têm as seguintes limitações quando usadas nas APIs de pontuações e perfis de segurança:

Campos de entrada compatíveis com JSON:
- timeRange: a duração do período pode ser de no máximo 14 dias, e o startTime e endTime do período precisam estar nos últimos 90 dias. Consulte Período.
- filters: Consulte Filtros compatíveis com a API.
- pageSize: número máximo de subcomponentes a serem retornados em uma única página: 100.
Não é possível usar vários filtros de entrada.
Não é possível usar o campo de impacto na resposta. O campo de impacto é o possível impacto dessa recomendação na pontuação geral. Isso indica a importância dessa recomendação para melhorar a pontuação.

Para as limitações gerais da pontuação de segurança não específicas do uso das APIs, consulte Limitações das pontuações de segurança.

Atrasos nos dados

Os dados em que as pontuações de segurança da API Advanced se baseiam têm os seguintes atrasos, devido à forma como os dados são processados:

Quando você ativa a segurança avançada da API em uma organização, pode levar até 6 horas para que as pontuações dos proxies e destinos atuais sejam refletidas em um ambiente.
Pode levar até 6 horas para que os eventos novos relacionados a proxies (implantação e cancelamento de implantação) e destinos (criar, atualizar e excluir) apareçam na pontuação do ambiente.
Os dados que fluem para o pipeline do Apigee Analytics têm um atraso de até 15 a 20 minutos em média. Como resultado, a fonte registra os dados de abuso que têm um atraso de processamento de 15 a 20 minutos.

Parâmetros em chamadas de API de exemplo

As seções a seguir mostram exemplos de chamadas de API que usam a API de perfis e as pontuações de segurança. As chamadas de API contêm os seguintes parâmetros:

ORG é sua organização.
ENV é o ambiente em que você quer que as pontuações sejam calculadas.
ENVGROUP é um grupo de ambiente que contém o ambiente.
PROFILE_ID é o nome do perfil. PROFILE_ID pode ser default ou o nome de um perfil personalizado que você cria.
PROFILE_ID precisa conter de 1 a 63 caracteres, que podem ser letras minúsculas, números de 0 a 9 ou hifens. O primeiro caractere precisa ser uma letra minúscula. O último caractere precisa ser uma letra minúscula ou um número.
$TOKEN é a variável de ambiente de um token de acesso do OAuth.
timeRange é o período da pontuação

Intervalo de tempo

O período dos dados em que as pontuações de segurança são calculadas. É possível definir o intervalo de tempo especificando um horário de início e término para as pontuações no seguinte formato:

"timeRange":
  {
    "startTime": "YYYY-MM-DDT00:00:00Z",
    "endTime": "YYYY-MM-DDT00:00:00Z"
  }

startTime e endTime precisam estar dentro dos últimos 90 dias.

Usar o perfil de segurança padrão

Os exemplos a seguir mostram como usar o perfil de segurança padrão. Consulte Parâmetros em chamadas de API de exemplo para conferir os parâmetros usados nos exemplos.

Para anexar o perfil de segurança padrão a um ambiente, faça o seguinte:

Para ver as pontuações de segurança, você precisa anexar um perfil ao ambiente cuja segurança você quer avaliar. Para anexar o perfil de segurança padrão a um ambiente, use o seguinte comando:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments" \
       -X POST \
       -d '{"name": "ENV"}' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Observação: o parâmetro securityProfileRevisionId foi suspenso. Se você incluir esse parâmetro em uma chamada de API, a Segurança avançada de API usará a revisão mais recente do perfil, independentemente do valor do parâmetro.

Ver a definição do perfil de segurança padrão

Para ver a definição do perfil de segurança padrão, digite o seguinte comando:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default" \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Remover o perfil de segurança padrão de um ambiente

Se você precisar desanexar o perfil padrão de um ambiente, faça isso da seguinte maneira:

  curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments/ENV" \
         -X DELETE
         -H 'Content-type: application/json' \
         -H "Authorization: Bearer $TOKEN"

Usar um perfil de segurança personalizado

É possível criar um perfil de segurança personalizado com uma chamada de API das seguintes maneiras:

Defina explicitamente o perfil no corpo da chamada.
Anexe à chamada um arquivo JSON com a definição do perfil.

As seções a seguir dão exemplos dos dois métodos. Consulte Parâmetros em chamadas de API de exemplo para conferir os parâmetros usados nos exemplos.

Os seguintes campos nas chamadas da API de exemplo especificam o perfil personalizado:

description: uma descrição do perfil personalizado.

profileConfig: uma lista das categorias a serem incluídas no perfil personalizado. Pode ser qualquer subconjunto das seguintes categorias de segurança:

abuse
authorization
cors
mtls
mediation
threat

Definir o perfil no corpo de uma chamada de API

Para definir um perfil personalizado no corpo de uma chamada de API, insira um comando semelhante ao seguinte:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles?security_profile_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
         "description":"test custom profile",
         "profileConfig" : {
           "categories":[
             {"cors":{}},
             {"threat":{}}
           ]
         }
       }'

Isso cria um perfil personalizado que inclui as categorias "cors" e "ameaça" e retorna a seguinte resposta:

{
  "name": "PROFILE_ID",
  "revisionId": "1",
  "revisionCreateTime": "2023-07-17T18:47:08Z",
  "revisionUpdateTime": "2023-07-17T18:47:08Z",
  "scoringConfigs": [
    {
      "title": "json",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat/json",
      "description": "Check if JSONThreatProtection policy is configured."
    },
    {
      "title": "xml",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat/xml",
      "description": "Check if XMLThreatProtection policy is configured."
    },
    {
      "title": "cors",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors",
      "description": "Check if CORS policy is configured."
    }
  ],
  "maxScore": 1200,
  "minScore": 200,
  "profileConfig": {
    "categories": [
      {
        "cors": {}
      },
      {
        "threat": {}
      }
    ]
  },
  "description": "test custom profile"
  }

Definir o perfil anexando um arquivo JSON a uma chamada de API

Também é possível definir um perfil de segurança personalizado anexando um arquivo JSON que define o perfil a uma chamada de API. Como exemplo, primeiro crie o seguinte arquivo JSON:

{
  "description": "test custom profile",
  "profileConfig" : {
    "categories":[
      {"cors":{}},
      {"threat" :{}},
    ]
  }
}

Isso define um perfil com categorias de cors e ameaças. Em seguida, você poderá criar um perfil com base nessas categorias da seguinte maneira:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles?security_profile_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -d @create_profile.json

em que create_profile.json é o nome do arquivo JSON descrito acima.

Receber uma definição personalizada de perfil de segurança

Para obter a definição de um perfil de segurança personalizado, insira um comando semelhante ao seguinte:

  curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
         -X GET \
         -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json"

Remover um perfil de segurança personalizado de um ambiente

Para desanexar um perfil de segurança personalizado de um ambiente, insira um comando semelhante ao seguinte:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json"

Excluir um perfil de segurança personalizado

Para excluir um perfil de segurança personalizado, insira um comando semelhante ao seguinte:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json"

Receber pontuações de um ambiente

As seções a seguir apresentam exemplos de como receber pontuações de um ambiente. Consulte Parâmetros em chamadas de API de exemplo para conferir os parâmetros usados nos exemplos.

Receber todas as pontuações de um ambiente

Para receber todas as pontuações de um ambiente, insira um comando semelhante a este:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              }
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Consulte a página de referência computeEnvironmentScores para ver uma descrição da solicitação e da resposta.

Receber pontuações de origem para um ambiente

Para receber pontuações de origem de um ambiente, insira um comando semelhante a este:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/source"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Receber pontuação de abuso na origem de um ambiente

Para ver a pontuação de abuso na origem de um ambiente, insira um comando semelhante a este:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Receber pontuações para todos os proxies em um ambiente

Para receber pontuações para todos os proxies em um ambiente, insira um comando semelhante a este:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Receber pontuações para um proxy específico em um ambiente

Para receber pontuações de um proxy específico em um ambiente, digite um comando semelhante a este:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

em que PROXY é o proxy com as pontuações que você quer ver.

Receber pontuações para um proxy específico em um ambiente

Para receber pontuações para um destino específico em um ambiente, digite um comando semelhante ao seguinte:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/target@TARGET"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Filtros compatíveis com a API

A tabela a seguir lista os filtros compatíveis com a API e os caminhos dos componentes dela. Nos caminhos do componente, substitua as variáveis da seguinte maneira:

ORG: sua organização.
ENV: o ambiente em que você está vendo as pontuações.
PROXY_NAME: o nome do proxy.

Filtro	Caminho do componente
Pontuações de ambiente	`/org@ORG/envgroup@ENVGROUP/env@ENV`
Fonte pontua todos os componentes subjacentes	`/org@ORG/envgroup@ENVGROUP/env@ENV/source`
Pontuações de abuso	`/org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse`
Pontuações de todos os proxies	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies`
Pontuações para proxy específico	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME`
Pontuações de política para proxy específico	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies` `/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual`
Pontuações de política de mediação para proxy específico	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/mediation`
Pontuações de política de segurança para proxy específico	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security`
Pontuações de política de autenticação para proxy específico	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/auth`
Pontuação da política de CORS para proxy específico	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/cors`
Pontuações de política de ameaças para proxy específico	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/threat`
Pontuações de política para todos os proxies no ambiente	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies` `/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual`
Pontuações de política de mediação para todos os proxies no ambiente	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/mediation`
Pontuações de política de segurança para todos os proxies no ambiente	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security`
Pontuações de política de autenticação para todos os proxies no ambiente	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/auth`
Pontuações de política de CORS para todos os proxies no ambiente	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors`
Pontuações de política de ameaças para todos os proxies no ambiente	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat`