보안 보고서 API

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

Apigee UI에서 보안 보고서를 사용하는 것 외에도 보안 보고서 API를 통해 모든 보안 보고서 기능에 액세스할 수 있습니다. 이 섹션에서는 보안 보고서 API를 사용하는 방법을 설명합니다.

참고: Apigee Analytics 파이프라인으로 들어가는 데이터는 평균적으로 최대 15~20분 정도까지 지연됩니다. 따라서 종료 시간이 과거 시점에서 20분 미만인 보고서를 만들면 잘못된 결과가 발생할 수 있습니다.

API 호출 예시의 매개변수

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

ORG는 사용자의 조직입니다.
ENV는 보고서를 계산할 환경입니다.
ENVGROUP은 환경이 포함된 환경 그룹입니다.
REPORT_ID는 보안 보고서를 만들기 위한 호출로 반환되는 보고서 ID입니다.
$TOKEN은 OAuth 액세스 토큰의 환경 변수입니다.
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 UI를 사용하여 만든 봇 IP 주소 보고서 예시와 동일한 보고서를 반환합니다.

기간

보고서의 기간입니다. 다음 방법 중 하나로 timeRange 필드를 설정할 수 있습니다.

보고서를 확장할 과거 기간을 지정합니다. 옵션은 다음과 같습니다.
```
"timeRange": "{last60minutes/last24hours/last7days}"
```
보고서의 시작 및 종료 시간을 다음 형식으로 지정합니다.
```
"timeRange": {
        "start": "YYYY-MM-DDT00:00:00Z",
        "end": "YYYY-MM-DDT00:00:00Z"
        }
```
start와 end는 둘 다 과거여야 하며 보고서를 만드는 현재 시점에서 최대 1년 전이어야 합니다.

샘플 응답

위 쿼리는 다음과 같은 응답을 반환합니다.

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

응답에 다음이 포함됩니다.

완료된 후 보고서를 가져오는 데 사용할 수 있는 보고서 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 형식인 보고서가 포함된 파일이 반환됩니다. 보고서를 보려면 다음을 따르세요.

OfflineQueryResult-{ID}.zip의 압축을 풉니다.
gzip -d QueryResults-{ID}*.json.gz를 입력합니다.
cat QueryResults-{ID}*.json 입력

봇 트래픽 예시

다음 예시에서는 bot_traffic에 대해 보고서를 만듭니다.

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

쿼리에는 다음과 같은 매개변수가 있습니다.

측정항목: bot_traffic. 봇 소스로 식별된 IP 주소의 총 요청 수입니다(1분 간격).

측정항목 및 집계 함수를 참조하세요.
측정기준: bot_reason. bot_reason은 봇에 대한 감지 규칙의 모든 조합일 수 있습니다. 봇이 감지되면 bot_reason은 봇의 트래픽 패턴과 일치한 감지 규칙의 하위 집합으로 구성됩니다.

측정기준을 참조하세요.
필터: environment.
groupByTimeUnit: minute
timeRange: last7days

참고로 이 API 호출은 Apigee UI를 사용하여 만든 봇 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 UI에서 관리자 > 환경 > 그룹으로 이동하여 환경 그룹의 이름을 찾을 수 있습니다.

참고:

환경 그룹 수준 Report API는 집계 함수 sum이 있는 message_count 측정항목만 지원합니다.
환경 그룹 수준의 Report API는 측정기준 bot_reason 또는 incident_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 형식인 보고서가 포함된 파일이 반환됩니다. 보고서를 보려면 다음을 따르세요.

OfflineQueryResult-{ID}.zip의 압축을 풉니다.
gzip -d QueryResults-{ID}*.json.gz를 입력합니다.
cat QueryResults-{ID}*.json 입력

측정항목 및 집계 함수

사용자는 보고서에 대해 측정항목을 계산하는 다음 측정항목과 집계 함수를 사용할 수 있습니다.

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

측정기준

측정기준을 사용하면 데이터의 관련된 하위 집합을 기준으로 측정항목 값을 그룹으로 묶을 수 있습니다. 다음 표에서는 지능화된 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
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

보안 보고서 제한사항

보안 보고서 제한사항을 참조하세요.