Kebijakan analisis lint

Topik ini menjelaskan cara melakukan lint atau memvalidasi kebijakan yang diizinkan oleh Identity and Access Management (IAM).

Sebelum memulai

Aktifkan IAM API.
Mengaktifkan API
Baca ringkasan IAM Conditions untuk memahami dasar-dasar IAM Conditions.

Peran yang diperlukan

Untuk melakukan lint pada kebijakan izin resource, Anda memerlukan izin untuk mendapatkan resource, serta mendapatkan dan menetapkan kebijakan izin untuk resource tersebut. Izin ini memiliki bentuk berikut, dengan SERVICE merupakan nama layanan yang memiliki resource dan RESOURCE_TYPE merupakan nama jenis resource yang aksesnya ingin Anda kelola:

SERVICE.RESOURCE_TYPE.get
SERVICE.RESOURCE_TYPE.getIamPolicy
SERVICE.RESOURCE_TYPE.setIamPolicy

Misalnya, untuk melakukan lint kebijakan izin project, Anda memerlukan izin berikut:

resourcemanager.projects.get
resourcemanager.projects.getIamPolicy
resourcemanager.projects.setIamPolicy

Untuk mendapatkan izin yang diperlukan, minta administrator untuk memberi Anda peran khusus atau bawaan yang menyertakan izin tersebut. Misalnya, administrator dapat memberi Anda peran Security Admin (roles/iam.securityAdmin), yang mencakup izin untuk mendapatkan hampir semua resource Google Cloud dan mengelola kebijakan izin.

Memahami analisis lint untuk kebijakan izin

Dalam konteks kebijakan izin, analisis lint adalah metode pemeriksaan kebijakan izin baru atau yang sudah ada untuk memeriksa masalah tertentu. Masalah ini mencakup berbagai kemungkinan berikut:

Saran
Peringatan
Informasi yang dapat membantu meningkatkan intent kebijakan izin, seperti peningkatan sintaksis dan semantik
Kesalahan sintaksis atau semantik yang menyebabkan operasi setIamPolicy gagal

Jika Anda mencoba memperbarui kebijakan izin, dan terjadi error, menganalisis lint kebijakan izin dapat membantu Anda menemukan penyebab error tersebut. Anda juga dapat menggunakan linter untuk membantu memastikan bahwa binding peran bersyarat memberikan hasil yang diinginkan.

Menganalisis lint pada suatu kondisi

Ekspresi kondisi mungkin akan menjadi rumit, terutama ketika memerlukan banyak klausa dan operator logika untuk mengelola akses dengan tepat. Jika ekspresi kondisi berisi logika yang tidak valid, atau jika sintaksis melanggar batasan ekspresi kondisi, Anda tidak dapat menambahkan kondisi ke kebijakan izin.

Selain itu, meskipun ekspresi kondisi menggunakan sintaksis yang benar, ekspresi tersebut mungkin berisi kesalahan semantik. Kesalahan tersebut dapat mencegah kebijakan izin dan binding peran berfungsi seperti yang diharapkan. Kesalahan semantik umumnya mencakup hal berikut:

Penggunaan fungsi yang tidak direkomendasikan
Penggunaan jenis resource lama atau nama layanan lama
Kondisi yang tidak efektif, seperti tanggal atau rentang waktu yang tidak dapat diterapkan

Saat Anda melakukan analisis lint terhadap suatu kondisi, linter akan memeriksa ekspresi kondisi dan melaporkan setiap kesalahan sintaksis. Fitur ini juga melaporkan kemungkinan kesalahan semantik yang dapat menyebabkan hasil yang tidak terduga.

Sebelum mencoba menetapkan binding peran kondisional baru, Anda disarankan untuk melakukan lint ekspresi terlebih dahulu. Bagian ini menunjukkan cara melakukan lint ekspresi kondisi menggunakan Konsol Google Cloud, Google Cloud CLI, atau REST API.

Untuk melakukan lint ekspresi kondisi:

Konsol

Di konsol Google Cloud, buka halaman IAM.

Buka IAM
Klik Pilih project, pilih project, lalu klik Buka.
Dari daftar utama, temukan akun utama yang diinginkan dan klik tombol Edit.
Dari panel Izin edit, temukan peran yang diinginkan yang akan Anda lint. Kemudian, di bagian IAM condition (opsional), klik nama kondisinya.
Di Editor Kondisi, tambahkan atau edit ekspresi kondisi secara manual.
Untuk memvalidasi sintaks CEL, klik Jalankan Linter.

Jika sintaksis berisi error, ikon Error akan muncul di samping baris yang salah. Untuk melihat detail setiap error, arahkan kursor ke ikon.

