Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Verwenden Sie Geheimnisse sicher mit AI Coding Agents Wenn KI-Codierungsagenten Shell- oder AWS API-Zugriff haben, können sie in ihrem Kontextfenster Klartext-Geheimnisse aufrufen `get-secret-value` und empfangen. Dies birgt mehrere Risiken: Geheime Werte können in den Konversationsverlauf, in Protokolle oder nachgeschaltete Tool-Aufrufe gelangen. Um dies zu verhindern, verwenden Sie die Fähigkeit *Secret Safety* im [Agent Toolkit für AWS](https://github.com/aws/agent-toolkit-for-aws). Mit dieser Fähigkeit lernen KI-Agenten, dynamische Referenzen zu verwenden, die zur Laufzeit aufgelöst werden, sodass der Agent die geheime Verwendung orchestriert, ohne jemals den Klartext-Wert zu sehen. **Wichtig** Dabei handelt es sich um eine Verteidigung nach bestem Wissen und nicht um eine Sicherheitsgrenze. Es verhindert den gängigsten Leckagepfad, kann aber nicht alle Ausweichmöglichkeiten verhindern. Kombinieren Sie es mit IAM-Richtlinien für geringste Rechte, CloudTrail Überwachung und VPC-Endpunkte. ## Funktionsweise Die Fähigkeit „Geheime Sicherheit“ bietet zwei Schutzebenen: 1. **Anleitung zum Fachwissen** — Bringt dem Agenten bei, `{{resolve:secretsmanager:...}}` dynamische Referenzen mit einem Wrapper-Skript zu verwenden`asm-exec`, das Verweise zur Laufzeit auflöst. Der Klartext-Wert ist nur im untergeordneten Prozess vorhanden und wird nie im Kontextfenster des Agenten angezeigt. 1. **Strukturelle Durchsetzung (Hook)** — Ein `PreToolUse` Hook blockiert automatisch jeden Versuch AWS CLI, SDK `get-secret-value` - oder `batch-get-secret-value` MCP-Tools oder direkten Zugriff auf den AWS Workload Credentials Provider-Daemon aufzurufen oder zu verwenden. Eine manuelle Konfiguration ist nicht erforderlich. ## Voraussetzungen + Ein KI-Codierungsagent, der Plugins wie [Claude Code](https://docs.anthropic.com/en/docs/claude-code) oder [OpenAI Codex](https://openai.com/index/codex/) unterstützt. + Das [Agent Toolkit für AWS](https://github.com/aws/agent-toolkit-for-aws) `aws-core` das Plugin ist installiert. + Eines der folgenden Backends zur geheimen Auflösung: + AWS Der **Workload Credentials Provider** läuft auf. `localhost:2773` Siehe [Verwendung der AWS Anbieter von Workload-Anmeldeinformationen](workload-credentials-provider.md). + **AWS Anmeldeinformationen**, mit denen Anfragen an den AWS MCP-Endpunkt signiert werden können. + IAM-Berechtigungen: für `secretsmanager:GetSecretValue` die Geheimnisse, die Sie lösen möchten. ## Installieren des Plugins Installieren Sie das `aws-core` Plugin für Ihre Agentenplattform. Die geheime Sicherheitsfähigkeit und der geheime Sicherheitshaken werden automatisch aktiviert. Für Claude Code: ``` claude plugin add ./plugins/aws-core ``` Für OpenAI Codex: ``` codex plugin add ./plugins/aws-core ``` Informationen zu anderen unterstützten Plattformen finden Sie im [Agent Toolkit](https://github.com/aws/agent-toolkit-for-aws) for README.AWS ## Das `{{resolve:...`}} Syntax Wenn der Agent einem Befehl ein Geheimnis übergeben muss, verwendet er eine dynamische Referenz, anstatt aufzurufen`get-secret-value`: ``` {{resolve:secretsmanager::::}} ``` | Komponente | Erforderlich | Standard | Description | | --- | --- | --- | --- | | secret-id | Ja | – | Geheimer Name oder vollständiger ARN | | field-type | Nein | SecretString | Muss SecretString sein. | | json-key | Nein | (voller Wert) | Schlüssel zum Extrahieren aus dem geheimen JSON-Wert | | version-stage | Nein | AWSCURRENT | Bezeichnung der Versionsphase | ## Verwenden Sie `asm-exec, um Befehle` mit Geheimnissen auszuführen `asm-exec`ist ein Wrapper-Skript, das `{{resolve:...}}` Verweise in Befehlsargumenten auflöst und dann den Zielbefehl ausführt. Der geheime Wert ist nur im untergeordneten Prozess vorhanden. ``` asm-exec -- [arguments with {{resolve:...}} references] ``` `asm-exec`löst Verweise über das erste verfügbare Backend auf: 1. **AWS Anbieter für Workload-Anmeldeinformationen aktiviert** `localhost:2773` — lokal zwischengespeichert. 1. **AWS MCP-Endpunkt** — SigV4-signed Anfrage mit verfügbaren Anmeldeinformationen.AWS **Example Stellen Sie eine Connect zu einer PostgreSQL-Datenbank her** ``` asm-exec -- psql \ "host=mydb.example.com \ user={{resolve:secretsmanager:prod/db-creds:SecretString:username}} \ password={{resolve:secretsmanager:prod/db-creds:SecretString:password}}" \ -c "SELECT * FROM users LIMIT 10" ``` **Example Führen Sie einen API-Aufruf mit einem Bearer-Token durch** ``` asm-exec -- curl -H "Authorization: Bearer {{resolve:secretsmanager:prod/api-token}}" \ https://api.example.com/data ``` **Example Stellen Sie mit mehreren Geheimnissen eine Connect zu MySQL her** ``` asm-exec -- mysql \ -h {{resolve:secretsmanager:prod/mysql:SecretString:host}} \ -u {{resolve:secretsmanager:prod/mysql:SecretString:username}} \ -p{{resolve:secretsmanager:prod/mysql:SecretString:password}} \ -e "SHOW TABLES" ``` **Example Übergeben Sie ein Geheimnis als Umgebungsvariable an einen Docker-Container** ``` asm-exec -- docker run \ -e "DB_PASSWORD={{resolve:secretsmanager:prod/db:SecretString:password}}" \ myapp:latest ``` ## Cross-region Geheimnisse Verwenden Sie für Geheimnisse, die in einer anderen Region als Ihrer Standardregion gespeichert sind, entweder den vollständigen ARN (der die Region einschließt) oder legen Sie die `AWS_REGION` Umgebungsvariable fest. ``` # Using full ARN (region is extracted automatically) asm-exec -- curl -H "X-Api-Key: {{resolve:secretsmanager:arn:aws:secretsmanager:eu-west-1:123456789012:secret:prod/key-a1b2c3}}" \ https://eu.api.example.com/data # Using AWS_REGION export AWS_REGION=eu-west-1 asm-exec -- curl -H "X-Api-Key: {{resolve:secretsmanager:prod/key}}" \ https://eu.api.example.com/data ``` ## Sicherheitsüberlegungen + **Isolierung von Unterprozessen** — Der Zielbefehl wird über `subprocess.run` ausgeführt. Geheime Werte existieren nur im `asm-exec` Prozessspeicher und in den Argumenten des untergeordneten Prozesses. ## Wie der Hook den direkten geheimen Zugriff blockiert Wenn das `aws-core` Plugin aktiviert ist, fängt ein `PreToolUse` Hook Werkzeuganrufe vor der Ausführung ab. Es blockiert: + `aws secretsmanager get-secret-value`und `batch-get-secret-value` über CLI + `get_secret_value`und `batch_get_secret_value` über SDK-Aufrufe in Skripten + Direkter Zugriff auf den Daemon-Pfad () `localhost:2773/secretsmanager/get` des AWS Workload Credentials Provider + `GetSecretValue`Operationen über MCP-Tools oder strukturierte API-Aufrufe AWS Wenn ein Anruf blockiert wird, erhält der Agent eine Ablehnungsnachricht, in der er angewiesen wird, `asm-exec` stattdessen `{{resolve:...}}` Referenzen mit zu verwenden. ## Fehlerbehebung ### Fehler „Geheimnis nicht gefunden“ Stellen Sie sicher, dass das Geheimnis existiert und dass Ihre IAM-Rolle über die entsprechenden `secretsmanager:GetSecretValue` Berechtigungen verfügt. Bei geheimen Namen wird zwischen Groß- und Kleinschreibung unterschieden. ### AWS Die Verbindung zum Workload Credentials Provider wurde verweigert Der AWS Workload Credentials Provider läuft möglicherweise nicht. Das ist nicht fatal — es `asm-exec` geht bis zum SigV4-signed MCP-Endpunkt. Stellen Sie sicher, dass AWS Anmeldeinformationen verfügbar sind, damit sich das Backend authentifizieren kann. ### Fehler „Konnten nicht behoben werden“ Beide Backends waren nicht erreichbar. Prüfen Sie, ob entweder der AWS Workload Credentials Provider läuft oder ob die AWS Anmeldeinformationen gültig sind (`aws sts get-caller-identity`), ob die Region des Secrets korrekt ist und ob Ihre Identität `secretsmanager:GetSecretValue` auf dem Secret steht. ### Die Auflösung erzeugt eine leere Zeichenfolge Der JSON-Schlüssel ist möglicherweise nicht im geheimen Wert enthalten. Überprüfen Sie die geheime Struktur in der AWS Konsole oder bitten Sie den geheimen Besitzer, die verfügbaren Schlüssel zu bestätigen. ### Hook blockiert keinen Anruf Hooks werden beim Start der Agentensitzung geladen. Wenn Sie das Plugin während der Sitzung installiert haben, starten Sie die Agentensitzung neu, damit der Hook aktiviert wird.