Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Skills auf Sicherheitsprobleme scannen

Mit der Agent Registry können Sie automatisierte Sicherheitsscans für eigenständige Skills konfigurieren, Scanrichtlinien in Ihrer Organisation mithilfe des Organisationsrichtliniendienstes erzwingen und Sicherheitsergebnisse priorisieren, um zu verhindern, dass kompromittierte Skills Ihre Agenten erreichen.

Wenn Sie eine Skill-Version hochladen, scannt die Agent Registry die SKILL.md-Anweisungsdatei, optionale Skripts und unterstützende Assets auf Sicherheitsrisiken wie nicht autorisierte Daten-Exfiltration, offengelegte Anmeldedaten und Prompt Injection.

Beim Skill-Sicherheitsscan werden Large Language Models (LLMs) verwendet, um Anweisungen, Codelogik und semantische Absichten zu bewerten. Da die LLM-Analyse probabilistisch ist, können Scans falsch positive oder falsch negative Ergebnisse liefern und die Ergebnisse können von Ausführung zu Ausführung variieren. Außerdem können die Details zu den Ergebnissen ungenau sein und Halluzinationen enthalten. Entwickler müssen die Scanergebnisse prüfen und bestätigen, bevor sie Änderungen zur Behebung vornehmen.

Hinweis

Agent Registry einrichten
Rufen Sie für eine Einrichtung mit einem einzelnen Projekt die Projekt-ID des Governance-Projekts ab, in dem die Agent Registry aktiviert ist. Wenn Sie eine Verwaltungsgrenze für mehrere Projekte konfiguriert haben, verwenden Sie die Projekt-ID Ihres Verwaltungsprojekts für die grenzübergreifende Erkennung und Registrierung oder geben Sie eine Mitgliedsprojekt-ID für Vorgänge in einem einzelnen Projekt an.
Registrieren Sie einen eigenständigen Skill in der Agent Registry.
Wenn Sie die Google Cloud CLI-Befehle in diesem Dokument verwenden möchten, richten Sie Ihre gcloud CLI-Umgebung ein.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Governance-Projekt zuzuweisen, in dem Agent Registry aktiviert ist, um die Berechtigungen zu erhalten, die Sie zum Konfigurieren von Scans und zum Selektieren von Ergebnissen in Agent Registry benötigen:

Konfigurieren Sie das Scannen von Skills: Agent Registry User (roles/agentregistry.user)
Skills und Skill-Versionen ansehen: Agent Registry API Viewer (roles/agentregistry.viewer)
Sicherheitsergebnisse ansehen und auflisten: Agent Registry API Admin (roles/agentregistry.admin)
Scanrichtlinien auf Organisations- oder Ordnerebene erzwingen: Administrator für Organisationsrichtlinien (roles/orgpolicy.policyAdmin)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Andere Agent Registry-Rollen enthalten möglicherweise auch die Berechtigungen, die zum Konfigurieren von Scans und zum Aufrufen von Skills erforderlich sind. Weitere Informationen finden Sie unter Agent Registry-Rollen und -Berechtigungen.

Größenbeschränkungen für unkomprimierte Nutzlasten

Um eine optimale Leistung zu gewährleisten und die Verarbeitungstokenlimits für die zugrunde liegenden LLM-Scanner zu berücksichtigen, erzwingt die Agent Registry strenge Limits für die unkomprimierte Größe, wenn das Scannen aktiv ist:

Gesamtgröße des unkomprimierten Skills: maximal 10 MB für das extrahierte Archiv.
Größe pro unkomprimierter Datei: maximal 1 MB für jede einzelne Datei im Skill-Paket.

Wenn für einen Skill das Scannen aktiviert ist und diese Limits überschritten werden, schlägt das Erstellen einer Skill-Version mit dem Fehler INVALID_ARGUMENT fehl oder der Scanstatus der Version wird zu UNSUPPORTED_FORMAT aufgelöst.

Wenn das Scannen explizit deaktiviert ist, umgeht die Agent Registry diese scanningspezifischen Größenbeschränkungen. Es gelten jedoch weiterhin die allgemeinen Systemlimits. Weitere Informationen zu Systemlimits finden Sie unter Kontingente und Systemlimits.

Scanrichtlinie für einen Skill konfigurieren

Standardmäßig verwenden Skills die Scanrichtlinie Aktiviert (Blockieren) (ENABLED_BLOCKING), die hochgeladene Skill-Versionen automatisch auf Sicherheitsrisiken wie unbefugte Daten-Exfiltration, offengelegte Anmeldedaten und Prompt Injection scannt. Erkannte Probleme werden als schreibgeschützte Finding-Ressourcen in Ihrem Governance-Projekt angezeigt: projects/PROJECT_NUMBER/locations/LOCATION/findings/FINDING_ID.

