安全分数和配置文件 API

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

概览

本页面介绍了如何使用 API 来管理风险评估安全得分和安全配置文件（简称“配置文件”）。本页介绍了 API 请求示例。

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

Risk Assessment v2 API 示例

v2 API 示例的参数

本部分中的示例可以使用以下参数：

  • ORG 是您的组织。
  • ENV 是您要计算得分的环境。
  • PROFILE_ID 是配置文件的名称。PROFILE_ID 可以是 google-default 或您创建的自定义配置文件的名称。
  • PROFILE_DESC（可选）是配置文件的说明。这应该是对配置文件的人类可读说明，提供足够的信息以便将其与其他配置文件区分开来。
  • PROXY_NAME：代理的名称。
  • $TOKEN 是 OAuth 访问令牌的环境变量。

检索批量安全评估结果

具有 Security Admin 或 Security Viewer 角色的用户有权执行临时风险评估计算。您需要指定安全配置文件、范围（Apigee 环境）和要评估的资源。资源可以是 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": {}
  }'

以下是该请求的可能响应：

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

管理安全配置文件

本部分提供了一些示例，说明如何使用 API 管理安全配置文件，但并非详尽无遗。如需了解详情，请参阅 securityProfilesV2 API 参考文档。

获取现有的自定义安全配置文件

以下命令会检索项目的所有安全配置文件的信息：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2" \
      -H "Authorization: Bearer $TOKEN"

此命令可用于检索特定安全配置文件的元数据，并可用于检索 google-default 配置文件以及自定义配置文件中的信息：

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID" \
      -H "Authorization: Bearer $TOKEN"

创建新的自定义安全配置文件

如需创建新的自定义安全配置文件，请使用如下命令：

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

更新现有的自定义安全配置文件

如需更新现有配置文件，请使用以下命令：

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

其中，UPDATE_MASK 可以是以下值之一（如果存在）：description、profile_assessment_configs、description,profile_assessment_configs 或 *（所有内容）。如果指定 * 更新掩码，请求会更新所有字段，如果请求中未包含值，则可能会移除这些值。

省略 update_mask 后，系统仅更新更新请求中提供的字段。

删除自定义安全配置文件

删除自定义安全配置文件：

curl "https://apigee.googleapis.com/v1/organizations/$ORG/securityProfilesV2/PROFILE_ID" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN"

Risk Assessment v1

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

使用 API 时的安全得分限制

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

  • 支持的输入字段（JSON 格式）：
  • 不支持对输入使用多个过滤条件。
  • 不支持响应中的“影响”字段。（“影响”字段是此建议对整体得分的潜在影响；这表示此建议对提高得分的重要性。）

如需了解并非特定于通过 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"
获取默认安全配置文件定义

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

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 和 threat 的自定义配置文件，并返回如下所示的响应：

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