安全分数和配置文件 API

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

概览

本页面介绍了如何使用 API 来管理风险评估安全分数和安全配置文件。本页还介绍了 API 请求示例。

注意：Risk Assessment v1 和 v2 的 API 具有单独的数据和 API。一个版本中的 API 无法用于查询另一个版本。例如，Risk Assessment v1 API 无法用于查询 Risk Assessment v2 数据。

如需概括了解风险评估功能（包括限制）以及使用界面的说明，请参阅风险评估概览和界面。

Risk Assessment v2 API 示例

预览 — Risk Assessment v2

此功能须遵守服务专用条款的“通用服务条款”部分中的“非正式版产品条款”。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

检索批量安全评估结果

具有 Security Admin 或 Security Viewer 角色的用户有权执行临时风险评估计算。您需要指定安全配置文件、范围和要评估的资源。资源可以是 include_all_resources: true，用于计算范围内的所有资源，也可以仅计算少数资源。如需详细了解此功能，请参阅 Apigee Management API 参考文档中的 securityAssessmentResults.batchCompute。

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

其中：

• ORG 是您的组织。
• ENV 是要在其中查看分数的环境。

以下是上述请求的可能响应：

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

风险评估 v1

本部分介绍了 Risk Assessment v1 API 的信息和示例。

使用 API 时的安全得分限制

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

• 支持的输入字段（JSON 格式）：
  • timeRange：值受 computEnvironmentScores API 参考文档中所述的条件的限制。
  • filters：请参阅 API 中支持的过滤条件。
  • pageSize：单个页面中返回的子组件数上限：100。
• 不支持对输入使用多个过滤条件。
• 不支持响应中的“影响”字段。（“影响”字段是此建议对整体得分的潜在影响；这表示此建议对提高得分的重要性。）

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

API 调用示例中的参数

以下部分提供了 API 调用示例，并可使用以下参数：

• ORG 是您的组织。
• ENV 是您要计算得分的环境。
• ENVGROUP 是包含环境的环境组。
• PROFILE_ID 是配置文件的名称。PROFILE_ID 可以是 default 或您创建的自定义配置文件的名称。

  PROFILE_ID 必须包含 1 到 63 个字符，可以是小写字母、数字 0-9 或连字符。第一个字符必须是小写字母。最后一个字符必须是小写字母或数字。

• PROXY_NAME：代理的名称。
• RESOURCES 可以是：
  • {"all_resources":true}，表示范围内的所有资源。
  • {"includes": { "resources": [{"name": "<proxy-name>"}]}，用于监控一个或多个指定的代理。例如，{"includes": { "resources": [{"name": "my-proxy-1"}]} 用于监控代理 my-proxy-1。
  • {"excludes": { "resources": [{"name": "<proxy-name>"}]}，用于监控除一个或多个指定代理以外的所有资源。例如，{"excludes": { "resources": [{"name": "my-proxy-1"}]} 会监控除代理 my-proxy-1 之外的所有资源。
• $TOKEN 是 OAuth 访问令牌的环境变量。
• timeRange 是得分的时间范围。

Risk Assessment v1 API 示例

API 中支持的过滤条件

下表列出了 API 中支持的过滤条件及其组件路径。

过滤	组件路径
环境得分	/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

使用默认安全配置文件

以下示例展示了如何使用默认安全配置文件。如需了解示例中使用的参数，请参阅 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"

使用自定义安全配置文件

预览版 - Advanced API Security Custom Profiles

此功能受 Google Cloud 服务条款的正式发布前产品条款的约束。对正式发布前功能的支持可能有限，并且对正式发布前功能的更改可能不兼容其他正式发布前版本。如需了解详情，请参阅发布阶段说明。

可通过 Apigee - Google Cloud 社区论坛获取对 Advanced API Security Custom Profiles 的预览版发布的支持。

您可以通过以下任一方式使用 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"