Halaman ini diterjemahkan oleh Cloud Translation API.

API laporan keamanan

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca 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.

Catatan: Data yang mengalir ke pipeline Analytics Apigee rata-rata mengalami keterlambatan hingga 15 hingga 20 menit. Akibatnya, laporan keamanan dengan waktu berakhir kurang dari 20 menit yang lalu mungkin menampilkan hasil yang salah.

Parameter dalam contoh panggilan API

Bagian berikut memberikan contoh panggilan API yang menggunakan Security reports API. Panggilan API berisi parameter berikut:

ORG adalah organisasi Anda.
ENV adalah lingkungan tempat Anda ingin menghitung laporan.
ENVGROUP adalah grup lingkungan yang berisi lingkungan.
REPORT_ID adalah ID laporan yang ditampilkan oleh panggilan untuk membuat 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 ini.

{
  "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. Metode 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 Metrik dan fungsi agregasi.
Dimensi: ax_resolved_client_ip. Tindakan ini mengelompokkan jumlah bot dalam laporan menurut alamat IP sumbernya.
Lihat Dimensi.
Filter: environment.
groupByTimeUnit: minute
rentangwaktu: last7days. Lihat Rentang waktu.

Perhatikan bahwa panggilan API ini akan 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 batas waktu laporan harus diperpanjang. 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 dapat berlangsung maksimal 1 tahun sebelum masa sekarang saat Anda membuat laporan.

Contoh respons

Kueri di atas mengembalikan 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 hal berikut:
- enqueued: Tugas laporan baru saja dibuat, tetapi belum berjalan.
- running: Tugas laporan sedang berjalan.
- completed: Tugas laporan selesai. Pada tahap ini, Anda dapat melihat laporan.
- expired: Tugas laporan telah kedaluwarsa, 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 sebagai ID laporan. Lihat Parameter dalam contoh panggilan API.

Responsnya akan 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 sebagai ID laporan. Lihat Parameter dalam contoh panggilan API.

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

Ekstrak file OfflineQueryResult-{ID}.zip.
Masukkan gzip -d QueryResults-{ID}*.json.gz.
Masukkan cat QueryResults-{ID}*.json

Contoh traffic bot

Contoh berikut membuat laporan di 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 Metrik dan fungsi agregasi.
Dimensi: bot_reason. bot_reason dapat berupa kombinasi apa pun dari aturan deteksi untuk bot. Saat bot terdeteksi, bot_reason terdiri dari subset aturan deteksi yang cocok dengan pola traffic bot.

Lihat Dimensi.
Filter: environment.
groupByTimeUnit: minute
Rentangwaktu: last7days

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

Penundaan data deteksi bot

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

Membuat laporan keamanan untuk grup lingkungan

Dengan 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 level 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 sekarang 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 berformat OfflineQueryResult-{ID}.zip. Untuk melihat laporan:

Ekstrak file OfflineQueryResult-{ID}.zip.
Masukkan gzip -d QueryResults-{ID}*.json.gz.
Masukkan cat QueryResults-{ID}*.json

Metrik dan fungsi agregasi

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

Metrik	Deskripsi	`Aggregation function`
`bot`	Jumlah alamat IP yang berbeda untuk bot yang terdeteksi dalam interval satu menit.	`count_distinct`
`bot_traffic`	Jumlah pesan dari alamat IP bot yang terdeteksi dalam interval satu menit.	`sum`
`message_count`	Jumlah total panggilan API yang diproses oleh Apigee dalam interval satu menit. Catatan: `message_count` tidak dapat digunakan dengan metrik lain dalam laporan yang sama.	`sum`
`response_size`	Ukuran payload respons yang ditampilkan dalam byte.	`sum`, `avg`, `min`, `max`
`bot_first_detected`	Tanggal dan waktu bot pertama kali terdeteksi. Hanya tersedia melalui API.	`min`
`bot_last_detected`	Tanggal dan waktu bot terakhir terdeteksi. Hanya tersedia melalui API.	`max`

Dimensi

Dimensi memungkinkan Anda mengelompokkan nilai metrik berdasarkan subkumpulan data yang terkait. Tabel berikut menjelaskan dimensi yang dikhususkan untuk Advanced API Security:

Dimensi	Deskripsi
`bot_reason`	Dapat berupa kombinasi dari aturan deteksi keamanan. `bot_reason` terdiri dari subset aturan deteksi yang cocok dengan pola traffic bot.
`incident_id` (pratinjau)	UUID untuk insiden keamanan, yang ditampilkan melalui panggilan ke Incidents API. Lihat Contoh: Mendapatkan detail atau insiden tertentu.
`security_action`	Tindakan keamanan. Nilai yang mungkin adalah `ALLOW`, `DENY`, atau `FLAG`.
`security_action_name`	Nama tindakan keamanan.
`security_action_headers`	Header yang dapat digunakan untuk mengkueri tindakan keamanan tanda.

Catatan: bot_reason dan incident_id hanya berfungsi dengan metrik berikut:

bot
bot_traffic
response_size

Selain dimensi yang dijelaskan di atas, Advanced API Security 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 laporan keamanan.