安全报告 API

本页面适用于 ApigeeApigee Hybrid

查看 Apigee Edge 文档。

除了在 Apigee 界面中使用安全报告之外,您还可以通过安全报告 API 访问所有安全报告功能。本部分介绍了如何使用安全报告 API。

注意:数据进入 Apigee Analytics 流水线的平均延迟时间为 15 到 20 分钟。因此,结束时间在过去 20 分钟以内的安全报告可能会返回错误的结果。

API 调用示例中的参数

以下各部分提供了使用安全报告 API 的 API 调用的示例。API 调用包含以下参数:

  • ORG 是您的组织。
  • ENV 是您希望在其中计算报告的环境。
  • ENVGROUP 是包含环境的环境组。
  • REPORT_ID 是调用返回的报告 ID,用于创建安全报告
  • $TOKENOAuth 访问令牌的环境变量。
  • timeRange 是报告的时间范围

创建安全报告

如需创建安全报告,请输入如下所示的命令:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports" \
       -X POST -d @./Query.json \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

其中,Query.json 是定义查询的查询模板。查询模板的示例如下所示。

{
  "dimensions": [
    "ax_resolved_client_ip",
  ],
  "metrics": [
    {
      "aggregation_function": "count_distinct",
      "name": "bot"
    },
    {
      "aggregation_function": "sum",
      "name": "bot_traffic"
    },
  ],
  "groupByTimeUnit": "minute",
  "timeRange": "last7days"
}

查询具有以下参数:

  • 指标:
    • bot。这用于计算已确定为机器人来源的不同 IP 地址的数量。

      聚合函数:count_distinct

    • bot_traffic。作为机器人来源的 IP 地址发出的请求总数。

      聚合函数:sum

    请参阅指标和聚合函数

  • 维度:ax_resolved_client_ip。此组会按来源的 IP 地址计算报告中的机器人的数量。

    请参阅维度

  • 过滤条件:environment
  • groupByTimeUnit:minute
  • timeRange:last7days。请参阅时间范围

请注意,此 API 调用会返回与使用 Apigee 界面创建的机器人 IP 地址报告示例相同的报告。

时间范围

报告的时间范围。您可以通过以下任一方式设置 timeRange 字段:

  • 指定报告应扩展到过去多长时间。选项如下:
    "timeRange": "{last60minutes/last24hours/last7days}"
  • 按以下格式指定报告的开始时间和结束时间:
    "timeRange": {
            "start": "YYYY-MM-DDT00:00:00Z",
            "end": "YYYY-MM-DDT00:00:00Z"
            }

    startend 都必须是过去的时间,并且最长可比当前创建报告的时间早一年。

示例响应

以上查询会返回如下所示的响应:

{
  "self": "/organizations/ORG/environments/ENV/securityReports/3964675e-9934-4398-bff5-39dd93a67201",
  "state": "enqueued",
  "created": "2021-08-06T22:28:28Z"
}

响应包含以下内容:

  • 报告 ID,您可以在报告完成后使用该报告 ID 获取报告。在上面的示例中,报告 ID 为 3964675e-9934-4398-bff5-39dd93a67201
  • "state":报告作业的状态,可以是以下项之一:
    • enqueued:报告作业刚刚创建,但尚未运行。
    • running:报告作业正在运行。
    • completed:报告作业已完成。在此阶段,您可以查看报告。
    • expired:报告作业已过期,您无法再查看报告。

获取报告状态

如需获取报告的状态,请发送如下请求:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID" \
       -X GET  -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

其中 REPORT_ID 是报告 ID。请参阅 API 调用示例中的参数

该响应包含报告参数的摘要以及报告的当前状态。在此示例中,状态为 "completed",因此您可以查看报告的结果。

{
  "self": "/organizations/sense-staging-test/environments/local/securityReports/bd2f4fe0-a906-44c2-8dcb-2c618e4b565d",
  "state": "completed",
  "created": "2022-06-27T13:00:25-07:00",
  "updated": "2022-06-27T13:01:08-07:00",
  "result": {
    "self": "/organizations/sense-staging-test/environments/local/securityReports/bd2f4fe0-a906-44c2-8dcb-2c618e4b565d/result",
    "expires": "2022-07-04T13:01:08-07:00"
  },
  "resultRows": "848",
  "resultFileSize": "5.10 KB",
  "executionTime": "43 seconds",
  "queryParams": {
    "metrics": [
      "name:bot,func:count_distinct,alias:count_distinct_bot,op:,val:",
      "name:bot_traffic,func:sum,alias:sum_bot_traffic,op:,val:"
    ],
    "dimensions": [
      "ax_resolved_client_ip"
    ],
    "startTimestamp": "2022-06-20T20:00:25.098237292Z",
    "endTimestamp": "2022-06-27T20:00:25.098237292Z",
    "mimeType": "json",
    "timeUnit": "minute"
  },
  "displayName": "Sample Query Bot"
}

获取报告

如需下载安全报告,请发送如下请求:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID/result" \
       -X GET -O -J \
       -H "Authorization: Bearer $TOKEN"

其中 REPORT_ID 是报告 ID。请参阅 API 调用示例中的参数

这将返回一个包含报告的文件,其名称的格式为 OfflineQueryResult-{ID}.zip。如需查看报告,请执行以下操作:

  1. 解压缩 OfflineQueryResult-{ID}.zip
  2. 输入 gzip -d QueryResults-{ID}*.json.gz
  3. 输入 cat QueryResults-{ID}*.json
  4. .

机器人流量示例

以下示例创建一个 bot_traffic 报告:

{
  "dimensions": [
    "bot_reason"
  ],
   "metrics": [
    {
      "aggregation_function": "sum",
      "name": "bot_traffic"
    }
  ],
  "groupByTimeUnit": "minute",
  "timeRange": "last7days"
}

