Mengonfigurasi atribut bahasa aturan khusus

Setiap aturan kebijakan keamanan Google Cloud Armor memiliki prioritas, kondisi kecocokan, dan tindakan. Cloud Armor menjalankan tindakan dari aturan dengan prioritas tertinggi yang cocok dengan permintaan. Aturan dengan prioritas yang lebih rendah daripada aturan yang cocok dengan prioritas tertinggi tidak dievaluasi, meskipun memiliki kondisi kecocokan yang sama.

Setiap aturan kebijakan keamanan mendukung dua jenis kondisi kecocokan:

Kondisi kecocokan dasar berisi daftar alamat IP atau daftar rentang alamat IP. Kondisi kecocokan dasar ditentukan dengan menggunakan flag --src-ip-ranges saat membuat aturan menggunakan Google Cloud CLI.
Kondisi kecocokan lanjutan berisi ekspresi dengan hingga lima subekspresi yang dapat mencocokkan berbagai atribut permintaan yang masuk. Kondisi kecocokan lanjutan ditentukan menggunakan flag --expression saat membuat aturan menggunakan Google Cloud CLI.

Halaman ini membahas kondisi pencocokan lanjutan dan bahasa aturan khusus Cloud Armor yang Anda gunakan untuk menulis ekspresi dalam kondisi pencocokan lanjutan aturan kebijakan keamanan. Bahasa aturan khusus Cloud Armor adalah subset dari Common Expression Language (CEL). Ekspresi yang ditulis dalam bahasa aturan khusus Cloud Armor memerlukan dua komponen:

Atribut: data yang akan diperiksa
Operasi: cara menggunakan data

Misalnya, ekspresi berikut menggunakan atribut origin.ip dan 9.9.9.0/24 dalam operasi inIpRange(). Dalam hal ini, ekspresi akan menampilkan true jika origin.ip berada dalam rentang alamat IP 9.9.9.0/24.

inIpRange(origin.ip, '9.9.9.0/24')

Meskipun ekspresi contoh sebelumnya hanya cocok dengan alamat IP klien, saat Anda menggunakan ekspresi contoh tersebut dalam aturan kebijakan keamanan Cloud Armor, aturan tersebut dianggap sebagai aturan dengan kondisi kecocokan lanjutan dari perspektif kuota. Untuk mengetahui informasi selengkapnya, lihat Kuota dan batas Cloud Armor.

Operasi

Referensi berikut menjelaskan operator yang dapat Anda gunakan dengan atribut (diwakili oleh x, y, dan k) untuk menentukan ekspresi aturan.

