安全分数和配置文件 API

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

除了在 Apigee 界面中查看安全得分和安全配置文件之外，您还可以使用安全得分和配置文件 API 来访问它们。本页面介绍了使用安全得分和配置文件 API 的一些示例。

使用 API 时的安全得分限制

通过安全得分和配置文件 API 使用安全得分时，安全得分存在以下限制：

支持的输入字段（JSON 格式）：
- timeRange：时间范围的长度最多为 14 天，该时间范围的 startTime 和 endTime 必须在过去 90 天内。请参阅时间范围。
- filters：请参阅 API 中支持的过滤条件。
- pageSize：单个页面中返回的子组件数上限：100。
不支持对输入使用多个过滤条件。
不支持响应中的“影响”字段。（“影响”字段是此建议对整体得分的潜在影响；这表示此建议对提高得分的重要性。）

如需了解并非特定于通过 API 使用的一般安全得分限制，请参阅安全得分限制。

数据延迟

Advanced API Security 得分所基于的数据因数据处理方式而存在以下延迟：

在组织中启用 Advanced API Security 后，现有代理和目标的得分最多可能需要 6 小时才能在环境中体现。
与环境中的代理（部署和取消部署）和目标（创建、更新、删除）相关的新事件最多可能需要 6 小时才能在环境的得分中体现。
数据进入 Apigee Analytics 流水线的平均延迟时间为 15 到 20 分钟。因此，来源得分滥用行为数据大约有 15 到 20 分钟的处理延迟。

API 调用示例中的参数

以下部分提供了使用安全得分和配置文件 API 的 API 调用示例。API 调用包含以下参数：

ORG 是您的组织。
ENV 是您要计算得分的环境。
ENVGROUP 是包含环境的环境组。
PROFILE_ID 是配置文件的名称。PROFILE_ID 可以是 default 或您创建的自定义配置文件的名称。
PROFILE_ID 必须包含 1 到 63 个字符，可以是小写字母、数字 0-9 或连字符。第一个字符必须是小写字母。最后一个字符必须是小写字母或数字。
$TOKEN 是 OAuth 访问令牌的环境变量。
timeRange 是得分的时间范围。

时间范围

计算安全得分基于的数据的时间范围。您可以按以下格式指定得分的开始时间和结束时间来设置时间范围：

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

startTime 和 endTime 都必须在过去 90 天内。

使用默认安全配置文件

以下示例展示了如何使用默认安全配置文件。如需了解示例中使用的参数，请参阅 API 调用示例中的参数。

将默认安全配置文件附加到环境

如需查看安全分数，您需要将配置文件附加到要评估安全性的环境。如需将默认安全配置文件附加到环境，请使用以下命令：

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"

注意：参数 securityProfileRevisionId 已弃用。如果您在 API 调用中添加此参数，则无论参数值是什么，Advanced API Security 都会使用配置文件的最新修订版本。

获取默认安全配置文件定义

要获取默认安全配置文件的定义，请输入以下命令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default" \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

从环境分离默认安全配置文件

如果需要从环境分离默认配置文件，您可以使用以下命令：

  curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments/ENV" \
         -X DELETE
         -H 'Content-type: application/json' \
         -H "Authorization: Bearer $TOKEN"

使用自定义安全配置文件

您可以通过以下任一方式使用 API 调用创建自定义安全配置文件：

在调用正文中明确定义配置文件。
将包含配置文件定义的 JSON 文件附加到调用。

以下部分提供了这两种方法的示例。如需了解示例中使用的参数，请参阅 API 调用示例中的参数。

示例 API 调用中的以下字段指定了自定义配置文件：

description：自定义配置文件的说明。

profileConfig：要包含在自定义配置文件中的类别列表。这可以是以下安全类别的任意子集：

abuse
authorization
cors
mtls
mediation
threat

在 API 调用正文中定义配置文件

如需在 API 调用正文中定义自定义配置文件，请输入如下所示的命令：

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

这将创建一个包含类别 cors 和 threats 的自定义配置文件，并返回以下响应：

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

通过将 JSON 文件附加到 API 调用来定义配置文件

您还可以通过将定义配置文件的 JSON 文件附加到 API 调用来定义自定义安全配置文件。例如，首先创建以下 JSON 文件：

{
  "description": "test custom profile",
  "profileConfig" : {
    "categories":[
      {"cors":{}},
      {"threat" :{}},
    ]
  }
}

这定义了具有类别 cors 和 threat 的配置文件。然后，您可以根据这些类别创建配置文件，如下所示：

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

其中，create_profile.json 是上面描述的 JSON 文件的名称。

获取自定义安全配置文件定义

如需获取自定义安全配置文件的定义，请输入如下所示的命令：

  curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
         -X GET \
         -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json"

从环境分离自定义安全配置文件

如需从环境分离自定义安全配置文件，请输入如下所示的命令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json"

删除自定义安全配置文件

如需删除自定义安全配置文件，请输入如下所示的命令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json"

获取环境的得分

以下部分展示了获取环境得分的示例。如需了解示例中使用的参数，请参阅 API 调用示例中的参数。

获取环境的所有得分

如需获取环境的所有得分，请输入如下所示的命令：

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"

如需查看请求和响应的说明，请参阅 computeEnvironmentScores 参考页面。

获取环境的源得分

如需获取环境的源得分，请输入如下所示的命令：

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"

获取环境的滥用行为得分

如需获取环境源中的滥用行为得分，请输入如下所示的命令：

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"

获取环境中所有代理的得分

如需获取环境中所有代理的得分，请输入如下所示的命令：

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"

获取环境中特定代理的得分

如需获取环境中特定代理的得分，请输入如下所示的命令：

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"

其中，PROXY 是您想要获取其得分的代理。

获取环境中特定目标的得分

如需获取环境中特定目标的得分，请输入如下所示的命令：

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"

API 中支持的过滤条件

下表列出了 API 中支持的过滤条件及其组件路径。在组件路径中，按如下方式替换变量：

ORG：您的组织。
ENV：要在其中查看得分的环境。
PROXY_NAME：代理的名称。

过滤条件	组件路径
环境得分	`/org@ORG/envgroup@ENVGROUP/env@ENV`
源得分（所有底层组件）	`/org@ORG/envgroup@ENVGROUP/env@ENV/source`
滥用行为得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse`
所有代理的得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies`
特定代理的得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME`
特定代理的政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies` `/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual`
特定代理的中介政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/mediation`
特定代理的安全政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security`
特定代理的身份验证政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/auth`
特定代理的 CORS 政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/cors`
特定代理的威胁政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/threat`
环境中所有代理的政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies` `/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual`
环境中所有代理的中介政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/mediation`
环境中所有代理的安全政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security`
环境中所有代理的身份验证政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/auth`
环境中所有代理的 CORS 政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors`
环境中所有代理的威胁政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat`