Security reports API

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Selain menggunakan laporan keamanan di UI Apigee, Anda juga dapat mengakses semua fitur laporan keamanan melalui API laporan keamanan. Bagian ini menjelaskan cara menggunakan Security Reports API.

Parameter dalam contoh panggilan API

Bagian berikut memberikan contoh panggilan API yang menggunakan API laporan keamanan. Panggilan API berisi parameter berikut:

• ORG adalah organisasi Anda.
• ENV adalah lingkungan tempat Anda ingin laporan dihitung.
• ENVGROUP adalah grup lingkungan yang berisi lingkungan.
• REPORT_ID adalah ID laporan yang ditampilkan oleh panggilan ke buat laporan keamanan.
• $TOKEN adalah variabel lingkungan untuk token akses OAuth.
• timeRange adalah rentang waktu untuk laporan.

Membuat laporan keamanan

Untuk membuat laporan keamanan, masukkan perintah seperti berikut:

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"

dengan Query.json adalah template kueri yang menentukan kueri. Contoh template kueri ditampilkan di bawah.

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

Kueri memiliki parameter berikut:

• Metrik:

  • bot. Metrik ini menghitung jumlah alamat IP berbeda yang telah diidentifikasi sebagai sumber bot.

    Fungsi agregasi: count_distinct

  • bot_traffic. Jumlah total permintaan dari alamat IP yang merupakan sumber bot.

    Fungsi agregasi: sum

  Lihat Fungsi metrik dan agregasi.

• Dimensi: ax_resolved_client_ip. Opsi ini mengelompokkan jumlah bot dalam laporan menurut alamat IP sumbernya.

  Lihat Dimensi.

• Filter: environment.
• groupByTimeUnit: minute
• timeRange: last7days. Lihat Rentang waktu.

Perhatikan bahwa panggilan API ini menampilkan laporan yang sama dengan contoh laporan alamat IP bot yang dibuat menggunakan UI Apigee.

Rentang waktu

Rentang waktu untuk laporan. Anda dapat menetapkan kolom timeRange dengan salah satu cara berikut:

• Tentukan berapa lama laporan harus diperpanjang. Opsinya adalah:

  "timeRange": "{last60minutes/last24hours/last7days}"

• Tentukan waktu mulai dan berakhir untuk laporan dalam format berikut:

  "timeRange": {
          "start": "YYYY-MM-DDT00:00:00Z",
          "end": "YYYY-MM-DDT00:00:00Z"
          }

  start dan end harus berada di masa lalu, dan paling banyak 1 tahun sebelum saat ini saat Anda membuat laporan.

Contoh respons

Kueri di atas akan menampilkan respons seperti berikut:

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

Responsnya berisi hal berikut:

• ID laporan, yang dapat Anda gunakan untuk mendapatkan laporan setelah selesai. Pada contoh di atas, ID laporan adalah 3964675e-9934-4398-bff5-39dd93a67201.
• "state": Status tugas laporan, yang dapat berupa salah satu dari berikut ini:
  • enqueued: Tugas laporan baru saja dibuat, tetapi belum berjalan.
  • running: Tugas laporan sedang berjalan.
  • completed: Tugas pelaporan selesai. Pada tahap ini, Anda dapat melihat laporan.
  • expired: Masa berlaku tugas laporan telah berakhir, dan Anda tidak dapat lagi melihat laporan.

Mendapatkan status laporan

Untuk mendapatkan status laporan, kirim permintaan seperti berikut:

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"

dengan REPORT_ID adalah ID laporan. Lihat Parameter dalam panggilan API contoh.

Respons berisi ringkasan parameter laporan, serta status laporan saat ini. Dalam contoh ini, statusnya adalah "completed", sehingga Anda dapat melihat hasil laporan.

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

Baca laporannya

Untuk mendownload laporan keamanan, kirim permintaan seperti berikut:

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

dengan REPORT_ID adalah ID laporan. Lihat Parameter dalam panggilan API contoh.

