Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Memindai keterampilan untuk menemukan masalah keamanan

Agent Registry memungkinkan Anda mengonfigurasi pemindaian keamanan otomatis untuk kemampuan mandiri, menerapkan kebijakan pemindaian di seluruh organisasi Anda menggunakan Organization Policy Service, dan melakukan triase temuan keamanan sehingga Anda dapat mencegah kemampuan yang disusupi menjangkau agen Anda.

Saat Anda mengupload revisi skill, Agent Registry akan memindai file petunjuk SKILL.md, skrip opsional, dan aset pendukung untuk menemukan risiko keamanan seperti pemindahan data yang tidak sah, kredensial yang terekspos, dan injeksi perintah.

Pemindaian keamanan keahlian menggunakan model bahasa besar (LLM) untuk mengevaluasi petunjuk, logika kode, dan intent semantik. Karena analisis LLM bersifat probabilistik, pemindaian mungkin menghasilkan positif palsu atau negatif palsu, dan hasilnya mungkin bervariasi di setiap eksekusi. Selain itu, detail tentang temuan mungkin berupa perkiraan dan dapat mengalami halusinasi. Developer harus meninjau dan memverifikasi temuan pemindaian sebelum menerapkan perubahan perbaikan.

Sebelum memulai

Menyiapkan Agent Registry.
Untuk penyiapan project tunggal, dapatkan project ID dari project tata kelola tempat Agent Registry diaktifkan. Jika Anda mengonfigurasi batas pengelolaan untuk beberapa project, gunakan ID project pengelolaan Anda untuk penemuan dan pendaftaran di seluruh batas, atau tentukan ID project anggota untuk operasi project tunggal.
Daftarkan keahlian mandiri di Agent Registry.
Untuk menggunakan perintah Google Cloud CLI dalam dokumen ini, siapkan lingkungan gcloud CLI Anda.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk mengonfigurasi pemindaian dan melakukan triase temuan di Agent Registry, minta administrator untuk memberi Anda peran IAM berikut pada project tata kelola tempat Agent Registry diaktifkan:

Mengonfigurasi pemindaian keterampilan: Agent Registry User (roles/agentregistry.user)
Melihat keterampilan dan revisi keterampilan: Agent Registry API Viewer (roles/agentregistry.viewer)
Melihat dan mencantumkan temuan keamanan: Agent Registry API Admin (roles/agentregistry.admin)
Menerapkan kebijakan pemindaian di tingkat organisasi atau folder: Organization Policy Administrator (roles/orgpolicy.policyAdmin)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Peran Agent Registry lainnya mungkin juga mencakup izin yang diperlukan untuk mengonfigurasi pemindaian dan melihat skill. Untuk mengetahui informasi selengkapnya, lihat Peran dan izin Agent Registry.

Batasan ukuran payload yang tidak dikompresi

Untuk memastikan performa yang optimal dan mengakomodasi batas token pemrosesan untuk pemindai LLM yang mendasarinya, Registry Agen menerapkan batas ukuran yang tidak dikompresi yang ketat saat pemindaian aktif:

Total ukuran skill yang tidak dikompresi: maksimum 10 MB untuk arsip yang diekstrak.
Ukuran per file yang tidak dikompresi: maksimum 1 MB untuk setiap file dalam paket skill.

Jika skill memiliki pemindaian diaktifkan dan melebihi batas ini, pembuatan revisi skill akan gagal dengan error INVALID_ARGUMENT atau status pemindaian revisi akan berubah menjadi UNSUPPORTED_FORMAT.

Jika pemindaian dinonaktifkan secara eksplisit, Agent Registry akan mengabaikan batas ukuran khusus pemindaian ini, tetapi batas sistem umum tetap berlaku. Untuk mengetahui informasi selengkapnya tentang batas sistem, lihat Kuota dan batas sistem.

Mengonfigurasi kebijakan pemindaian untuk keterampilan