Jika kondisi menggunakan sintaksis yang benar, tetapi linter menemukan kemungkinan masalah, ikon Peringatan akan muncul di samping baris yang bermasalah. Untuk melihat detail setiap peringatan, arahkan kursor ke ikon.
Buat perubahan yang diperlukan pada ekspresi kondisi. Setelah Anda mengklik Jalankan Linter, linter akan otomatis berjalan di latar belakang saat Anda mengedit ekspresi.

Anda harus memperbaiki semua error sebelum menyimpan ekspresi kondisi. Sebaiknya Anda juga memperbaiki semua peringatan.
Jika tidak ada error atau peringatan, klik Simpan untuk menerapkan kondisi.
Setelah panel Edit kondisi ditutup, klik Simpan lagi dari panel Izin edit untuk memperbarui kebijakan izin.

gcloud

Jalankan perintah gcloud alpha iam policies lint-condition untuk melakukan lint ekspresi kondisi tertentu. Untuk menjalankan perintah ini, Anda dapat membuat file teks yang berisi kondisi, atau menentukan flag untuk judul, deskripsi, dan ekspresi kondisi.

Contoh ini menggunakan file teks yang berisi kondisi berikut:

condition.json

{
  "title": "1_less_than_2",
  "description": "",
  "expression": "1 <"
}

Perintah jalankan:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Output dari perintah ini berisi hal berikut:

lintResults:
- debugMessage: |-
    ERROR: Parse expression:1:3: mismatched input '<EOF>' expecting {'[', '{', '(', '.', '-', '!', 'true', 'false', 'null', NUM_FLOAT, NUM_INT, NUM_UINT, STRING, BYTES, IDENTIFIER}
      | 1 >
      | ...^
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 3
  severity: ERROR
  validationUnitName: LintValidationUnits/ConditionCompileCheck
...

Setiap hasil lint berisi debugMessage yang dapat digunakan untuk membantu menemukan masalah dengan ekspresi kondisi. Jika kondisi gagal dikompilasi, Anda mungkin melihat berbagai jenis validationUnitName dengan teks debugMessage berikut:

The validation unit is skipped due to absence of a required object: CheckedExpr

Ubah ekspresi agar dapat dikompilasi, lalu lint kembali kondisi tersebut.

REST

Metode iamPolicies.lintPolicy melakukan lint, atau memvalidasi, ekspresi kondisi dalam kebijakan izin.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

condition: Object Expr yang mewakili kondisi pada lint. Contoh:
```
"title": "1_less_than_2",
"description": "",
"expression": "1 <"
```
Untuk mempelajari format objek Expr, lihat referensi skema Expr.

Metode HTTP dan URL:

POST https://iam.googleapis.com/v1/iamPolicies:lintPolicy

Meminta isi JSON:

{
  "condition": {
    condition
  }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/iamPolicies:lintPolicy"

PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/iamPolicies:lintPolicy" | Select-Object -Expand Content

APIs Explorer (browser)

Salin isi permintaan dan buka halaman referensi metode. Panel APIs Explorer akan terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Tempelkan isi permintaan di alat ini, lengkapi kolom wajib lainnya, lalu klik Jalankan.

Isi respons berisi satu atau beberapa objek LintResult seperti berikut:

{
  "lint_results": {
    "level": "CONDITION",
    "validation_unit_name": "LintValidationUnits/ConditionCompileCheck",
    "severity": "ERROR",
    "field_name": "condition.expression",
    "location_offset": "2",
    "debug_message": "ERROR: Parse expression:1:2: mismatched input \'<EOF>\' expecting {\'[\', \'{\', \'(\', \'.\', \'-\', \'!\', \'true\', \'false\', \'null\', NUM_FLOAT, NUM_INT, NUM_UINT, STRING, BYTES, IDENTIFIER}\n  | 1<\n  | ..^"
  },
  "lint_results": {
    "level": "CONDITION",
    "validation_unit_name": "LintValidationUnits/ConditionComplexityCheck",
    "severity": "NOTICE",
    "field_name": "condition.expression",
    "debug_message": "The validation unit is skipped due to absence of a required object: CheckedExpr"
  }
}

Setiap hasil lint berisikan debug_message yang dapat digunakan untuk membantu menemukan masalah dengan ekspresi kondisi. Jika kondisi gagal dikompilasi, Anda mungkin melihat berbagai jenis validation_unit_name dengan teks debugMessage berikut:

The validation unit is skipped due to absence of a required object: CheckedExpr

Ubah ekspresi agar dapat dikompilasi, lalu lint kembali kondisi tersebut.

Unit validasi yang didukung

Seperti yang dijelaskan sebelumnya, unit validasi adalah jenis lint individu yang mengevaluasi ekspresi untuk masalah sintaksis. Tabel di bawah ini merangkum unit validasi yang didukung, masing-masing dengan tingkat analisis lint yang dimaksudkan, tingkat keparahan hasil analisis lint, dan deskripsi singkatnya.

Unit validasi	Tingkat lint	Keparahan	Deskripsi
`ConditionCompileCheck`	`CONDITION`	`ERROR`	Ekspresi kondisi berisi error kompilasi sebagai akibat dari sintaks CEL yang tidak valid.
`ConditionComplexityCheck`	`CONDITION`	`ERROR`	Ekspresi kondisi berisi lebih dari jumlah maksimum 12 operator logika.
`DateTimeCheck`	`CONDITION`	`WARNING`	Ekspresi kondisi menentukan perbandingan stempel waktu yang selalu bernilai benar atau salah, karena salah satu masalah berikut: Stempel waktu tidak menggunakan format yang benar untuk stempel waktu. Stempel waktu berada di masa lalu.
`DateTimeRangeCheck`	`CONDITION`	`WARNING`	Nilai di luar rentang untuk fungsi stempel waktu lanjutan yang dimaksudkan dan ekspresi perbandingan. Lihat nilai valid untuk mengetahui fungsi stempel waktu lanjutan.
`DrgGetAttributeDefaultValueCheck`	`CONDITION`	`ERROR`	Ekspresi kondisi memanggil `api.getAttribute('iam.googleapis.com/modifiedGrantsByRole', V)`, dengan `V` adalah semua nilai selain daftar kosong, `[]`. Untuk atribut API ini, `V` harus selalu berupa daftar kosong.
`EffectiveTimeRangeCheck`	`CONDITION`	`WARNING`	Dalam penggunaan fungsi dan perbandingan stempel waktu yang lebih kompleks, ekspresi menghasilkan rentang waktu efektif yang kosong, sehingga secara efektif bernilai salah. Atau, rentang waktu mencakup rentang penuh, sehingga secara efektif bernilai benar.
`HasOnlyListConstCheck`	`CONDITION`	`ERROR`	Ekspresi kondisi memanggil `hasOnly(List<T>)`, dengan jenis `T` bukan merupakan jenis konstanta, seperti string atau bilangan bulat. Fungsi `hasOnly()` hanya menerima daftar konstanta.
`HasOnlyListLengthCheck`	`CONDITION`	`ERROR`	Ekspresi kondisi memanggil `hasOnly(List<T>)`, dan `List<T>` berisi lebih dari jumlah maksimum 10 elemen.
`ResourceServiceLiteralCheck`	`CONDITION`	`WARNING`	Nilai `resource.service` yang ditentukan tidak didukung. Ekspresi yang menggunakan string literal untuk perbandingan kesetaraan pada dasarnya bernilai salah. Gunakan nilai yang didukung.
`ResourceTypeLiteralCheck`	`CONDITION`	`WARNING`	Nilai `resource.type` yang ditentukan tidak didukung. Ekspresi yang menggunakan string literal tersebut untuk perbandingan kesetaraan pada dasarnya bernilai salah. Gunakan nilai yang didukung.
`RestrictedAttributesCheck`	`CONDITION`	`WARNING`	Ekspresi tersebut menggunakan atribut yang dibatasi atau tidak didukung. Penyetelan ekspresi kondisi mungkin tidak berhasil. Lihat daftar attribut.

Contoh analisis lint

Bagian ini menunjukkan contoh kondisi yang menyebabkan setiap unit validasi melaporkan masalah. Setiap contoh menunjukkan analisis lint menggunakan Google Cloud CLI.

Tidak ada masalah validasi

Contoh kondisi:

{
  "title": "1_less_than_2",
  "description": "",
  "expression": "1 < 2"
}

Perintah jalankan:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Hasil lint:

{}

ConditionCompileCheck

Contoh kondisi:

{
  "title": "Condition not compiling",
  "description": "",
  "expression": "true=false"
}

Perintah jalankan:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Hasil lint:

lintResults:
- debugMessage: |-
    ERROR: Parse expression:1:4: token recognition error at: '=f'
      | true=false
      | ....^
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 4
  severity: ERROR
  validationUnitName: LintValidationUnits/ConditionCompileCheck

ConditionComplexityCheck

Contoh kondisi:

{
  "title": "Condition not compiling",
  "description": "",
  "expression":
    "1<2 || 2<3 || 3<4 || 4<5 || 5<6 || 6<7 || 7<8 || 8<9 || 9<10 || 10<11 || 11<12 || 12<13 || 13<14 || 14<15"
}

Perintah jalankan:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Hasil lint:

lintResults:
- debugMessage: Logical operators count must not be more than 12
  fieldName: condition.expression
  level: CONDITION
  severity: ERROR
  validationUnitName: LintValidationUnits/ConditionComplexityCheck

DateTimeCheck

Contoh kondisi:

{
  "title": "Condition not compiling",
  "description": "",
  "expression": "request.time < timestamp('2000-01-01T00:00:00Z')"
}

Perintah jalankan:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Hasil lint:

lintResults:
- debugMessage: Ineffective date time value 2000-01-01T00:00:00+00:00 parsed
    from "2000-01-01T00:00:00Z"; condition is effectively False. Time expired
    already.
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 25
  severity: WARNING
  validationUnitName: LintValidationUnits/DateTimeCheck

DateTimeRangeCheck

Contoh kondisi:

{
  "title": "Time function out of range",
  "description": "",
  "expression": "request.time.getMonth() > 13"
}

Perintah jalankan:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Hasil lint:

lintResults:
- debugMessage: The value being compared to the specified timestamp function
    (getMonth) must be in range [0, 11].
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 26
  severity: WARNING
  validationUnitName: LintValidationUnits/DateTimeRangeCheck

DrgGetAttributeDefaultValueCheck

Contoh kondisi:

{
  "title": "DRG condition takes non empty list as default value",
  "description": "",
  "expression":
    "api.getAttribute('iam.googleapis.com/modifiedGrantsByRole', ['roles/viewer']).hasOnly(['roles/editor'])"
}

Perintah jalankan:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Hasil lint:

lintResults:
- debugMessage: api.getAttribute call on
    'iam.googleapis.com/modifiedGrantsByRole' can only
    accept empty list ('[]') as default value.
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 60
  severity: ERROR
  validationUnitName: LintValidationUnits/DrgGetAttributeDefaultValueCheck

EffectiveTimeRangeCheck

Contoh kondisi:

{
  "title": "Empty time range",
  "description": "",
  "expression": "request.time.getMonth() > 5 && request.time.getMonth() < 4"
}

Perintah jalankan:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Hasil lint:

lintResults:
- debugMessage: The aggregate of time functions [getMonth] results in empty ranges.
  fieldName: condition.expression
  level: CONDITION
  severity: WARNING
  validationUnitName: LintValidationUnits/EffectiveTimeRangeCheck

HasOnlyListConstCheck

Contoh kondisi:

{
  "title": "hasOnly contains more than constant value",
  "description": "",
  "expression":
    "api.getAttribute('somekey', []).hasOnly(['somevalue', resource.name])"
}

Perintah jalankan:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Hasil lint:

lintResults:
- debugMessage: hasOnly() expects an argument of type list containing only const
      values, but a non-const expression was found in the list.
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 59
  severity: ERROR
  validationUnitName: LintValidationUnits/HasOnlyListConstCheck

HasOnlyListLengthCheck

Contoh kondisi:

{
  "title": "hasOnly contains more than 10 elements",
  "description": "",
  "expression":
    "api.getAttribute('somekey', []).hasOnly([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])"
}

Perintah jalankan:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Hasil lint:

lintResults:
- debugMessage: The list argument to hasOnly() cannot have more than 10 elements
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 39
  severity: ERROR
  validationUnitName: LintValidationUnits/HasOnlyListLengthCheck

ResourceServiceLiteralCheck

Contoh kondisi:

{
  "title": "Condition with unsupported resource service string",
  "description": "",
  "expression": "resource.service == 'resourcemanager'"
}

Perintah jalankan:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Hasil lint:

lintResults:
- debugMessage: 'resource.service : resourcemanager is not supported. Using this
    value in condition may lead to unintended consequences. Check user guide at
    https://cloud.google.com/iam/docs/conditions-resource-attributes#resource_service_values
    for supported values for resource.service.'
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 20
  severity: WARNING
  validationUnitName: LintValidationUnits/ResourceServiceLiteralCheck

ResourceTypeLiteralCheck

Contoh kondisi:

{
  "title": "Condition with legacy resource type",
  "description": "",
  "expression": "resource.type == 'resourcemanager.projects'"
}

Perintah jalankan:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Hasil lint:

lintResults:
- debugMessage: 'resource.type : resourcemanager.projects is not supported.
    Using this value in condition may lead to unintended consequences. Check
    user guide at https://cloud.google.com/iam/docs/conditions-resource-attributes#resource_type_values
    for supported values for resource.type.'
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 17
  severity: WARNING
  validationUnitName: LintValidationUnits/ResourceTypeLiteralCheck

RestrictedAttributesCheck

Contoh kondisi:

{
  "title": "Condition with restricted attribute",
  "description": "",
  "expression": "'accessPolicies/123/accesslevels/TRUSTED' in request.auth.access_levels"
}

Perintah jalankan:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Hasil lint:

lintResults:
- debugMessage: Condition attribute `request.auth.access_levels` is restricted
    or unsupported. Please check https://cloud.google.com/iam/docs/conditions-overview
    for the full list of supported attributes
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 57
  severity: WARNING
  validationUnitName: LintValidationUnits/RestrictedAttributesCheck