查询具有以下参数:

  • 指标:bot_traffic。这是每隔一分钟已确定为机器人来源的 IP 地址发出的请求总数。

    请参阅指标和聚合函数

  • 维度:bot_reasonbot_reason 可以是机器人的检测规则的任意组合。 检测到机器人时,bot_reason 包含机器人流量模式匹配的检测规则的子集。

    请参阅维度

  • 过滤条件:environment
  • groupByTimeUnit:minute
  • timeRange:last7days

请注意,此 API 调用会返回与使用 Apigee 界面创建的机器人 IP 地址报告示例相同的报告。

聊天机器人检测数据延迟

聊天机器人检测的处理延迟时间平均约为 15 到 20 分钟。

为环境组创建安全报告

使用安全报告 API,您可以为环境组(而不仅仅是环境)中的数据创建报告。为此,请输入如下命令:

curl "https://apigee.googleapis.com/v1/organizations/ORG/hostSecurityReports" \
       -X POST -d @./Query.json \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

并确保查询模板 Query.json 包含以下行:

"envgroup_hostname": "ENVGROUP"

其中,ENVGROUP 是包含环境的环境组的名称。您可以通过在 Apigee 界面中转到管理 > 环境 > 组找到环境组的名称。

备注:

  • 环境组级报告 API 仅支持具有聚合函数 sum 的指标 message_count
  • 环境组级报告 API 不支持维度 bot_reasonincident_id,但支持安全报告的所有其他维度

获取报告状态

如需获取报告的状态,请输入如下所示的命令:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID" \
       -X GET  -H 'Content-type: application/json' -i \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

该方法返回报告请求的摘要和报告的当前状态。以下是示例响应:

{
  "self": "/organizations/ngsaas-runtime-staging/environments/test/securityReports/3964675e-9934-4398-bff5-39dd93a67201",
  "state": "completed",
  "created": "2021-08-06T15:28:28-07:00",
  "updated": "2021-08-06T15:28:40-07:00",
  "result": {
    "self": "/organizations/ngsaas-runtime-staging/environments/test/securityReports/3964675e-9934-4398-bff5-39dd93a67201/result",
    "expires": "2021-08-13T15:28:40-07:00"
  },
  "resultRows": "60",
  "resultFileSize": "0.31 KB",
  "executionTime": "11 seconds",
  "queryParams": {
    "metrics": [
      "name:message_count,func:sum,alias:sum_message_count,op:,val:"
    ],
    "dimensions": [
      "apiproxy"
    ],
    "startTimestamp": "2021-08-06T21:28:28.570770570Z",
    "endTimestamp": "2021-08-06T22:28:28.570770570Z",
    "mimeType": "json",
    "timeUnit": "minute"
  }
}

由于状态为 "completed",因此您现在可以查看报告,如下所述。

查看安全报告

如需查看安全报告,请输入如下所示的命令:

curl "https://apigee.googleapis.com/v1/organizations/ORG/hostSecurityReports/REPORT_ID/result" \
       -X GET -O -J \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

这将返回一个包含报告的文件,其名称的格式为 OfflineQueryResult-{ID}.zip。如需查看报告,请执行以下操作:

  1. 解压缩 OfflineQueryResult-{ID}.zip
  2. 输入 gzip -d QueryResults-{ID}*.json.gz
  3. 输入 cat QueryResults-{ID}*.json
  4. .

指标和聚合函数

您可以将以下指标和聚合函数用于报告来计算指标的统计信息。

指标 说明 Aggregation function
bot 每隔一分钟检测到的机器人的不同 IP 地址数量。 count_distinct
bot_traffic 每隔一分钟检测到的机器人 IP 地址发出的消息数量。 sum
message_count

Apigee 每隔一分钟处理的 API 调用总数。

注意message_count 不能与同一报告中的其他指标结合使用。

sum
response_size 返回的响应载荷大小(以字节为单位)。 sumavgminmax
bot_first_detected 首次检测到机器人的日期和时间。只能通过 API 获得。 min
bot_last_detected 上次检测到机器人的日期和时间。只能通过 API 获得。max

维度

利用维度,您可以根据相关的数据子集将指标值归为一组。下表介绍了 Advanced API Security 特有的维度:

维度 说明
bot_reason 可以是安全检测规则的任意组合。 bot_reason 包含机器人流量模式匹配的检测规则的子集。

incident_id(预览) 安全事件的 UUID,由调用 Incidents API 返回。 请参阅“示例:获取详细信息或特定突发事件”
security_action 安全操作。可能的值包括 ALLOWDENYFLAG
security_action_name 安全操作的名称。
security_action_headers 可用于查询标志安全操作的标头。

注意bot_reasonincident_id 仅适用于以下指标:

  • bot
  • bot_traffic
  • response_size

除了上述维度之外,Advanced API Security 还支持以下维度

  • access_token
  • api_product
  • apiproxy
  • ax_dn_region
  • ax_edge_execution_fault_code
  • ax_geo_city
  • ax_geo_continent
  • ax_geo_country
  • ax_geo_region
  • ax_isp
  • ax_resolved_client_ip
  • ax_ua_agent_family
  • ax_ua_agent_type
  • ax_ua_agent_version
  • ax_ua_agent_category
  • ax_ua_os_family
  • bot_reason
  • client_id
  • developer
  • developer_app
  • developer_email
  • envgroup_hostname
  • environment
  • incident_id(预览)
  • proxy_basepath
  • proxy_pathsuffix
  • request_uri
  • request_verb
  • response_status_code
  • target_host
  • target_url
  • useragent

安全报告的限制

请参阅安全报告的限制