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.

Visão geral

Esta página descreve como gerenciar pontuações e perfis de segurança da Avaliação de risco usando APIs. Também são apresentados exemplos de solicitações de API.

Para ter uma visão geral da funcionalidade de Avaliação de risco, incluindo limitações e instruções para usar a interface, consulte Visão geral e interface da avaliação de risco.

Exemplos da API Risk Assessment v2

Recuperar os resultados da avaliação de segurança em lote

Os usuários com as funções Security Admin ou Security Viewer têm permissões para realizar um cálculo ad hoc de avaliação de risco. Você precisa especificar o perfil de segurança, escopo e recursos a serem avaliados. Os recursos podem ser include_all_resources: true para computar em todos os recursos no escopo ou apenas em alguns. Consulte securityAssessmentResults.batchCompute na documentação de referência da API Apigee Management para mais informações sobre essa funcionalidade.

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityAssessmentResults:batchCompute" \
  -X POST \
  -H "Authorization: Bearer $TOKEN"
  -H 'Content-type: application/json' \
  -d '{
    "profile": "google-default",
    "scope": "ENV",
    "include_all_resources": {}
  }'

em que:

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

Esta é uma possível resposta para a solicitação acima.

  {
    "security_assessment_results": [
      {
        "resource": {
          "name" : "my-proxy-1",
          "revision": "1"
        },
        "create_time": "2023-11-22T03:04:05Z",
        "score": 99,
        "severity": "low",
        "failed_assessment_by_weight": {
          "MINOR": 1
        },
        "assessment_recommendations": {
          "CORS-Check": {
            "weight": "MINOR",
            "recommendations": [
              {
                "description": "add CORS policy to your proxy",
                "learn_more_link": "https://example.com"
              }
            ]
          }
        }
      },
      {
        "resource": {
          "name" : "my-proxy-2",
          "revision": "3"
        },
        "create_time": "2023-11-22T03:04:05Z",
        "score": 100,
        "severity": "low",
        "resource_revision": "1",
        "failed_assessment_by_weight": {
          "MINOR": 0
        },
        "assessment_recommendations": {}
      }
    ]
  }

Risk Assessment v1

Esta seção mostra informações e exemplos das APIs Risk Assessment v1.

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: os valores são limitados pelos critérios descritos na Referência da API computEnvironmentScores.
- 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 v1.

Parâmetros em chamadas de API de exemplo

As seções a seguir fornecem exemplos de chamadas de API e podem usar 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.
PROXY_NAME: o nome do proxy.
RESOURCES pode ser:
- {"all_resources":true} para todos os recursos no escopo.
- {"includes": { "resources": [{"name": "<proxy-name>"}]} para monitorar um ou mais proxies especificados. Por exemplo, {"includes": { "resources": [{"name": "my-proxy-1"}]} para monitorar o proxy chamado my-proxy-1.
- {"excludes": { "resources": [{"name": "<proxy-name>"}]} para monitorar todos os recursos, exceto um ou mais proxies especificados. Por exemplo: {"excludes": { "resources": [{"name": "my-proxy-1"}]} monitora todos os recursos, exceto o proxy chamado my-proxy-1.
$TOKEN é a variável de ambiente de um token de acesso do OAuth.
timeRange é o período das pontuações.

Exemplos da API Risk Assessment v1

Filtros compatíveis com a API

A tabela a seguir lista os filtros compatíveis com a API e os caminhos dos componentes dela.

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ça para todos os proxies no ambiente	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat`

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 descontinuado. 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"