Tindakan ini akan menampilkan file yang berisi laporan, yang namanya dalam bentuk OfflineQueryResult-{ID}.zip. Untuk melihat laporan:

1. Buka zip OfflineQueryResult-{ID}.zip.
2. Masukkan gzip -d QueryResults-{ID}*.json.gz.
3. Masukkan cat QueryResults-{ID}*.json
.

Contoh traffic bot

Contoh berikut membuat laporan tentang bot_traffic:

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

Kueri memiliki parameter berikut:

• Metrik: bot_traffic. Ini adalah jumlah total permintaan dari alamat IP yang telah diidentifikasi sebagai sumber bot, dalam interval satu menit.

  Lihat Fungsi metrik dan agregasi.

• Dimensi: bot_reason. bot_reason dapat berupa kombinasi aturan deteksi untuk bot. Jika bot terdeteksi, bot_reason terdiri dari subset aturan deteksi yang cocok dengan pola traffic bot.

  Lihat Dimensi.

• Filter: environment.
• groupByTimeUnit: minute
• timeRange: last7days

Perhatikan bahwa panggilan API ini menampilkan laporan yang sama dengan contoh laporan alamat IP bot yang dibuat menggunakan UI Apigee.

Penundaan data deteksi bot

Deteksi bot memiliki penundaan pemrosesan rata-rata sekitar 15 hingga 20 menit.

Membuat laporan keamanan untuk grup lingkungan

Dengan menggunakan Security Reports API, Anda dapat membuat laporan untuk data dalam grup lingkungan (bukan hanya lingkungan). Untuk melakukannya, masukkan perintah seperti berikut:

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

dan pastikan template kueri, Query.json, berisi baris berikut:

"envgroup_hostname": "ENVGROUP"

dengan ENVGROUP adalah nama grup lingkungan yang berisi lingkungan. Anda dapat menemukan nama grup lingkungan di UI Apigee dengan membuka Admin > Environments > Groups.

Catatan:

• Report API tingkat grup lingkungan hanya mendukung metrik message_count dengan fungsi agregasi sum.
• API Laporan tingkat grup lingkungan tidak mendukung dimensi bot_reason atau incident_id, tetapi mendukung semua dimensi lainnya untuk laporan keamanan.

Mendapatkan status laporan

Untuk mendapatkan status laporan, masukkan perintah seperti berikut:

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"

Tindakan ini akan menampilkan ringkasan permintaan laporan, dan status laporan saat ini. Berikut adalah contoh respons:

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

Karena statusnya adalah "completed", Anda kini dapat melihat laporan, seperti yang dijelaskan selanjutnya.

Melihat laporan keamanan

Untuk melihat laporan keamanan, masukkan perintah seperti berikut:

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"

Tindakan ini akan menampilkan file yang berisi laporan, yang namanya dalam bentuk OfflineQueryResult-{ID}.zip. Untuk melihat laporan:

1. Buka zip OfflineQueryResult-{ID}.zip.
2. Masukkan gzip -d QueryResults-{ID}*.json.gz.
3. Masukkan cat QueryResults-{ID}*.json
.

Metrik dan fungsi agregasi

Anda dapat menggunakan metrik dan fungsi agregasi berikut, yang menghitung statistik dari metrik, untuk laporan.

Dimensi

Dimensi memungkinkan Anda mengelompokkan nilai metrik berdasarkan subkumpulan data terkait. Tabel berikut menjelaskan dimensi yang khusus untuk Keamanan API Tingkat Lanjut:

Catatan: bot_reason dan incident_id hanya berfungsi dengan metrik berikut:

• bot
• bot_traffic
• response_size

Selain dimensi yang dijelaskan di atas, Keamanan API Tingkat Lanjut juga mendukung dimensi berikut:

• 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 (pratinjau)
• proxy_basepath
• proxy_pathsuffix
• request_uri
• request_verb
• response_status_code
• target_host
• target_url
• useragent

Batasan pada laporan keamanan

Lihat Batasan pada laporan keamanan.