Operasi	Ekspresi	Deskripsi
Kesetaraan	`x == y`	Menampilkan true jika x sama dengan y.
Kesetaraan, literal string	`x == "foo"`	Menampilkan true jika x sama dengan literal string konstan yang diberikan.
Kesetaraan, literal string raw	`x == R"fo'o"`	Menampilkan true jika x sama dengan literal string raw yang diberikan yang tidak menafsirkan urutan escape. Literal string raw berguna untuk mengekspresikan string yang harus menggunakan karakter urutan escape.
Logika NOT	`!x`	Menampilkan true jika nilai Boolean x adalah false, atau menampilkan false jika nilai Boolean x adalah true.
Ketidaksetaraan	`x != y`	Menampilkan true jika x tidak sama dengan y.
Penyambungan	`x + y`	Menampilkan string penyambungan xy.
Logika AND	`x && y`	Menampilkan true jika x dan y adalah true.
Logika OR	`x \|\| y`	Menampilkan true jika x, y, atau keduanya true.
Berisi substring	`x.contains(y)`	Menampilkan true jika string x berisi substring y.
Dimulai dengan substring	`x.startsWith(y)`	Menampilkan true jika string x dimulai dengan substring y.
Diakhiri dengan substring	`x.endsWith(y)`	Menampilkan true jika string x diakhiri dengan substring y.
Pencocokan ekspresi reguler	`x.matches(y)`	Menampilkan true jika string x sebagian cocok dengan pola RE2 y yang ditentukan. Pola RE2 dikompilasi menggunakan opsi RE2::Latin1 yang menonaktifkan fitur Unicode.
Alamat IP dalam rentang	`inIpRange(x, y)`	Menampilkan true jika alamat IP x berada dalam rentang IP y.
Huruf kecil	`x.lower()`	Menampilkan nilai huruf kecil dari string x.
Huruf besar	`x.upper()`	Menampilkan nilai huruf besar dari string x.
Nilai yang didekode base64	`x.base64Decode()`	Menampilkan nilai yang didekode base64 dari x; karakter `_ -` diganti terlebih dahulu dengan `/ +`. Menampilkan (string kosong) `""` jika x bukan nilai base64 yang valid.
Nilai key-map	`m['k']`	Menampilkan nilai pada kunci k dalam peta string-ke-string m jika k tersedia; jika tidak, maka error akan ditampilkan. Pendekatan yang direkomendasikan adalah memeriksa ketersediaan terlebih dahulu menggunakan `"has(m['k'])==true"`.
Memeriksa ketersediaan kunci di peta	`has(m['k'])`	Menampilkan true jika kunci k tersedia di peta m.
Mengonversi ke integer	`int(x)`	Mengonversi hasil string x menjadi jenis `int`. Kemudian, nilai ini dapat digunakan untuk melakukan perbandingan integer menggunakan operator aritmatika standar seperti > dan <=. Cara ini hanya berfungsi untuk nilai yang seharusnya berupa integer.
Panjang	`size(x)`	Menampilkan panjang string x.
Mendekode URL	`x.urlDecode()`	Menampilkan nilai yang didekode URL dari x; urutan karakter dalam format `%##` diganti dengan karakter non-ASCII yang setara, dan `+` diganti dengan spasi. Encoding yang tidak valid ditampilkan apa adanya.
Mendekode URL (Unicode)	`x.urlDecodeUni()`	Menampilkan nilai yang didekode URL dari x; selain `urlDecode()`, fungsi ini juga menangani urutan karakter unicode dalam format `%u###`. Encoding yang tidak valid ditampilkan apa adanya.
Konversi UTF-8 ke Unicode	`x.utf8ToUnicode()`	Menampilkan representasi Unicode huruf kecil dari x yang dienkode UTF-8.

Atribut

Atribut merepresentasikan informasi dari permintaan masuk, seperti alamat IP klien atau jalur URL yang diminta.

