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

Funktionsweise

Die Fähigkeit „Geheime Sicherheit“ bietet zwei Schutzebenen:

Voraussetzungen

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 for README.AWS

Das {{resolve:...}} Syntax

Wenn der Agent einem Befehl ein Geheimnis übergeben muss, verwendet er eine dynamische Referenz, anstatt aufzurufenget-secret-value:

{{resolve:secretsmanager:<secret-id>:<field-type>:<json-key>:<version-stage>}}

Verwenden Sie asm-exec, um Befehle mit Geheimnissen auszuführen

asm-execist 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 -- <command> [arguments with {{resolve:...}} references]

asm-execlöst Verweise über das erste verfügbare Backend auf:

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"

asm-exec -- curl -H "Authorization: Bearer {{resolve:secretsmanager:prod/api-token}}" \
  https://api.example.com/data

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"

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

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:

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.