Mengelola aturan terpadu dengan Rules API

Didukung di:

Rules API menyediakan endpoint terprogram untuk mengelola aturan kustom dan aturan pilihan. Dokumen ini menguraikan cara menggunakan Rules API untuk mengelola aturan kustom dan aturan pilihan secara terprogram.

Gunakan Rules API untuk melakukan tugas berikut:

  • Menelusuri dan mencantumkan aturan: Menjalankan penelusuran terstruktur, mengurutkan hasil, dan mengambil resource aturan yang diperluas.

  • Melihat detail aturan pilihan: Mengambil metadata hanya baca, tag yang diterapkan, dan logika teks mentah untuk aturan yang dibuat oleh Google.

  • Mengubah konfigurasi aturan secara batch: Memperbarui status aktif, status pemberitahuan, status arsip, dan penetapan tag secara sinkron di beberapa aturan.

Menelusuri aturan menggunakan aturan daftar

Metode rules.list mendukung resource aturan yang diperluas dan penelusuran terstruktur. Untuk membuat kueri resource mendetail ini, gunakan salah satu tampilan berikut:

  • CONFIG_ONLY

  • TRENDS

Kedua tampilan memberikan informasi yang diperluas, yang mencakup hal berikut:

  • Informasi deployment aturan (pengaktifan aturan aktif, pengaktifan pemberitahuan, status diarsipkan, status eksekusi)

  • Tag aturan terkait

  • Akses ke resource aturan pilihan dalam tampilan CONFIG_ONLY

  • Ukuran halaman yang lebih besar,yaitu 5.000 hasil dalam tampilan CONFIG_ONLY

  • Kemampuan penelusuran terstruktur yang andal.

Urutkan hasil penelusuran di kolom resource aturan menggunakan order_by dalam permintaan rules.list. Kolom aturan berikut didukung:

  • alerting_enabled

  • archived

  • author

  • create_time

  • display_name

  • execution_state

  • live_mode_enabled

  • revision_create_time

  • rule_id

  • rule_owner

  • severity

  • type

  • update_time

Contoh permintaan:

HTTP

GET https://chronicle.googleapis.com/v1alpha/projects/<ID>/locations/us/instances/<ID>/rules?filter=archived%3Dfalse&pageSize=100&pageToken=&view=TRENDS

Contoh respons:

JSON

{
  "rules": [
    {
      "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ru_fd3fe28c-2d7b-4f7e-9fca-4fdd6029d228",

      "revisionId": "v_1719339990_701951000",

      "displayName": "SomaMaglevProberRule",

      "author": "test@google.com",

      "metadata": {
        "description": "enabled live rule used for maglev rules latency prober"

      },

      "createTime": "2024-06-25T18:26:30.701951Z",

      "revisionCreateTime": "2024-06-25T18:26:30.701951Z",

      "type": "SINGLE_EVENT",

      "etag": "CNaX7LMGEJjY284C",

      "nearRealTimeLiveRuleEligible": true,

      "ruleOwner": "CUSTOMER",

      "alertingEnabled": true,

      "liveModeEnabled": true,

      "runFrequency": "LIVE",

      "currentDayDetectionCount": 10000,

      "executionState": "DEFAULT"

    },
    {
      "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ru_fbf56bf1-ea5f-4b5b-bbe9-e91e13f3b3b3",

      "revisionId": "v_1696452642_197471000",

      "displayName": "LoadTestingRule",

      "author": "loadtesting@google.com",

      "createTime": "2023-10-04T20:50:42.197471Z",

      "revisionCreateTime": "2023-10-04T20:50:42.197471Z",

      "type": "SINGLE_EVENT",

      "etag": "CKKg96gGEJjWlF4=",

      "nearRealTimeLiveRuleEligible": true,

      "ruleOwner": "CUSTOMER",

      "alertingEnabled": true,

      "liveModeEnabled": true,

      "runFrequency": "LIVE",

      "executionState": "DEFAULT"
    }
  ]
}

Melihat detail aturan pilihan menggunakan getRule dan listRules

rules.getRule dan rule.listRules mendukung pengambilan detail untuk aturan pilihan. Respons rule.listRules dapat difilter hanya untuk aturan pilihan menggunakan filter rule_owner: "GOOGLE". Detail selengkapnya tentang penggunaan filter rule_owner dapat ditemukan di bagian sintaksis penelusuran aturan.

Contoh permintaan listRules untuk membaca aturan pilihan:

HTTP

GET https://chronicle.googleapis.com/v1alpha/projects/<ID>/locations/us/instances/<ID>/rules?filter=rule_owner%3A%22GOOGLE%22pageSize=1&view=TRENDS

Contoh respons:

JSON

{
  "rules": [
    {
      "name": "projects/<ID>/locations/us/instances/<ID>/rules/ur_e34bf150-6cfb-494c-ad9d-ec8f7216a03c",

      "revisionId": "v_1755272664_971453000",

      "displayName": "Example Curated Rule",

      "severity": {
        "displayName": "Info"
      },

      "metadata": {
        "technique": "T1136.003",
        "rule_name": "Example Curated Rule",
        "description": "Example Curated Rule Description",
        "tactic": "TA0003"
      },

      "createTime": "2024-10-02T18:10:43.647897Z",

      "revisionCreateTime": "2025-08-15T15:44:24.971453Z",

      "type": "SINGLE_EVENT",

      "etag": "CNir/cQGEMjknM8D",

      "nearRealTimeLiveRuleEligible": true,

      "ruleOwner": "GOOGLE",

      "tags": [
        "google.mitre.tactic.ta0003",
        "google.mitre.technique.t1136.003"
      ],

      "executionState": "DEFAULT"
    }
  ]
}