Kolom	Jenis	Deskripsi kolom
`origin.ip`	string	Alamat IP klien yang memulai permintaan.
`origin.user_ip`	string	Alamat IP klien asal, yang disertakan dalam `HTTP-HEADER` oleh proxy upstream. Sebelum menggunakan atribut ini, Anda harus mengonfigurasi opsi `userIpRequestHeaders[]` di kolom `advancedOptionsConfig` kebijakan keamanan agar cocok dengan sumber seperti `True-Client-IP`, `X-Forwarded-For`, atau `X-Real-IP`. Untuk mengetahui informasi selengkapnya, lihat Ringkasan alamat IP pengguna. Jika Anda tidak mengonfigurasi opsi `userIpRequestHeaders[]`, jika header yang dikonfigurasi berisi nilai alamat IP yang tidak valid, atau jika header yang dikonfigurasi tidak ada, `origin.user_ip` akan ditetapkan ke `origin.ip` secara default. Untuk mengetahui informasi selengkapnya, lihat referensi resource securityPolicy.
`origin.tls_ja4_fingerprint`	string	Sidik jari TLS/SSL JA4 jika klien terhubung menggunakan `HTTPS`, `HTTP/2`, atau `HTTP/3`. Jika tidak tersedia, string kosong akan ditampilkan.
`origin.tls_ja3_fingerprint`	string	Sidik jari TLS/SSL JA3 jika klien terhubung menggunakan `HTTPS`, `HTTP/2`, atau `HTTP/3`. Jika tidak tersedia, string kosong akan ditampilkan.
`request.headers`	map	Peta string-ke-string dari header permintaan HTTP. Jika header berisi beberapa nilai, nilai dalam peta ini akan berupa string yang dipisahkan koma dari semua nilai header. Semua kunci dalam peta ini berupa huruf kecil. Semua header yang diterima oleh Load Balancer Aplikasi eksternal diperiksa, dan batasan header yang sama berlaku. Pendekatan yang direkomendasikan adalah memeriksa ketersediaan terlebih dahulu menggunakan `has()`, seperti `has(request.headers['header-key']) && request.headers['header-key'] != 'header-value'`.
`request.method`	string	Metode permintaan HTTP.
`request.path`	string	Jalur URL HTTP yang diminta.
`request.scheme`	string	Skema URL HTTP seperti `http` atau `https`. Nilai untuk atribut ini berupa huruf kecil.
`request.query`	string	Kueri URL HTTP dalam format `name1=value&name2=value2`, seperti yang muncul di baris pertama permintaan HTTP. Tidak ada decoding yang dijalankan.
`origin.region_code`	string	Kode negara Unicode yang terkait dengan IP klien, seperti `US`. Jika Anda membuat aturan atau ekspresi yang menggunakan kode negara atau region ISO 3166-1 alpha 2, Cloud Armor memperlakukan setiap kode secara terpisah. Aturan dan ekspresi Cloud Armor secara eksplisit menggunakan kode region tersebut untuk mengizinkan atau menolak permintaan.
`origin.asn`	integer	Nomor sistem otonom (ASN) yang terkait dengan alamat IP klien. ASN yang unik secara global ditentukan berdasarkan operator jaringan yang mendukung awalan alamat IP yang berisi alamat IP klien.

Atribut reCAPTCHA

Bagian ini mencantumkan atribut yang hanya berlaku untuk token reCAPTCHA atau cookie pengecualian. Subekspresi berdasarkan atribut ini menampilkan false jika token reCAPTCHA atau cookie pengecualian yang akan dievaluasi tidak tersedia atau tidak valid karena salah satu alasan berikut:

Token salah format dan tidak dapat didekode.
Token berisi atribut yang tidak valid. Misalnya, token dibuat menggunakan kunci reCAPTCHA yang tidak cocok dengan kunci reCAPTCHA yang terkait dengan aturan.
Token telah kedaluwarsa.

Atribut cookie pengecualian

Kolom	Jenis	Deskripsi kolom
`token.recaptcha_exemption.valid`	`bool`	Keberadaan cookie pengecualian reCAPTCHA yang valid.

Atribut token tindakan

Kolom	Jenis	Deskripsi kolom
`token.recaptcha_action.score`	`float`	Skor dari token tindakan reCAPTCHA. Skor yang valid berkisar antara `0.0` hingga `1.0`, dengan `0.0` kemungkinan besar adalah pengguna yang tidak sah, dan `1.0` kemungkinan besar adalah pengguna yang sah.
`token.recaptcha_action.captcha_status`	`string`	Status captcha dari token tindakan reCAPTCHA. Status yang valid adalah `NONE`, `PASS`, atau `FAIL`, dengan `NONE` merujuk pada saat tidak ada tantangan yang terlibat selama penilaian reCAPTCHA, sehingga kolom captcha tidak ada dalam token tindakan.
`token.recaptcha_action.action`	`string`	Nama tindakan (hingga 100 karakter) dari token tindakan reCAPTCHA. Lihat Nama tindakan.
`token.recaptcha_action.valid`	`bool`	Keberadaan token tindakan reCAPTCHA yang valid.

Atribut token sesi

