This page applies to Apigee and Apigee hybrid.
View
Apigee Edge documentation.
Overview
This page describes how to manage Risk Assessment security scores and security profiles using APIs. It also presents example API requests.
For an overview of the Risk Assessment functionality, including limitations, and instructions for using the UI, see Risk assessment overview and UI.
Risk Assessment v2 API Examples
Retrieve batch security assessment results
Users with the Security Admin
or Security Viewer
roles have permissions
to perform an ad hoc risk assessment computation. You'll need to specify the security profile,
scope, and resources to be assessed. Resources could be include_all_resources: true
to
compute on all resources within the scope, or only a handful. See
securityAssessmentResults.batchCompute
in the Apigee Management API reference documentation for more information on this functionality.
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": {} }'
where:
- ORG is your organization.
- ENV is the environment in which you are viewing the scores.
This is a potential response for the request above.
{ "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
This section shows information and examples for Risk Assessment v1 APIs.
Limitations on security scores when using the APIs
Security scores have the following limitations when used from the security scores and profiles APIs:
- Supported input fields in JSON:
timeRange
: Values are limited by the criteria described in the computEnvironmentScores API reference.filters
: See Filters supported in the API.pageSize
: Maximum number of subcomponents to be returned in a single page: 100.
- Multiple input filters are not supported.
- Impact field in response is not supported. (Impact field is the potential impact of this recommendation on the overall score. This denotes how important this recommendation is to improve the score.)
For general security score limitations not specific to use from the APIs, see Limitations on security scores v1.
Parameters in example API calls
The following sections provide example API calls and can use the following parameters:
- ORG is your organization.
- ENV is the environment in which you want scores to be calculated.
- ENVGROUP is an environment group containing the environment.
- PROFILE_ID is the name of the profile. PROFILE_ID can be
default
or the name of a custom profile that you create.PROFILE_ID must contain from 1 to 63 characters, which can be lower case letters, numbers 0-9, or hyphens. The first character must be a lower case letter. The last character must be a lower case letter or number.
- PROXY_NAME: The name of the proxy.
- RESOURCES can be:
{"all_resources":true}
for all resources within the scope.{"includes": { "resources": [{"name": "<proxy-name>"}]}
to monitor one or more specified proxies. For example,{"includes": { "resources": [{"name": "my-proxy-1"}]}
to monitor the proxy calledmy-proxy-1
.{"excludes": { "resources": [{"name": "<proxy-name>"}]}
to monitor all the resources except one or more specified proxies. For example,{"excludes": { "resources": [{"name": "my-proxy-1"}]}
monitors all resources except the proxy calledmy-proxy-1
.
$TOKEN
is the environment variable for an OAuth access token.timeRange
is the time range for the scores.
Risk Assessment v1 API Examples
Filters supported in the API
The following table lists the filters that are supported in the API, and their component paths.
Filter | Component path |
---|---|
Environment scores | /org@ORG/envgroup@ENVGROUP/env@ENV |
Source scores all underlying components | /org@ORG/envgroup@ENVGROUP/env@ENV/source |
Abuse scores | /org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse |
Scores for all proxies | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies |
Scores for specific proxy | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME |
Policy scores for specific proxy |
|
Mediation policy scores for specific proxy | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/mediation |
Security policy scores for specific proxy | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security |
Auth policy scores for specific proxy | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/auth |
CORS policy score for specific proxy | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/cors |
Threat policy scores for specific proxy | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/threat |
Policy scores for all proxies in the env |
|
Mediation policy scores for all proxies in the env | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/mediation |
Security policy scores for all proxies in the env | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security |
Auth policy scores for all proxies in the env | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/auth |
CORS policy scores for all proxies in the env | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors |
Threat policy scores for all proxies in the env | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat |
Use the default security profile
The following examples show how to use the default security profile. See Parameters in example API calls for the parameters used in the examples.
Attach the default security profile to an environment
To view security scores, you need to attach a profile to the environment whose security you want to evaluate. To attach the default security profile to an environment, use the following command:
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"
Get the default security profile definition
To get the definition of the default security profile, enter the following command:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default" \ -H 'Content-type: application/json' \ -H "Authorization: Bearer $TOKEN"
Detach the default security profile from an environment
If you need to detach the default profile from an environment, you can do so as follows:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments/ENV" \ -X DELETE -H 'Content-type: application/json' \ -H "Authorization: Bearer $TOKEN"
Use a custom security profile
You can create a custom security profile with an API call in either of the following ways:
- Explicitly define the profile in the body of the call.
- Attach a JSON file that contains the profile definition to the call.
The following sections give examples of both methods. See Parameters in example API calls for the parameters used in the examples.
The following fields in the example API calls specify the custom profile:
description
: A description of the custom profile.profileConfig
: A list of the categories to include in the custom profile. This can be any subset of the following security categories:abuse
authorization
cors
mtls
mediation
threat
Define the profile in the body of an API call
To define a custom profile in the body of an API call, enter a command similar to the following:
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":{}} ] } }'
This creates a custom profile that includes the categories cors and threat, and returns the following response:
{ "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" }
Define the profile by attaching a JSON file to an API call
You can also define a custom security profile by attaching a JSON file that defines the profile to an API call. As an example, first create the following JSON file:
{ "description": "test custom profile", "profileConfig" : { "categories":[ {"cors":{}}, {"threat" :{}}, ] } }
This defines a profile with categories cors and threat. You can then create a profile based on these categories as follows:
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
where create_profile.json
is the name of the JSON file described above.
Get a custom security profile definition
To get the definition of a custom security profile, enter a command similar to the following:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \ -X GET \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json"
Detach a custom security profile from an environment
To detach a custom security profile from an environment, enter a command similar to the following:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV" \ -X DELETE \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json"
Delete a custom security profile
To delete a custom security profile, enter a command similar to the following:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \ -X DELETE \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json"
Get scores for an environment
The following sections present examples of getting scores for an environment. See Parameters in example API calls for the parameters used in the examples.
Get all scores for an environment
To get all scores for an environment, enter a command similar to the following:
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"
See the
computeEnvironmentScores
reference page for a description of the request
and response.
Get source scores for an environment
To get source scores for an environment, enter a command similar to the following:
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"
Get abuse score in source for an environment
To get the abuse score in source for an environment, enter a command similar to the following:
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"
Get scores for all proxies in an environment
To get scores for all proxies in an environment, enter a command similar to the following:
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"
Get scores for a specific proxy in an environment
To get scores for a specific proxy in an environment, enter command similar to the following:
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"
where PROXY is the proxy whose scores you want to get.
Get scores for a specific target in an environment
To get scores for a specific target in an environment, enter a command similar to the following:
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"