Halaman ini diterjemahkan oleh Cloud Translation API.

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 API laporan keamanan.

Catatan: Data yang mengalir ke pipeline Apigee Analytics memiliki keterlambatan rata-rata hingga 15 hingga 20 menit. Akibatnya, laporan keamanan dengan waktu berakhir kurang dari 20 menit di masa 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 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.

{
  "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. 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 berdasarkan 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 ke masa lalu. 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 dapat maksimal 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 hal berikut:
- 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: Tugas laporan telah berakhir masa berlakunya, dan Anda tidak dapat lagi melihat laporan tersebut.

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.

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

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

Ekstrak 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 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
timeRange: last7days

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

Keterlambatan data deteksi bot

Deteksi bot memiliki keterlambatan 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.
Report API 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 berikutnya.

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:

Ekstrak 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 selama interval satu menit.	`count_distinct`
`bot_traffic`	Jumlah pesan dari alamat IP bot yang terdeteksi selama 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 kali terdeteksi. Hanya tersedia melalui API.	`max`

Dimensi

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

Dimensi	Deskripsi
`bot_reason`	Dapat berupa kombinasi dari aturan deteksi keamanan apa pun. `bot_reason` terdiri dari subset aturan deteksi yang cocok dengan pola traffic bot.
`incident_id` (pratinjau)	UUID untuk insiden keamanan, yang ditampilkan oleh 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 Anda gunakan untuk membuat kueri tindakan keamanan flag.

Catatan: bot_reason dan incident_id hanya berfungsi dengan metrik berikut:

bot
bot_traffic
response_size

Selain dimensi yang dijelaskan di atas, Keamanan API Lanjutan 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.