Mengelola laporan keamanan menggunakan API

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Halaman ini menjelaskan cara membuat dan melihat laporan keamanan menggunakan API laporan keamanan.

Untuk mengetahui ringkasan laporan keamanan, termasuk batasan, lihat Ringkasan laporan keamanan. Untuk dokumentasi referensi API untuk laporan keamanan, lihat Referensi API laporan keamanan.

Catatan: Data yang masuk ke pipeline Apigee Analytics memiliki penundaan rata-rata hingga 15 hingga 20 menit. Akibatnya, laporan keamanan yang waktu berakhirnya kurang dari 20 menit yang lalu mungkin menampilkan hasil yang salah.

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. Total jumlah 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 untuk informasi dimensi yang didukung.
  • 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 diperluas ke masa lalu. Opsi yang tersedia: 
    "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"
}

Respons 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 ini 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 contoh panggilan API.

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

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

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 berbentuk OfflineQueryResult-{ID}.zip. Untuk melihat laporan:

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