Secara default, skill menggunakan kebijakan pemindaian Diaktifkan (Memblokir) (ENABLED_BLOCKING) , yang otomatis memindai revisi skill yang diupload untuk mendeteksi risiko keamanan seperti pemindahan data yang tidak sah, kredensial yang terekspos, dan injeksi perintah. Masalah yang terdeteksi ditampilkan sebagai resource Finding hanya baca di project tata kelola Anda: projects/PROJECT_NUMBER/locations/LOCATION/findings/FINDING_ID.

Dengan Enabled (Blocking), Agent Registry memblokir download revisi yang memiliki temuan keamanan dan mencegah promosi revisi yang memiliki temuan atau pemindaian yang tertunda sebagai revisi default skill.

Anda juga dapat mengonfigurasi kebijakan pemindaian untuk mode audit non-pemblokiran (ENABLED_NONBLOCKING) atau menonaktifkan pemindaian (DISABLED). Untuk mengetahui informasi selengkapnya tentang kebijakan pemindaian yang didukung, lihat Kebijakan pemindaian.

Menetapkan atau memperbarui setelan pemindaian keterampilan

Mengaktifkan atau mengupdate pemindaian pada skill yang ada hanya berlaku untuk revisi skill yang dibuat setelah perubahan konfigurasi. Pemindaian tidak dipicu secara retroaktif untuk revisi yang telah dibuat. Untuk memindai konten keahlian yang diupload saat pemindaian dinonaktifkan, Anda harus membuat revisi keahlian baru.

Untuk mengonfigurasi setelan pemindaian saat membuat atau memperbarui skill, ikuti langkah-langkah berikut:

Konsol

Di konsol Google Cloud , buka halaman Agent Registry:

Buka Agent Registry
Pilih tab Keterampilan.
Klik Add skill atau pilih keahlian yang ada, lalu klik Edit.
Di bagian Security scanning, pilih kebijakan pemindaian yang Anda inginkan.
Klik Save atau Create.

gcloud

Membuat skill dengan pemindaian diaktifkan (pemblokiran): jalankan perintah gcloud agent-registry skills create dengan flag --scanning-policy yang ditetapkan ke enabled-blocking. Misalnya, jika Anda mendaftarkan skill menggunakan arsip ZIP dari bucket Cloud Storage:

gcloud agent-registry skills create SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --target-state=disabled \
    --scanning-policy=enabled-blocking \
    --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

Membuat skill dengan pemindaian diaktifkan (non-pemblokiran): jalankan perintah gcloud agent-registry skills create dengan flag --scanning-policy yang ditetapkan ke enabled-nonblocking. Misalnya, jika Anda mendaftarkan skill menggunakan arsip ZIP dari bucket Cloud Storage:

gcloud agent-registry skills create SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --target-state=disabled \
    --scanning-policy=enabled-nonblocking \
    --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

Memperbarui kebijakan pemindaian pada skill yang ada: jalankan perintah gcloud agent-registry skills update dengan flag --scanning-policy yang ditetapkan ke kebijakan yang dipilih, misalnya enabled-nonblocking:
```
gcloud agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --scanning-policy=enabled-nonblocking
```

Menonaktifkan pemindaian pada skill: jalankan perintah gcloud agent-registry skills update dengan flag --scanning-policy yang ditetapkan ke disabled:

gcloud agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --scanning-policy=disabled

Menjelaskan konfigurasi pemindaian pada skill yang ada: jalankan perintah gcloud agent-registry skills describe dengan flag --format yang ditetapkan ke value(scanningConfig.policy):
```
gcloud agent-registry skills describe SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format="value(scanningConfig.policy)"
```

Ganti kode berikut:

SKILL_ID: ID keterampilan. Saat memperbarui atau menjelaskan keterampilan yang sudah ada dan terdaftar secara manual, sertakan awalan private-, seperti private-my-skill.
PROJECT_ID: project ID.
LOCATION: lokasi registry.
BUCKET_NAME: nama bucket Cloud Storage yang berisi paket ZIP. Sebelum mengimpor dari bucket, pastikan agen layanan Agent Registry memiliki izin storage.objects.get di bucket. Untuk mengetahui informasi selengkapnya, lihat Mendaftarkan skill.
SKILL_PACKAGE: nama paket skill yang berisi payload skill.

REST

Untuk mengonfigurasi pemindaian menggunakan REST API, sertakan objek scanningConfig dalam isi permintaan Anda:

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
        "scanningConfig": {
          "policy": "ENABLED_BLOCKING"
        }
      }' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=scanningConfig"

Ganti kode berikut:

PROJECT_ID: project ID.
LOCATION: lokasi registry.
SKILL_ID: ID keterampilan. Untuk keterampilan yang didaftarkan secara manual, sertakan awalan private-, seperti private-my-skill.

Menerapkan pemindaian menggunakan Organization Policy Service

Anda dapat menerapkan kebijakan pemindaian di seluruh organisasi dengan menentukan batasan Organization Policy Service kustom pada resource Skill yang mengevaluasi kebijakan pemindaian, dengan pengecualian tag Resource Manager opsional.

Untuk mengetahui informasi tentang penerapan kebijakan organisasi di Agent Registry, kemampuan, dan batasan, lihat Penerapan kebijakan organisasi.

Menentukan batasan kustom

Buat file YAML bernama skills-scan-constraint.yaml dengan spesifikasi berikut:

name: organizations/ORGANIZATION_ID/customConstraints/custom.skillsScanningEnforcement
resourceTypes:
- agentregistry.googleapis.com/Skill
methodTypes:
- CREATE
- UPDATE
condition: resource.scanningConfig.policy == "DISABLED"
actionType: DENY
displayName: Prevent Disabling Skills Scanning
description: Prevents creating or updating skills with scanning disabled.

Ganti ORGANIZATION_ID dengan ID organisasi numerik Anda.

Untuk mewajibkan mode pemblokiran di semua kemampuan dan mencegah kebijakan pemindaian DISABLED dan ENABLED_NONBLOCKING, Anda juga dapat menetapkan condition: resource.scanningConfig.policy == "ENABLED_BLOCKING" dan actionType: ALLOW.

Menetapkan batasan kustom

Upload dan daftarkan batasan kustom di organisasi Anda dengan perintah gcloud org-policies set-custom-constraint:

gcloud org-policies set-custom-constraint skills-scan-constraint.yaml

Menerapkan kebijakan dengan pengecualian bersyarat

Buat file definisi kebijakan bernama skills-scan-policy.yaml yang menerapkan batasan di semua project standar, sekaligus, misalnya, mengecualikan project pengujian yang Anda beri tag dengan exempt-scanning-enforcement: true:

name: organizations/ORGANIZATION_ID/policies/custom.skillsScanningEnforcement
spec:
  rules:
  # Enforce scanning on all standard projects
  - enforce: true
    condition:
      expression: "!resource.matchTag('ORGANIZATION_ID/exempt-scanning-enforcement', 'true')"
      title: "Enforce Scanning"
      description: "Enforce scanning on all non-exempt projects"
  # Bypass enforcement for tagged projects
  - enforce: false
    condition:
      expression: "resource.matchTag('ORGANIZATION_ID/exempt-scanning-enforcement', 'true')"
      title: "Exempt Testing Projects"
      description: "Allow scanning to be disabled for testing projects"

Ganti ORGANIZATION_ID dengan ID organisasi numerik Anda.

Terapkan kebijakan ke organisasi Anda dengan perintah gcloud org-policies set-policy:

gcloud org-policies set-policy skills-scan-policy.yaml

Memverifikasi kebijakan

Pastikan kebijakan aktif di project dengan perintah gcloud org-policies describe:

gcloud org-policies describe custom.skillsScanningEnforcement \
    --project=PROJECT_ID \
    --effective

Ganti PROJECT_ID dengan project ID Anda.

Meninjau hasil pemindaian dan status revisi

Saat Anda memublikasikan revisi skill, pemindai akan berjalan secara asinkron di latar belakang. Untuk memeriksa metadata revisi dan memverifikasi hasil pemindaian, jalankan perintah gcloud agent-registry skills revisions describe:

gcloud agent-registry skills revisions describe REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION

Ganti kode berikut:

REVISION_ID: ID revisi keahlian.
SKILL_ID: ID penampung keterampilan. Untuk kemampuan yang didaftarkan secara manual, sertakan awalan private-, seperti private-my-skill.
PROJECT_ID: project ID.
LOCATION: lokasi registry.

Outputnya berisi blok scanResult yang terlihat seperti contoh berikut:

name: projects/my-project/locations/us-central1/skills/private-my-skill/revisions/rev-v1
createTime: '2026-08-10T09:15:00.000000Z'
state: ACTIVE
scanResult:
  scanState: SUCCEEDED
  scanTime: '2026-08-10T09:16:22.000000Z'
  findings:
  - projects/my-project/locations/us-central1/findings/b9a8c7d6-e5f4-4321-89ab-cdef01234567

Nilai yang mungkin untuk scanResult.scanState adalah:

SUCCEEDED: pemindaian telah menyelesaikan eksekusi. Jika masalah keamanan terdeteksi, nama resource-nya akan dicantumkan dalam array scanResult.findings. Jika tidak ada masalah yang terdeteksi, scanResult.findings akan kosong.
RUNNING: pemindaian sedang dijalankan secara aktif.
DISABLED: pemindaian dilewati karena kebijakan pemindaian skill ditetapkan ke DISABLED pada saat revisi skill dibuat.
UNSUPPORTED_FORMAT: arsip yang diupload tidak dapat dianalisis oleh pemindai, misalnya, karena ukuran yang tidak dikompresi melebihi batas pemindaian atau format arsipnya tidak didukung. Detailnya diberikan di scanResult.errorMessage.
FAILED: pemindaian tidak dapat diselesaikan karena error internal. Detailnya tersedia di scanResult.errorMessage.

Status pemindaian revisi mencerminkan konfigurasi pemindaian yang aktif pada saat revisi dibuat. Mengaktifkan atau memperbarui pemindaian pada skill hanya berlaku untuk revisi yang dibuat setelah perubahan dan tidak memicu pemindaian secara retroaktif untuk revisi yang ada. Untuk memindai konten keahlian yang diupload saat pemindaian dinonaktifkan, Anda harus membuat revisi keahlian baru.

Menentukan prioritas temuan keamanan

Saat pemindaian mendeteksi masalah keamanan, telemetri mendetail akan dipublikasikan ke Agent Registry sebagai resource Finding yang dicakupkan ke project dan lokasi Anda. Untuk melihat temuan, Anda memerlukan peran Agent Registry API Admin (roles/agentregistry.admin).

Mencantumkan semua temuan untuk revisi skill: jalankan perintah gcloud agent-registry findings list:

gcloud agent-registry findings list \
    --project=PROJECT_ID \
    --location=LOCATION \
    --filter="resource=\"projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID\""

Ganti kode berikut:

PROJECT_ID: project ID.
LOCATION: lokasi registry.
SKILL_ID: ID penampung keterampilan, seperti private-my-skill.
REVISION_ID: ID revisi keahlian.

Outputnya mirip dengan hal berikut ini:

NAME                                                                                  SEVERITY           FINDING_CLASS  CREATE_TIME
projects/my-project/locations/us-central1/findings/FINDING_ID  SEVERITY_CRITICAL  VULNERABILITY  2026-08-10T09:16:22.104Z

Menjelaskan detail temuan: jalankan perintah gcloud agent-registry findings describe:

gcloud agent-registry findings describe FINDING_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format=json

Ganti kode berikut:

FINDING_ID: ID resource Finding.
PROJECT_ID: project ID.
LOCATION: lokasi registry.

Contoh output temuan:

{
  "name": "projects/my-project/locations/us-central1/findings/FINDING_ID",
  "uid": "FINDING_ID",
  "createTime": "2026-08-10T09:16:22.104Z",
  "updateTime": "2026-08-10T09:16:22.104Z",
  "resource": "projects/my-project/locations/us-central1/skills/private-my-skill/revisions/rev-v1",
  "severity": "SEVERITY_CRITICAL",
  "findingClass": "VULNERABILITY",
  "files": [
    {
      "path": "resources/helper.py",
      "lineNumber": "12"
    }
  ],
  "detail": "Involves unauthorized outbound network requests transmitting sensitive local files or environment variables. Detected inside resources/helper.py at line 12."
}

Setiap resource Finding menyertakan kolom kunci berikut:

resource: nama resource lengkap revisi skill yang terkait dengan temuan.
severity: tingkat keseriusan. Nilai yang diperbolehkan adalah:
- SEVERITY_CRITICAL
- SEVERITY_HIGH
- SEVERITY_MEDIUM
- SEVERITY_LOW
- SEVERITY_UNSPECIFIED
findingClass: jenis temuan:
- VULNERABILITY: kelemahan software atau petunjuk.
- SECRET: kredensial, kunci, atau token teks biasa yang terekspos.
files: daftar file yang terpengaruh dalam arsip skill, termasuk path dan lineNumber relatif. Nilai 0 menunjukkan bahwa temuan berlaku untuk seluruh file.
detail: penjelasan mendetail tentang masalah keamanan yang terdeteksi.

Memperbaiki temuan dan mengupdate keterampilan

Untuk menyelesaikan temuan keamanan pada keterampilan, ikuti langkah-langkah berikut:

Tinjau kolom detail dari temuan dan periksa file yang bermasalah path dan lineNumber dalam array files. Karena pemindaian otomatis menggunakan LLM untuk memeriksa kode dan petunjuk semantik, verifikasi nomor baris dan temuan yang dilaporkan sebelum mengubah file Anda.
Perbarui file sumber di lingkungan pengembangan lokal Anda untuk menyelesaikan temuan. Misalnya, hapus panggilan jaringan yang tidak sah, hapus kredensial yang terekspos, atau hilangkan pola injeksi perintah.
Kemas file yang telah diperbarui ke dalam file ZIP baru.
Membuat revisi keahlian baru.
Pastikan bahwa scanResult.scanState revisi baru di-resolve ke SUCCEEDED tanpa temuan yang tercantum.
Perbarui revisi default keahlian untuk mengarah ke revisi yang diverifikasi.

Langkah berikutnya

Pelajari arsitektur keterampilan.
Pelajari cara mendaftarkan keterampilan.
Pelajari cara mengelola revisi keahlian.
Tinjau kuota dan batas sistem.

Memindai keterampilan untuk menemukan masalah keamanan Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Peran yang diperlukan

Batasan ukuran payload yang tidak dikompresi

Mengonfigurasi kebijakan pemindaian untuk keterampilan

Menetapkan atau memperbarui setelan pemindaian keterampilan

Konsol

gcloud

REST

Menerapkan pemindaian menggunakan Organization Policy Service

Menentukan batasan kustom

Menetapkan batasan kustom

Menerapkan kebijakan dengan pengecualian bersyarat

Memverifikasi kebijakan

Meninjau hasil pemindaian dan status revisi

Menentukan prioritas temuan keamanan

Memperbaiki temuan dan mengupdate keterampilan

Langkah berikutnya

Memindai keterampilan untuk menemukan masalah keamanan