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 (também chamados de "perfis") usando APIs. Esta página apresenta 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

Parâmetros para exemplos da API v2

Os exemplos desta seção podem usar estes parâmetros:

  • ORG é sua organização.
  • ENV é o ambiente em que você quer que as pontuações sejam calculadas.
  • PROFILE_ID é o nome do perfil. PROFILE_ID pode ser google-default ou o nome de um perfil personalizado que você cria.
  • PROFILE_DESC (opcional) é a descrição do perfil. Essa descrição precisa ser legível por humanos e fornecer informações suficientes para diferenciá-lo de outros perfis.
  • PROXY_NAME: o nome do proxy.
  • $TOKEN é a variável de ambiente de um token de acesso do OAuth.

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, o escopo (o ambiente do Apigee) e os 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": {}
  }'

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

  {
    "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": {}
      }
    ]
  }

Gerenciar perfis de segurança

Esta seção traz exemplos de como gerenciar perfis de segurança usando as APIs e não é exaustiva. Consulte as documentação de referência da API securityProfilesV2 para mais informações.

Conseguir perfis de segurança personalizados

Esse comando recupera as informações de todos os perfis de segurança do seu projeto:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2" \
      -H "Authorization: Bearer $TOKEN"

Esse comando recupera os metadados de um perfil de segurança específico e pode ser usado para extrair informações sobre o perfil google-default e perfis personalizados:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID" \
      -H "Authorization: Bearer $TOKEN"

Criar um perfil de segurança personalizado

Para criar um perfil de segurança personalizado, use um comando como este:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2?security_profile_v2_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H 'Content-type: application/json' \
       -d '{
          "description": "PROFILE_DESC",
          "profile_assessment_configs": {
            "auth-policies-check": {"weight": "MINOR"},
            "threat-policies-check": {"weight": "MODERATE"}
          }
       }'
}

Atualizar um perfil de segurança personalizado

Para atualizar um perfil, use um comando como:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID?update_mask=UPDATE_MASK" \
       -X PATCH \
       -H "Authorization: Bearer $TOKEN" \
       -H 'Content-type: application/json' \
       -d '{"description": "PROFILE_DESC"}'

em que UPDATE_MASK pode ser um destes valores, se presente: description, profile_assessment_configs, description,profile_assessment_configs ou * (tudo). Se a máscara de atualização * for especificada, a solicitação vai atualizar todos os campos, o que pode remover valores se eles não estiverem incluídos na solicitação.

A omissão de update_mask atualiza apenas os campos fornecidos na solicitação de atualização.

Excluir um perfil de segurança personalizado

A exclusão de um perfil de segurança personalizado:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/securityProfilesV2/PROFILE_ID" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN"

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:
  • 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"
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 "threat" e retorna uma resposta como esta:

{
  "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"