보안 통계 API

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

보안 통계 API를 사용하면 지난 14일 동안의 악용 및 봇 관련 통계를 볼 수 있습니다. 보안 통계에는 두 가지 유형이 있습니다.

시간 측정기준이 없는 테이블 형식 통계 테이블 형식 통계는 주로 집계 함수(예: sum for message_count 또는 bot_traffic)를 사용하여 계산됩니다.
시간 측정기준이 있는 시계열 통계

참고: 봇 감지에는 평균적으로 약 15~20분 정도의 처리 지연이 발생합니다.

API 호출 예시의 매개변수

다음 섹션에서는 보안 상태 API를 사용하는 API 호출의 예시를 보여줍니다. API 호출에는 다음 매개변수가 포함됩니다.

ORG: 내 조직
ENV: 내 환경
METRIC_i: 통계 측정항목. 측정항목 및 집계 함수를 참조하세요.
AGGREGATION_i: 측정항목의 집계 함수. 아래의 표를 참조하세요.
DIMENSION_i: 통계 값을 그룹화하는 측정기준
PAGE_SIZE: 단일 페이지에서 반환되는 최대 하위 구성요소 수
time_range: 양식의 통계 기간
```
"time_range": {
    "start_time": START_TIME,
    "end_time": END_TIME
}
```
각 매개변수는 다음과 같습니다.
- START_TIME은 기간의 시작 시간입니다.
- END_TIME은 기간의 종료 시간입니다.
START_TIME과 END_TIME은 "YYYY-MM-DDT00:00:00Z" 형식입니다.

기간 길이는 최대 14일까지 가능하고 시작 날짜와 종료 날짜 모두 이전 365일 이내에 있어야 합니다.

예시: 환경의 테이블 형식 보안 통계 쿼리

테이블 형식 통계를 쿼리하는 요청의 형식은 다음과 같습니다.

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1",
                      {"metric": "METRIC_2", "aggregation": "AGGREGATION_2"}],
          "dimensions": ["DIMENSION_1",  "DIMENSION_2"],
          "page_size": PAGE_SIZE,
          "time_range": {
              "start_time": START_TIME,
              "end_time": END_TIME
          }
        }'

예시 API 호출의 매개변수를 참조하세요.

요청에 포함할 수 있는 최대 측정항목 수, 집계 함수, 측정기준은 보안 통계 제한사항을 참조하세요.

다음은 테이블 형식 통계를 쿼리하는 요청의 예시입니다.

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "bot", "aggregation": "count_distinct"},
                      {"metric": "bot_traffic", "aggregation": "sum"},
                      {"metric": "bot_first_detected", "aggregation": "min"},
                      {"metric": "bot_last_detected", "aggregation": "max"}],
          "dimensions": ["apiproxy",  "bot_reason", "ax_resolved_client_ip",  "ax_geo_city",  "ax_geo_country",  "client_id",  "proxy_basepath", "proxy_pathsuffix"],
          "page_size": 1,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

요청 및 응답에 대한 설명은 queryTabularStats 참조 페이지를 참조하세요.

예시: 환경의 시계열 보안 통계 쿼리

시계열 API는 선택한 측정항목의 시계열 통계를 선택한 측정기준별로 그룹화하여 반환합니다.

다음 호출은 API 프록시별로 그룹화된 봇 트래픽의 시계열 통계를 호출합니다. 프록시가 4개 있으므로 시계열 지점 4개가 순서대로 생성됩니다. 각 행의 지점 순서는 열 필드의 해당 색인과 일치합니다.

샘플 요청은 다음과 같습니다.

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTimeSeriesStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1", "order": "ORDER"}],
          "dimensions": ["DIMENSION_1"], "window_size": "WINDOW_SIZE",
          "page_size": PAGE_SIZE,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

예시 API 호출의 매개변수를 참조하세요.

요청 및 응답에 대한 설명은 queryTabularStats 참조 페이지를 참조하세요.

예시: 악용 감지를 위한 이슈 세부정보 쿼리

다음 예시에서는 지능화된 API 보안의 악용 감지를 위한 이슈 세부정보를 쿼리합니다. 이 호출은 지정된 이슈에 대한 developer_app의 봇 수 세부정보를 반환합니다.

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST -d  \
       '{"metrics": [{"metric": "bot_traffic", "aggregation": "sum"}],
         "dimensions": ["incident_id", "developer_app"],
          "filter": "incident_id eq '\''d897d1af-51ac-4b5d-a29e-d1059d922a05'\''",
          "page_size": 100,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