Kolom	Jenis	Deskripsi kolom
`token.recaptcha_session.score`	`float`	Skor dari token sesi reCAPTCHA. Skor yang valid berkisar antara `0.0` hingga `1.0`, dengan `0.0` kemungkinan besar adalah pengguna yang tidak sah, dan `1.0` kemungkinan besar adalah pengguna yang sah.
`token.recaptcha_session.valid`	`bool`	Keberadaan token sesi reCAPTCHA yang valid.

Contoh ekspresi

Untuk setiap ekspresi berikut, tindakan yang diambil bergantung pada apakah ekspresi tersebut disertakan dalam aturan penolakan atau aturan izin.

Mengizinkan atau menolak akses berdasarkan rentang alamat IP di IPv4 atau IPv6

Ekspresi berikut cocok dengan permintaan dari rentang alamat IP 198.51.100.0/24:
```
inIpRange(origin.ip, '198.51.100.0/24')
```
Ekspresi berikut cocok dengan permintaan dari rentang alamat IP 2001:db8::/32:
```
inIpRange(origin.ip, '2001:db8::/32')
```

Mengizinkan atau menolak akses berdasarkan rentang alamat IP klien kustom di belakang proxy upstream

Jika telah mengonfigurasi operator origin.user_ip, Anda dapat mencocokkan berdasarkan nilai header yang ditentukan di kolom advancedOptionsConfig.userIpRequestHeaders[].

Ekspresi berikut cocok dengan permintaan yang berasal dari rentang alamat IP 192.0.2.0/24:
```
inIpRange(origin.user_ip, '192.0.2.0/24')
```
Ekspresi berikut cocok dengan permintaan yang berasal dari rentang alamat IP 2001:db8::/32:
```
inIpRange(origin.user_ip, '2001:db8::/32')
```

Mengizinkan atau menolak traffic dengan cookie tertentu

Ekspresi berikut cocok dengan permintaan yang memiliki cookie yang berisi 80=BLAH:

has(request.headers['cookie']) && request.headers['cookie'].contains('80=BLAH')

Mengizinkan atau menolak traffic dengan header `referer` yang tidak kosong

Ekspresi berikut cocok dengan permintaan yang memiliki header referer yang tidak kosong:
```
has(request.headers['referer']) && request.headers['referer'] != ""
```

Mengizinkan atau menolak traffic berdasarkan header host

Anda dapat mengizinkan atau menolak traffic berdasarkan nilai header Host dalam permintaan.

Ekspresi berikut cocok dengan permintaan ke URL tertentu menggunakan ==:
```
request.headers['host'].lower() == 'test.example.com'
```
Ekspresi berikut cocok dengan permintaan ke URL tertentu menggunakan endsWith:
```
request.headers['host'].lower().endsWith('.example.com')
```
Ekspresi berikut cocok dengan permintaan ke URL tertentu menggunakan contains:
```
request.headers['host'].lower().contains('test.example.com')
```

Ekspresi berikut cocok dengan permintaan ke beberapa domain menggunakan contains:

request.headers['host'].lower().contains('test.example.com') || request.headers['host'].lower().contains('test22.example.com')

Ekspresi berikut cocok dengan permintaan ke domain dan subdomainnya menggunakan matches:
```
request.headers['host'].matches('(?i:(sub\.)?test\.example\.com)')
```

Mengizinkan atau menolak traffic dari region tertentu

Jika aplikasi web Anda tidak tersedia di region AU, semua permintaan dari region tersebut harus diblokir.

Dalam aturan penolakan, gunakan ekspresi berikut yang cocok dengan permintaan dari region AU:
```
origin.region_code == 'AU'
```

Sebaliknya, jika aplikasi web Anda hanya tersedia di region AU, permintaan dari semua region lain harus diblokir.

Dalam aturan penolakan, gunakan ekspresi berikut yang cocok dengan permintaan dari semua region selain region AU:
```
origin.region_code != 'AU'
```

Kode region didasarkan pada kode ISO 3166-1 alpha 2. Dalam beberapa kasus, region sesuai dengan negara, tetapi tidak selalu demikian. Misalnya, kode