Kebijakan analisis lint

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

Sebelum memulai

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

  1. Di konsol Google Cloud, buka halaman IAM.

    Buka IAM

  2. Klik Pilih project, pilih project, lalu klik Buka.

  3. Dari daftar utama, temukan akun utama yang diinginkan dan klik tombol Edit.

  4. Dari panel Izin edit, temukan peran yang diinginkan yang akan Anda lint. Kemudian, di bagian IAM condition (opsional), klik nama kondisinya.

  5. Di Editor kondisi, tambahkan atau edit ekspresi kondisi secara manual.

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

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

  8. Jika tidak ada error atau peringatan, klik Simpan untuk menerapkan kondisi.

  9. 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:

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:

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