Metode rule.getRule mendukung pengambilan aturan pilihan menggunakan nama resourcenya.

Contoh permintaan getRule untuk mengambil aturan pilihan:

HTTP

GET https://chronicle.googleapis.com/v1alpha/projects/<ID>/locations/us/instances/<ID>/rules/ur_e34bf150-6cfb-494c-ad9d-ec8f7216a03c?view=BASIC

Contoh respons:

JSON

{
  "rules": [
    {
      "name": "projects/<ID>/locations/us/instances/<ID>/rules/ur_e34bf150-6cfb-494c-ad9d-ec8f7216a03c",

      "revisionId": "v_1755272664_971453000",

      "displayName": "Example Curated Rule",

      "severity": {
        "displayName": "Info"
      },

      "metadata": {
        "technique": "T1136.003",
        "rule_name": "Example Curated Rule",
        "description": "Example curated rule description",
        "tactic": "TA0003"
      },

      "createTime": "2024-10-02T18:10:43.647897Z",

      "revisionCreateTime": "2025-08-15T15:44:24.971453Z",

      "text": "Example curated rule text",

      "type": "SINGLE_EVENT",

      "etag": "CNir/cQGEMjknM8D",

      "nearRealTimeLiveRuleEligible": true,

      "ruleOwner": "GOOGLE",

      "tags": [
        "google.mitre.tactic.ta0003",
        "google.mitre.technique.t1136.003"
      ],

      "executionState": "DEFAULT"
    }
  ]
}

Mengubah konfigurasi aturan secara batch dengan modifyRules

Metode rules.modifyRules mendukung update batch berikut pada aturan kustom dan aturan pilihan:

  • Memperbarui status aturan aktif

  • Memperbarui status pemberitahuan

  • Memperbarui tag yang diterapkan

  • Memperbarui status arsip (hanya untuk aturan kustom)

Update batch dijalankan secara sinkron dan independen. Prosesnya bersifat non-atomik dan terus berlanjut meskipun terjadi kegagalan individual. Kegagalan sebagian dijelaskan di kolom failed_requests, peta tempat kunci mewakili indeks permintaan yang gagal dan nilai memberikan alasan kegagalan. Update yang berhasil didokumentasikan di kolom rule_updates, tempat hasil untuk setiap permintaan ditempatkan pada indeks yang sesuai dari batch asli.

Contoh permintaan modifyRules:

HTTP

POST https://chronicle.googleapis.com/v1alpha/projects/<ID>/locations/us/instances/<ID>/rules:modifyRules

JSON

{
  "parent": "projects/<ID>/locations/us/instances/<ID>",
  "requests": [
    {
      "update_mask": "liveModeEnabled",
      "rule": {
        "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ru_aaaaaaaaaaaaaaaaaaaaaaa",
        "liveModeEnabled": true
      }
    },
    {
      "update_mask": "alertingEnabled",
      "rule": {
        "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ur_zzzzzzzzzzzzzzzzzzzzz",
        "alertingEnabled": false
      }
    },
    {
      "update_mask": "tags",
      "rule": {
        "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ru_bbbbbbbbbbbbbbbbbbbbbbb",
        "tags": [
          "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/google.mitre.tactic.TA0043",
          "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/google.mitre.technique.T1595"
        ]
      }
    },
    {
      "update_mask": "archived",
      "rule": {
        "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ru_cccccccccccccccccccccc",
        "archived": true
      }
    }
  ]
}

Contoh respons:

JSON

{
  "failed_requests": {
    "0": {
      "code": 5,
      "message": "rule is already enabled"
    },
    "3": {
      "code": 5,
      "message": "rule is already archived"
    }
  },
  "rule_updates": [
    {},
    { "alerting_state_updated": true },
    { "tagsUpdated": true },
    {}
  ]
}

Panduan untuk memperbarui aturan pilihan

Saat Anda mengubah status aktif atau pemberitahuan untuk aturan pilihan, pertimbangkan hal berikut:

  • Kontrol independen: Anda dapat mengelola status aturan secara independen dari kebijakan kumpulan aturan induknya. Jika status aturan berbeda dari kebijakan induk, setelan kustom Anda akan tetap ada hingga kebijakan induk menerima update berikutnya.

  • Persyaratan hak: Anda hanya dapat memperbarui status ini jika instance Anda secara aktif memiliki hak atas paket aturan induk.

Panduan untuk memperbarui tag

Anda dapat mengaitkan tag dengan aturan menggunakan metode berikut:

  • Sertakan kode-T MITRE (taktik atau teknik) di kolom meta tactic, technique, atau mitre_ttp dalam teks aturan.

  • Tentukan nama resource tag lengkap di kolom meta tags dari teks aturan.

  • Tentukan nama resource tag lengkap menggunakan permintaan ModifyRule API.

ModifyRules API mendukung tag tactic dan technique MITRE. Tag apa pun yang diberikan dalam update API akan menimpa tag yang ada, kecuali tag yang disimpulkan langsung dari teks aturan.

Tag tactic MITRE yang dikelola Google menggunakan awalan namespace google.mitre.tactic.

Contoh nama resource lengkap untuk tag taktik TA0001:


projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/google.mitre.tactic.TA0001

Perlu bantuan lain? Dapatkan jawaban dari anggota Komunitas dan profesional Google SecOps.