보안 보고서 API

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

Apigee Edge 문서 보기

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 형식인 보고서가 포함된 파일이 반환됩니다. 보고서를 보려면 다음을 따르세요.

  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 주소의 총 요청 수입니다(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에서 관리자 > 환경 > 그룹으로 이동하여 환경 그룹의 이름을 찾을 수 있습니다.

참고:

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

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

측정항목 및 집계 함수

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

측정항목 설명 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

보안 보고서 제한사항

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