Esta página aplica-se ao Apigee e ao Apigee Hybrid.
Veja a documentação do
Apigee Edge.
Vista geral
Esta página descreve como gerir as classificações de segurança e os perfis de segurança da avaliação de riscos (também denominados simplesmente "perfis") através de APIs. Esta página apresenta exemplos de pedidos de API.
Para uma vista geral da funcionalidade de avaliação de riscos, incluindo limitações e instruções para usar a IU, consulte o artigo Vista geral e IU da avaliação de riscos.
Exemplos da API Risk Assessment v2
Parâmetros para exemplos de API v2
Os exemplos nesta secção podem usar estes parâmetros:
- ORG é a sua organização.
- ENV é o ambiente no qual 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 criar. - PROFILE_DESC (opcional) é a descrição do perfil. Esta deve ser uma descrição legível do perfil que faculte informações suficientes para o diferenciar de outros perfis.
- PROXY_NAME: o nome do proxy.
- RESOURCES pode ser:
"include_all_resources":{}
para monitorizar todos os recursos no âmbito."include": { "resources": [{"type": "API_PROXY", "name": "PROXY_NAME"}]}
para monitorizar um ou mais proxies especificados. Por exemplo,"include": { "resources": [{"type": "API_PROXY", "name": "my-proxy-1"}]}
para monitorizar o proxy denominadomy-proxy-1
.
- SECURITY_MONITORING_CONDITION_ID: O ID exclusivo da condição de monitorização de segurança. Se não for fornecido nenhum ID, é gerado automaticamente um UUID.
$TOKEN
é a variável de ambiente para uma chave de acesso OAuth.
Obtenha resultados da avaliação de segurança em lote
Os utilizadores com as funções Security Admin
ou Security Viewer
têm autorizações
para realizar um cálculo de avaliação de risco ad hoc. Tem de especificar o perfil de segurança, o âmbito (o ambiente do Apigee) e os recursos a avaliar. Os recursos podem ser include_all_resources: true
para calcular em todos os recursos no âmbito ou apenas num punhado. Consulte
securityAssessmentResults.batchCompute
na documentação de referência da API Apigee Management para mais informações sobre esta funcionalidade.
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityAssessmentResults:batchCompute" \ -X POST \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-type: application/json' \ -d '{ "profile": "PROFILE_ID", "scope": "ENV", RESOURCES }'
Esta é uma potencial resposta para o pedido:
{ "securityAssessmentResults": [ { "resource": { "type": "API_PROXY", "name": "my-proxy-1", "resourceRevisionId": "1" }, "createTime": "2023-11-22T04:49:29.418166Z", "scoringResult": { "severity": "HIGH", "failedAssessmentPerWeight": { "MINOR": 1 }, "assessmentRecommendations": { "cors-policies-check": { "displayName": "CORS policies check", "weight": "MAJOR", "recommendations": [ { "description": "Check whether a CORS policy or CORS header in AssignMessage policy are present.", "link": { "text": "Learn more", "uri": "https://cloud.google.com/apigee/docs/api-platform/reference/policies/reference-overview-policy" } } ], "verdict": "FAIL", "scoreImpact": 100 } }, "dataUpdateTime": "2023-11-22T04:49:29.418166Z" } } ], "assessmentTime": "2023-11-22T04:49:29.418166Z" }
Faça a gestão dos perfis de segurança
Esta secção fornece exemplos para gerir perfis de segurança através das APIs e não é exaustiva. Consulte os documentos de referência da API securityProfilesV2 para mais informações.
Obtenha perfis de segurança personalizados existentes
Este comando obtém 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"
Este comando obtém os metadados de um perfil de segurança específico e pode ser usado para
obter informações sobre o perfil google-default
, bem como perfis personalizados:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID" \ -H "Authorization: Bearer $TOKEN"
Crie um novo perfil de segurança personalizado
Para criar um novo 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"} } }'
Atualize um perfil de segurança personalizado existente
Para atualizar um perfil existente, 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"}'
onde UPDATE_MASK pode ser um destes valores, se estiver presente: description
,
profile_assessment_configs
, description,profile_assessment_configs
ou
*
(tudo). Se especificar a máscara de atualização, o pedido atualiza todos os campos, o que pode remover valores se não estiverem incluídos no pedido.*
A omissão de update_mask
atualiza apenas os campos fornecidos no pedido de atualização.
Elimine um perfil de segurança personalizado
Para eliminar um perfil de segurança personalizado:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID" \ -X DELETE \ -H "Authorization: Bearer $TOKEN"
Faça a gestão das condições de monitorização
Esta secção fornece exemplos de gestão das condições de monitorização através das APIs e não é exaustiva. Consulte os documentos de referência da API de condições de monitorização para mais informações sobre a gestão das condições de monitorização através das APIs.
Crie uma nova condição de monitorização
Para criar uma nova condição de monitorização, use um comando como este:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions?security_monitoring_condition_id=MONITORING_CONDITION_ID" \ -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{ "profile": "PROFILE_ID", "scope": "ENV", RESOURCES }'
A resposta pode ter o seguinte aspeto:
{ "name": "organizations/my-org/securityMonitoringConditions/my-condition", "createTime": "2025-11-22T05:02:16.089469Z", "updateTime": "2023-11-22T05:02:16.089469Z", "profile": "google-default", "scope": "test", "totalMonitoredResources": 4, "totalDeployedResources": 4, "includeAllResources": {} }
Apresentar condições de monitorização
Para obter uma lista de condições de monitorização na sua organização, use um comando como este:
curl -H "Authorization: Bearer $TOKEN" \ "https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions"
A resposta tem este formato:
{ "securityMonitoringConditions": [ { "name": "organizations/my-org/securityMonitoringConditions/my-condition", "createTime": "2023-11-22T05:02:16.089469Z", "updateTime": "2025-11-22T05:02:16.089469Z", "profile": "google-default", "scope": "test", "totalMonitoredResources": 4, "totalDeployedResources": 4, "includeAllResources": {} } ] }
Também pode usar esta sintaxe para limitar os resultados devolvidos por âmbito ou perfil de segurança:
curl -H "Authorization: Bearer $TOKEN" \ "https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions?filter=scope=ENV%20AND%20profile=PROFILE_ID"
Obtenha uma condição de monitorização existente
Para obter as informações de uma condição de monitorização existente, use um comando como este:
curl -H "Authorization: Bearer $TOKEN" \ "https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions/MONITORING_CONDITION_ID"
A resposta tem este formato:
{ "name": "organizations/my-org/securityMonitoringConditions/my-condition", "createTime": "2023-11-22T05:02:16.089469Z", "updateTime": "2025-11-22T05:02:16.089469Z", "profile": "google-default", "scope": "test", "totalMonitoredResources": 4, "totalDeployedResources": 4, "includeAllResources": {} }
Atualize uma condição de monitorização existente
Este comando atualiza o perfil de uma condição de monitorização existente:
curl -H "Authorization: Bearer $TOKEN" \ "https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions/MONITORING_CONDITION_ID?update_mask=CONDITION_UPDATE_MASK" -X PATCH -H "Content-Type: application/json" \ -d '{ RESOURCES }'
onde update_mask
é opcional. Se incluído, CONDITION_UPDATE_MASK pode
ser include
ou include_all_resources
. A omissão de update_mask
atualiza apenas os campos fornecidos no pedido de atualização.
A resposta pode ter o seguinte aspeto:
{ "name": "test-condition", "createTime": "2023-11-22T03:04:05Z", "updateTime": "2023-11-22T03:04:05Z", "profile": "google-default", "scope": "test", "include": { "resources": [{ "type": "API_PROXY", "name": "PROXY_NAME" }] } }
Elimine uma condição de monitorização
Este comando elimina uma condição de monitorização existente:
curl -H "Authorization: Bearer $TOKEN" \ "https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions/MONITORING_CONDITION_ID" \ -X DELETE
Avaliação de risco v1
Esta secção mostra informações e exemplos para as APIs Risk Assessment v1.
Limitações nas pontuações de segurança quando usa as APIs
As pontuações de segurança têm as seguintes limitações quando usadas a partir das APIs de pontuações e perfis de segurança:
- Campos de entrada suportados em JSON:
timeRange
: os valores são limitados pelos critérios descritos na referência da API computEnvironmentScores.filters
: Consulte os filtros suportados na API.pageSize
: número máximo de subcomponentes a devolver numa única página: 100.
- Não são suportados vários filtros de entrada.
- O campo de impacto na resposta não é suportado. (O campo de impacto é o potencial impacto desta recomendação na pontuação geral. Isto indica a importância desta recomendação para melhorar a pontuação.)
Para limitações gerais da pontuação de segurança não específicas da utilização a partir das APIs, consulte o artigo Limitações das pontuações de segurança v1.
Parâmetros em exemplos de chamadas API
As secções seguintes fornecem exemplos de chamadas da API e podem usar os seguintes parâmetros:
- ORG é a sua organização.
- ENV é o ambiente no qual quer que as pontuações sejam calculadas.
- ENVGROUP é um grupo de ambientes que contém o ambiente.
- PROFILE_ID é o nome do perfil. PROFILE_ID pode ser
default
ou o nome de um perfil personalizado que criar.PROFILE_ID tem de conter entre 1 e 63 carateres, que podem ser letras minúsculas, números de 0 a 9 ou hífenes. O primeiro caráter tem de ser uma letra minúscula. O último caráter tem de ser uma letra minúscula ou um número.
- PROXY_NAME: o nome do proxy.
$TOKEN
é a variável de ambiente para uma chave de acesso OAuth.timeRange
é o intervalo de tempo para as classificações.
Exemplos da API Risk Assessment v1
Filtros suportados na API
A tabela seguinte apresenta os filtros suportados na API e os respetivos caminhos dos componentes.
Filtro | Caminho do componente |
---|---|
Classificações do ambiente | /org@ORG/envgroup@ENVGROUP/env@ENV |
A origem pontua todos os componentes subjacentes | /org@ORG/envgroup@ENVGROUP/env@ENV/source |
Pontuações de abuso | /org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse |
Resultados para todos os proxies | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies |
Pontuações para um proxy específico | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME |
Classificações de políticas para um proxy específico |
|
Pontuações da política de mediação para um proxy específico | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/mediation |
Pontuações da política de segurança para um proxy específico | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security |
Pontuações da política de autorização para um 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 um proxy específico | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/cors |
Pontuações da política de ameaças para um proxy específico | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/threat |
Classificações de políticas para todos os proxies no ambiente |
|
Pontuações da 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 da 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 da política de autorização para todos os proxies no ambiente | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/auth |
Resultados da 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 da política de ameaças para todos os proxies no ambiente | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat |
Use o perfil de segurança predefinido
Os exemplos seguintes mostram como usar o perfil de segurança predefinido. Consulte Parâmetros em exemplos de chamadas de API para ver os parâmetros usados nos exemplos.
Anexe o perfil de segurança predefinido a um ambiente
Para ver as pontuações de segurança, tem de anexar um perfil ao ambiente cuja segurança quer avaliar. Para anexar o perfil de segurança predefinido 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"
Obtenha a definição do perfil de segurança predefinido
Para obter a definição do perfil de segurança predefinido, introduza o seguinte comando:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default" \ -H 'Content-type: application/json' \ -H "Authorization: Bearer $TOKEN"
Desassocie o perfil de segurança predefinido de um ambiente
Se precisar de desassociar o perfil predefinido de um ambiente, pode fazê-lo da seguinte forma:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments/ENV" \ -X DELETE -H 'Content-type: application/json' \ -H "Authorization: Bearer $TOKEN"
Use um perfil de segurança personalizado
Pode criar um perfil de segurança personalizado com uma chamada API de qualquer uma das seguintes formas:
- Defina explicitamente o perfil no corpo da chamada.
- Anexe um ficheiro JSON que contenha a definição do perfil à chamada.
As secções seguintes apresentam exemplos de ambos os métodos. Consulte Parâmetros em exemplos de chamadas de API para ver os parâmetros usados nos exemplos.
Os campos seguintes nos exemplos de chamadas API especificam o perfil personalizado:
description
: uma descrição do perfil personalizado.profileConfig
: uma lista das categorias a incluir no perfil personalizado. Pode ser qualquer subconjunto das seguintes categorias de segurança:abuse
authorization
cors
mtls
mediation
threat
Defina o perfil no corpo de uma chamada API
Para definir um perfil personalizado no corpo de uma chamada API, introduza 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":{}} ] } }'
Isto cria um perfil personalizado que inclui as categorias cors e threat, e devolve 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" }
Defina o perfil anexando um ficheiro JSON a uma chamada API
Também pode definir um perfil de segurança personalizado anexando um ficheiro JSON que define o perfil a uma chamada API. Por exemplo, comece por criar o seguinte ficheiro JSON:
{ "description": "test custom profile", "profileConfig" : { "categories":[ {"cors":{}}, {"threat" :{}}, ] } }
Isto define um perfil com categorias cors e threat. Em seguida, pode criar um perfil com base nestas categorias da seguinte forma:
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 ficheiro JSON descrito acima.
Obtenha uma definição de perfil de segurança personalizada
Para obter a definição de um perfil de segurança personalizado, introduza 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"
Desassocie um perfil de segurança personalizado de um ambiente
Para desassociar um perfil de segurança personalizado de um ambiente, introduza 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"
Elimine um perfil de segurança personalizado
Para eliminar um perfil de segurança personalizado, introduza 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"
Obtenha resultados para um ambiente
As secções seguintes apresentam exemplos de como obter classificações para um ambiente. Consulte Parâmetros em exemplos de chamadas de API para ver os parâmetros usados nos exemplos.
Obtenha todas as pontuações de um ambiente
Para obter todas as classificações de um ambiente, introduza 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" } }' \ -H 'Content-type: application/json' \ -H "Authorization: Bearer $TOKEN"
Consulte a página de referência
computeEnvironmentScores
para ver uma descrição do pedido
e da resposta.
Obtenha classificações de fontes para um ambiente
Para obter pontuações de origem para um ambiente, introduza 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/source"}] }' \ -H 'Content-type: application/json' \ -H "Authorization: Bearer $TOKEN"
Obtenha a pontuação de abuso na origem para um ambiente
Para obter a pontuação de abuso na origem de um ambiente, introduza 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/source/abuse"}] }' \ -H 'Content-type: application/json' \ -H "Authorization: Bearer $TOKEN"
Obtenha classificações para todos os proxies num ambiente
Para obter classificações para todos os proxies num ambiente, introduza 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/proxies"}] }' \ -H 'Content-type: application/json' \ -H "Authorization: Bearer $TOKEN"
Obtenha classificações para um proxy específico num ambiente
Para obter classificações de um proxy específico num ambiente, introduza 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/proxies/proxy@PROXY"}] }' \ -H 'Content-type: application/json' \ -H "Authorization: Bearer $TOKEN"
em que PROXY é o proxy cujas classificações quer obter.
Obtenha pontuações para um alvo específico num ambiente
Para obter classificações de um alvo específico num ambiente, introduza 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"