Wenn Aktiviert (Blockieren) ausgewählt ist, blockiert die Agent Registry das Herunterladen von Versionen mit Sicherheitsergebnissen und verhindert, dass Versionen mit Ergebnissen oder ausstehenden Scans als Standardversion des Skills hochgestuft werden.

Sie können auch Scanrichtlinien für den nicht blockierenden Prüfmodus (ENABLED_NONBLOCKING) konfigurieren oder das Scannen deaktivieren (DISABLED). Weitere Informationen zu unterstützten Scanrichtlinien finden Sie unter Scanrichtlinien.

Einstellungen für Skill-Scans festlegen oder aktualisieren

Wenn Sie das Scannen für einen vorhandenen Skill aktivieren oder aktualisieren, gilt dies nur für Skill-Versionen, die nach der Konfigurationsänderung erstellt wurden. Das Scannen wird nicht rückwirkend für bereits erstellte Überarbeitungen ausgelöst. Wenn Sie Skill-Inhalte scannen möchten, die hochgeladen wurden, als das Scannen deaktiviert war, müssen Sie eine neue Skill-Überarbeitung erstellen.

So konfigurieren Sie die Scaneinstellungen beim Erstellen oder Aktualisieren eines Skills:

Console

Rufen Sie in der Google Cloud Console die Seite Agent Registry auf:

Zur Agent Registry
Wählen Sie den Tab Skills aus.
Klicken Sie auf Skill hinzufügen oder wählen Sie einen vorhandenen Skill aus und klicken Sie auf Bearbeiten.
Wählen Sie im Abschnitt Sicherheitsscans die gewünschte Scanrichtlinie aus.
Klicken Sie auf Speichern oder Erstellen.

gcloud

Skill mit aktiviertem Scannen (Blockieren) erstellen: Führen Sie den Befehl gcloud agent-registry skills create mit dem Flag --scanning-policy aus, das auf enabled-blocking gesetzt ist. Wenn Sie beispielsweise einen Skill mit einem ZIP-Archiv aus einem Cloud Storage-Bucket registrieren:
```
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"
```
Skill mit aktiviertem Scannen erstellen (nicht blockierend): Führen Sie den Befehl gcloud agent-registry skills create mit dem Flag --scanning-policy auf enabled-nonblocking gesetzt aus. Wenn Sie beispielsweise einen Skill mit einem ZIP-Archiv aus einem Cloud Storage-Bucket registrieren:
```
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"
```
Scanrichtlinie für einen vorhandenen Skill aktualisieren: Führen Sie den Befehl gcloud agent-registry skills update aus, wobei das Flag --scanning-policy auf die ausgewählte Richtlinie festgelegt ist, z. B. enabled-nonblocking:
```
gcloud agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --scanning-policy=enabled-nonblocking
```
Scannen für einen Skill deaktivieren: Führen Sie den Befehl gcloud agent-registry skills update aus, wobei das Flag --scanning-policy auf disabled gesetzt ist:
```
gcloud agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --scanning-policy=disabled
```
Scankonfiguration für einen vorhandenen Skill beschreiben: Führen Sie den Befehl gcloud agent-registry skills describe aus, wobei das Flag --format auf value(scanningConfig.policy) gesetzt ist:
```
gcloud agent-registry skills describe SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format="value(scanningConfig.policy)"
```

Ersetzen Sie Folgendes:

SKILL_ID: die ID des Skills. Wenn Sie einen vorhandenen manuell registrierten Skill aktualisieren oder beschreiben, fügen Sie das Präfix private- hinzu, z. B. private-my-skill.
PROJECT_ID: Projekt-ID.
LOCATION: der Standort der Registry.
BUCKET_NAME: der Name des Cloud Storage-Bucket, der das ZIP-Bundle enthält. Bevor Sie Daten aus einem Bucket importieren, muss der Agent Registry-Dienst-Agent die Berechtigung storage.objects.get für den Bucket haben. Weitere Informationen finden Sie unter Skill registrieren.
SKILL_PACKAGE: der Name des Skill-Pakets, das die Skill-Nutzlast enthält.

REST

Wenn Sie das Scannen mit der REST API konfigurieren möchten, fügen Sie das Objekt scanningConfig in den Anfragetext ein:

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"

Ersetzen Sie Folgendes:

PROJECT_ID: Projekt-ID.
LOCATION: der Standort der Registry.
SKILL_ID: die ID des Skills. Geben Sie für manuell registrierte Skills das Präfix private- an, z. B. private-my-skill.

Scans mit dem Organisationsrichtliniendienst erzwingen

Sie können organisationsweite Scanrichtlinien erzwingen, indem Sie eine benutzerdefinierte Einschränkung für den Organisationsrichtliniendienst für die Ressource Skill definieren, die die Scanrichtlinie auswertet, mit optionalen Ausnahmen für Resource Manager-Tags.

Informationen zur Durchsetzung von Organisationsrichtlinien in Agent Registry, zu den Funktionen und Einschränkungen finden Sie unter Durchsetzung von Organisationsrichtlinien.

Benutzerdefinierte Einschränkung definieren

Erstellen Sie eine YAML-Datei mit dem Namen skills-scan-constraint.yaml und der folgenden Spezifikation:

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.

Ersetzen Sie ORGANIZATION_ID durch die numerische Organisations-ID.

Wenn Sie den Blockierungsmodus für alle Fähigkeiten erzwingen und sowohl DISABLED- als auch ENABLED_NONBLOCKING-Scanrichtlinien verhindern möchten, können Sie alternativ condition: resource.scanningConfig.policy == "ENABLED_BLOCKING" und actionType: ALLOW festlegen.

Benutzerdefinierte Einschränkung festlegen

Laden Sie die benutzerdefinierte Einschränkung mit dem Befehl gcloud org-policies set-custom-constraint in Ihre Organisation hoch und registrieren Sie sie:

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

Richtlinie mit bedingten Ausnahmen anwenden

Erstellen Sie eine Richtliniendefinitionsdatei mit dem Namen skills-scan-policy.yaml, die die Einschränkung für alle Standardprojekte erzwingt, aber beispielsweise Testprojekte ausnimmt, die Sie mit exempt-scanning-enforcement: true getaggt haben:

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"

Ersetzen Sie ORGANIZATION_ID durch die numerische Organisations-ID.

Wenden Sie die Richtlinie mit dem Befehl gcloud org-policies set-policy auf Ihre Organisation an:

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

Richtlinie prüfen

Prüfen Sie mit dem Befehl gcloud org-policies describe, ob die Richtlinie für ein Projekt aktiv ist:

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

Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID.

Scanergebnisse und Überarbeitungsstatus prüfen

Wenn Sie eine Skill-Überarbeitung veröffentlichen, wird der Scanner asynchron im Hintergrund ausgeführt. Führen Sie den Befehl gcloud agent-registry skills revisions describe aus, um die Metadaten der Überarbeitung zu prüfen und das Scanergebnis zu verifizieren:

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

Ersetzen Sie Folgendes:

REVISION_ID: die ID der Skill-Version.
SKILL_ID: die ID des Skill-Containers. Geben Sie bei manuell registrierten Skills das Präfix private- an, z. B. private-my-skill.
PROJECT_ID: Projekt-ID.
LOCATION: der Standort der Registry.

Die Ausgabe enthält den Block scanResult, der in etwa so aussieht:

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

Folgende Werte sind für scanResult.scanState möglich:

SUCCEEDED: Der Scan wurde abgeschlossen. Wenn Sicherheitsprobleme erkannt werden, werden die Ressourcennamen im Array scanResult.findings aufgeführt. Wenn keine Probleme erkannt werden, ist scanResult.findings leer.
RUNNING: Der Scan wird gerade ausgeführt.
DISABLED: Der Scan wird übersprungen, da die Scanrichtlinie des Skills zum Zeitpunkt der Erstellung der Skill-Version auf DISABLED festgelegt ist.
UNSUPPORTED_FORMAT: Das hochgeladene Archiv kann vom Scanner nicht analysiert werden, z. B. weil die unkomprimierte Größe die Scanlimits überschreitet oder das Archivformat nicht unterstützt wird. Weitere Informationen finden Sie unter scanResult.errorMessage.
FAILED: Der Scan kann aufgrund eines internen Fehlers nicht abgeschlossen werden. Details finden Sie unter scanResult.errorMessage.

Der Scanstatus einer Version spiegelt die Scankonfiguration wider, die zum Zeitpunkt der Erstellung der Version aktiv war. Das Aktivieren oder Aktualisieren des Scannens für einen Skill gilt nur für Versionen, die nach der Änderung erstellt wurden. Für vorhandene Versionen wird kein Scan rückwirkend ausgelöst. Wenn Sie Skill-Inhalte scannen möchten, die hochgeladen wurden, als das Scannen deaktiviert war, müssen Sie eine neue Skill-Version erstellen.

Sicherheitsergebnisse priorisieren

Wenn bei einem Scan Sicherheitsprobleme erkannt werden, werden detaillierte Telemetriedaten in der Agent Registry als Finding-Ressourcen veröffentlicht, die auf Ihr Projekt und Ihren Standort beschränkt sind. Zum Ansehen von Ergebnissen ist die Rolle „Agent Registry API Admin“ (roles/agentregistry.admin) erforderlich.

Alle Ergebnisse für eine Skill-Version auflisten: Führen Sie den Befehl gcloud agent-registry findings list aus:

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

Ersetzen Sie Folgendes:

PROJECT_ID: Projekt-ID.
LOCATION: der Standort der Registry.
SKILL_ID: die ID des Skill-Containers, z. B. private-my-skill.
REVISION_ID: die ID der Skill-Version.

Die Ausgabe sieht etwa so aus:

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

Ergebnisdetails beschreiben: Führen Sie den Befehl gcloud agent-registry findings describe aus:
```
gcloud agent-registry findings describe FINDING_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format=json
```
Ersetzen Sie Folgendes:
- FINDING_ID: die ID der Finding-Ressource.
- PROJECT_ID: Projekt-ID.
- LOCATION: der Standort der Registry.
Beispiel für die Ausgabe eines Ergebnisses:
```
{
  "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."
}
```
Jede Finding-Ressource enthält die folgenden Schlüsselfelder:
- resource: der vollständige Ressourcenname der Skill-Version, die mit dem Ergebnis verknüpft ist.
- severity: der Schweregrad. Zulässige Werte sind:
  - SEVERITY_CRITICAL
  - SEVERITY_HIGH
  - SEVERITY_MEDIUM
  - SEVERITY_LOW
  - SEVERITY_UNSPECIFIED
- findingClass: die Art des Ergebnisses:
  - VULNERABILITY: eine Schwachstelle in der Software oder in den Anweisungen.
  - SECRET: offengelegte Klartext-Anmeldedaten, ‑Schlüssel oder ‑Tokens.
- files: die Liste der betroffenen Dateien im Skill-Archiv, einschließlich der relativen path und lineNumber. Der Wert 0 gibt an, dass das Ergebnis für die gesamte Datei gilt.
- detail: eine detaillierte Erklärung des erkannten Sicherheitsproblems.

Ergebnisse korrigieren und Fähigkeiten aktualisieren

So beheben Sie Sicherheitsergebnisse für einen Skill:

Prüfen Sie das Feld detail des Ergebnisses und die fehlerhafte Datei path und lineNumber im Array files. Da beim automatischen Scannen LLMs verwendet werden, um semantischen Code und Anweisungen zu prüfen, sollten Sie die gemeldeten Zeilennummern und Ergebnisse überprüfen, bevor Sie Ihre Dateien ändern.
Aktualisieren Sie die Quelldateien in Ihrer lokalen Entwicklungsumgebung, um das Ergebnis zu beheben. Entfernen Sie beispielsweise nicht autorisierte Netzwerkaufrufe, entfernen Sie offengelegte Anmeldedaten oder eliminieren Sie Prompt-Injection-Muster.
Verpacken Sie die aktualisierten Dateien in ein neues ZIP-Archiv.
Neue Skill-Version erstellen
Prüfen Sie, ob die scanResult.scanState der neuen Überarbeitung in SUCCEEDED aufgelöst wird und keine Ergebnisse aufgeführt sind.
Aktualisieren Sie die Standardversion des Skills, sodass sie auf die verifizierte Version verweist.

Skills auf Sicherheitsprobleme scannen Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Hinweis

Erforderliche Rollen

Größenbeschränkungen für unkomprimierte Nutzlasten

Scanrichtlinie für einen Skill konfigurieren

Einstellungen für Skill-Scans festlegen oder aktualisieren

Console

gcloud

REST

Scans mit dem Organisationsrichtliniendienst erzwingen

Benutzerdefinierte Einschränkung definieren

Benutzerdefinierte Einschränkung festlegen

Richtlinie mit bedingten Ausnahmen anwenden

Richtlinie prüfen

Scanergebnisse und Überarbeitungsstatus prüfen

Sicherheitsergebnisse priorisieren

Ergebnisse korrigieren und Fähigkeiten aktualisieren

Nächste Schritte

Skills auf Sicherheitsprobleme scannen