예시 API 호출의 매개변수를 참조하세요.

그러면 다음과 같은 응답이 반환됩니다.

{
  "values": [
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer2_App1",
      18353
    ],
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer1_App1",
      18082
    ]
  ],
  "columns": [
    "incident_id",
    "developer_app",
    "bot_traffic"
  ]
}

요청 및 응답에 대한 설명은 queryTabularStats 참조 페이지를 참조하세요.

측정항목 및 집계 함수

다음 표에서는 보안 통계 API에서 사용할 수 있는 측정항목과 집계 함수를 설명합니다.

`Metric`	설명	`Aggregation function`
`bot`	1분 간격으로 감지된 봇의 개별 IP 주소 수입니다.	`count_distinct`
`bot_first_detected`	봇이 처음 감지된 날짜 및 시간입니다. API를 통해서만 제공됩니다.	`min`
`bot_last_detected`	봇이 마지막으로 감지된 날짜 및 시간입니다. API를 통해서만 제공됩니다.	`max`
`bot_traffic`	1분 간격으로 감지된 봇의 IP 주소에서 전송된 메시지 수입니다.	`sum`
`message_count`	Apigee에서 1분 간격으로 처리된 총 API 호출 수입니다. 참고: `message_count`는 동일한 보고서에서 다른 측정항목과 함께 사용할 수 없습니다.	`sum`
`response_size`	응답의 크기입니다.	`average`, `max`, `min`, `sum`

측정기준

측정기준을 사용하면 데이터의 관련된 하위 집합을 기준으로 측정항목 값을 그룹으로 묶을 수 있습니다. 다음 표에서는 지능화된 API 보안 보고서와 관련된 측정기준을 설명합니다.

측정기준	설명
`bot_reason`	보안 감지 규칙의 조합이 될 수 있습니다. `bot_reason`은 봇의 트래픽 패턴과 일치하는 감지 규칙의 하위 집합으로 구성됩니다.
`incident_id`(미리보기)	Incidents API에 대한 호출로 반환되는 보안 사고의 UUID입니다. 예시: 세부정보 또는 특정 이슈 가져오기를 참조하세요.
`security_action`	보안 작업. 가능한 값은 `ALLOW`, `DENY` 또는 `FLAG`입니다.
`security_action_name`	보안 작업의 이름입니다.
`security_action_headers`	플래그 보안 작업을 쿼리하는 데 사용할 수 있는 헤더입니다.

참고: bot_reason 및 incident_id는 다음 측정항목에서만 작동합니다.

bot
bot_traffic
response_size

지능화된 API 보안은 위에 설명된 측정기준 외에 다음 측정기준도 지원합니다.

access_token
access_token
api_product
apiproxy
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_version
client_id
developer
developer_app
developer_email
environment
proxy_basepath
proxy_pathsuffix
request_uri
response_status_code
target_url
useragent

보안 통계 제한사항

보안 통계 API(테이블 형식 및 시계열 모두)에는 다음과 같은 한도가 적용됩니다.

최대 페이지 크기: 14400
시계열 측정기준 최대 10개
테이블 형식 통계 측정기준 최대 15개
측정항목 집계 최대 5개
시계열 측정항목 집계 최대 5개
기간: 길이는 최대 14일까지 가능하고 시작 날짜와 종료 날짜 모두 이전 365일 이내에 있어야 합니다.
incident_id 및 bot_reason 측정기준은 message_count 또는 response_size 측정항목에 사용할 수 없습니다.

보안 통계 API와 보안 보고서 API 비교

보안 통계 API와 보안 보고서 API 모두 악용 및 봇 관련 보안 통계를 반환하지만 다음과 같은 차이점이 있습니다.

보안 통계 API는 최근 API 트래픽에 대한 통계를 볼 수 있도록 설계되었습니다. 보안 통계 API의 데이터는 14일 전으로만 돌아가지만 요청을 전송하는 즉시 통계를 볼 수 있습니다.

보안 통계는 Apigee UI의 악용 측정항목 뷰에도 표시됩니다.
보안 보고서 API는 장기 실행 작업에 대한 통계를 볼 수 있도록 설계되었습니다. 보안 점수 API를 사용하려면 작업을 제출하고 작업이 완료된 경우에만 결과를 봅니다. 보안 점수 API의 데이터는 1년 전으로 돌아갑니다.