Security scores and profiles API

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

In addition to viewing security scores and security profiles in the Apigee UI, you can also access them using the security scores and profiles API. This page presents some examples of using the security scores and profiles API.

Limitations on security scores

Security scores have the following limitations:

  • Supported input fields in JSON:
    • timeRange: The length of the time range can be at most 14 days and the startTime and endTime for the time range must be within the past 90 days. See Time range.
    • 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.)
  • You can create up to 100 custom security profiles.

Data delays

The data that Advanced API Security security scores are based on have the following delays, due to the way the data is processed:

  • When you enable Advanced API Security in an organization, it can take up to 6 hours for the scores for existing proxies and targets to be reflected in an environment.
  • New events related to proxies (deployment and undeployment) and targets (create, update, delete) in an environment can take up to 6 hours to reflect in the environment's score.
  • Data flowing into the Apigee Analytics pipeline has a delay of up to 15 to 20 minutes on average. As a result source scores abuse data has processing delay around 15 to 20 minutes.

Parameters in example API calls

The following sections give examples of API calls that use the security scores and profiles API. The API calls contain 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.

  • $TOKEN is the environment variable for an OAuth access token.
  • timeRange is the time range for the scores.

Time range

The time range for the data on which security scores are calculated. You can set the time range by specifying a start and end time for the scores in the following format:

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

Both startTime and endTime must be be within the past 90 days.

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"

    Filters supported in the API

    The following table lists the filters that are supported in the API, and their component paths. In the component paths, replace the variables as follows:

    • ORG: Your organization.
    • ENV: The environment in which you are viewing the scores.
    • PROXY_NAME: The name of the proxy.
    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
    • /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies
    • /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual
    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
    • /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies
    • /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual
    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