AWS Secrets Manager Agent - AWS Secrets Manager
Étape 1 : Création du binaire de l'agent Secrets ManagerÉtape 2 : Installation de l'agent Secrets ManagerÉtape 3 : récupérer des secrets avec l'agent Secrets ManagerActualisez de force les secrets avec RefreshNowFichier de configurationJournalisationConsidérations sur la sécurité

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

AWS Secrets Manager Agent

L' AWS Secrets Manager agent est un service HTTP côté client que vous pouvez utiliser pour normaliser la consommation des secrets issus de Secrets Manager dans des environnements tels qu'Amazon Elastic Container Service, AWS Lambda Amazon Elastic Kubernetes Service et Amazon Elastic Compute Cloud. L'agent Secrets Manager peut récupérer et mettre en cache des secrets en mémoire afin que vos applications puissent les utiliser directement depuis le cache. Cela signifie que vous pouvez récupérer les secrets dont votre application a besoin auprès de l'hôte local au lieu d'appeler Secrets Manager. L'agent Secrets Manager peut uniquement envoyer des demandes de lecture à Secrets Manager ; il ne peut pas modifier les secrets.

L'agent Secrets Manager utilise les AWS informations d'identification que vous fournissez dans votre environnement pour appeler Secrets Manager. L'agent Secrets Manager offre une protection contre la falsification des requêtes côté serveur (SSRF) afin d'améliorer la sécurité des secrets. Vous pouvez configurer l'agent Secrets Manager en définissant le nombre maximum de connexions, la durée de vie (TTL), le port HTTP localhost et la taille du cache.

Comme l'agent Secrets Manager utilise un cache en mémoire, il est réinitialisé au redémarrage de l'agent Secrets Manager. L'agent Secrets Manager actualise régulièrement la valeur du secret mis en cache. L'actualisation a lieu lorsque vous essayez de lire un secret depuis l'agent Secrets Manager après l'expiration du TTL. La fréquence de rafraîchissement (TTL) par défaut est de 300 secondes, et vous pouvez la modifier en utilisant une Fichier de configuration valeur que vous transmettez à l'agent Secrets Manager à l'aide de l'argument de ligne de --config commande. L'agent Secrets Manager n'inclut pas l'invalidation du cache. Par exemple, si un secret change avant l'expiration de l'entrée du cache, l'agent Secrets Manager peut renvoyer une valeur secrète périmée.

L'agent Secrets Manager renvoie les valeurs secrètes dans le même format que la réponse deGetSecretValue. Les valeurs secrètes ne sont pas chiffrées dans le cache.

Pour télécharger le code source, voir https://github.com/aws/aws-secretsmanager-agentci-dessous GitHub.

Étape 1 : Création du binaire de l'agent Secrets Manager

Pour créer le binaire de l'agent Secrets Manager de manière native, vous avez besoin des outils de développement standard et des outils Rust. Vous pouvez également effectuer une compilation croisée pour les systèmes qui le supportent, ou vous pouvez utiliser Rust Cross pour effectuer une compilation croisée.

RPM-based systems

  1. Sur les systèmes basés sur le RPM tels que AL2 023, vous pouvez installer les outils de développement à l'aide du groupe Outils de développement.

    sudo yum -y groupinstall "Development Tools"

  2. Suivez les instructions de la section Installer Rust dans la documentation Rust.

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env"

  3. Créez l'agent à l'aide de la commande cargo build :

    cargo build --release

    Vous trouverez le fichier exécutable soustarget/release/aws-secrets-manager-agent.

Debian-based systems

  1. Sur les systèmes basés sur Debian tels qu'Ubuntu, vous pouvez installer les outils de développement à l'aide du package build-essential.

    sudo apt install build-essential

  2. Suivez les instructions de la section Installer Rust dans la documentation Rust.

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env"

  3. Créez l'agent à l'aide de la commande cargo build :

    cargo build --release

    Vous trouverez le fichier exécutable soustarget/release/aws-secrets-manager-agent.

Windows

Pour créer sous Windows, suivez les instructions de la section Configurer votre environnement de développement sous Windows pour Rust dans la documentation Microsoft Windows.

Cross-compile natively

Sur les distributions où le package mingw-w64 est disponible, comme Ubuntu, vous pouvez effectuer une compilation croisée en mode natif.

# Install the cross compile tool chain
sudo add-apt-repository universe
sudo apt install -y mingw-w64
    
# Install the rust build targets
rustup target add x86_64-pc-windows-gnu
    
# Cross compile the agent for Windows
cargo build --release --target x86_64-pc-windows-gnu

Vous trouverez le fichier exécutable à l'adressetarget/x86_64-pc-windows-gnu/release/aws-secrets-manager-agent.exe.

Cross compile with Rust cross

Si les outils de compilation croisée ne sont pas disponibles nativement sur le système, vous pouvez utiliser le projet croisé Rust. Pour plus d'informations, voir https://github.com/cross-rs/croix.

Important

Nous recommandons 32 Go d'espace disque pour l'environnement de génération.

# Install and start docker
sudo yum -y install docker
sudo systemctl start docker
sudo systemctl enable docker # Make docker start after reboot
    
# Give ourselves permission to run the docker images without sudo
sudo usermod -aG docker $USER
newgrp docker
    
# Install cross and cross compile the executable
cargo install cross
cross build --release --target x86_64-pc-windows-gnu

Étape 2 : Installation de l'agent Secrets Manager

Selon le type de calcul, plusieurs options s'offrent à vous pour installer l'agent Secrets Manager.

Amazon EKS, Amazon EC2, and Amazon ECS
Pour installer l'agent Secrets Manager

  1. Utilisez le install script fourni dans le référentiel.

    Le script génère un jeton SSRF aléatoire au démarrage et le stocke dans le fichier/var/run/awssmatoken. Le jeton est lisible par le awssmatokenreader groupe créé par le script d'installation.

  2. Pour permettre à votre application de lire le fichier de jetons, vous devez ajouter au awssmatokenreader groupe le compte utilisateur sous lequel votre application s'exécute. Par exemple, vous pouvez autoriser votre application à lire le fichier de jetons à l'aide de la commande usermod suivante, où <APP_USER> est l'ID utilisateur sous lequel votre application s'exécute.

    sudo usermod -aG awssmatokenreader <APP_USER>
Docker

Vous pouvez exécuter l'agent Secrets Manager en tant que conteneur annexe à votre application à l'aide de Docker. Votre application peut ensuite récupérer les secrets depuis le serveur HTTP local fourni par l'agent Secrets Manager. Pour plus d'informations sur Docker, consultez la documentation Docker.

Pour créer un conteneur annexe pour l'agent Secrets Manager avec Docker

  1. Créez un Dockerfile pour le conteneur annexe de l'agent Secrets Manager. L'exemple suivant crée un conteneur Docker avec le binaire de l'agent Secrets Manager.

    # Use the latest Debian image as the base
FROM debian:latest

# Set the working directory inside the container
WORKDIR /app 

# Copy the Secrets Manager Agent binary to the container
COPY secrets-manager-agent . 

# Install any necessary dependencies
RUN apt-get update && apt-get install -y ca-certificates 

# Set the entry point to run the Secrets Manager Agent binary
ENTRYPOINT ["./secrets-manager-agent"]

  2. Créez un Dockerfile pour votre application cliente.

  3. Créez un fichier Docker Compose pour exécuter les deux conteneurs, en vous assurant qu'ils utilisent la même interface réseau. Cela est nécessaire car l'agent Secrets Manager n'accepte pas les demandes provenant de l'extérieur de l'interface localhost. L'exemple suivant montre un fichier Docker Compose dans lequel la network_mode clé attache le secrets-manager-agent conteneur à l'espace de noms réseau du client-application conteneur, ce qui leur permet de partager la même interface réseau.

    Important

    Vous devez charger les AWS informations d'identification et le jeton SSRF pour que l'application puisse utiliser l'agent Secrets Manager. Notez ce qui suit :

    version: '3'
services:
    client-application:
    container_name: client-application
    build:
        context: .
        dockerfile: Dockerfile.client
    command: tail -f /dev/null  # Keep the container running
    

    secrets-manager-agent:
    container_name: secrets-manager-agent
    build:
        context: .
        dockerfile: Dockerfile.agent
    network_mode: "container:client-application"  # Attach to the client-application container's network
    depends_on:
        - client-application

  4. Copiez le secrets-manager-agent fichier binaire dans le même répertoire que celui qui contient vos fichiers Dockerfiles et Docker Compose.

  5. Créez et exécutez les conteneurs en fonction des Dockerfiles fournis à l'aide de la commande suivante docker-compose.

    docker-compose up --build

  6. Dans votre conteneur client, vous pouvez désormais utiliser l'agent Secrets Manager pour récupérer des secrets. Pour de plus amples informations, veuillez consulter Étape 3 : récupérer des secrets avec l'agent Secrets Manager.

AWS Lambda

Vous pouvez empaqueter l'agent Secrets Manager sous forme d' AWS Lambda extension. Vous pouvez ensuite l'ajouter à votre fonction Lambda sous forme de couche et appeler l'agent Secrets Manager depuis votre fonction Lambda pour obtenir des secrets.

Les instructions suivantes montrent comment obtenir un nom de secret à l'aide MyTest de l'exemple de script https://github.com/aws/aws-secretsmanager-agentpour installer l'agent Secrets Manager secrets-manager-agent-extension.sh en tant qu'extension Lambda.

Note

L'exemple de script utilise la curl commande, qui est incluse dans les environnements d'exécution basés sur Amazon Linux 2023 tels que Python 3.12 et Node.js 20. Si vous utilisez un environnement d'exécution basé sur Amazon Linux 2 tel que Python 3.11 ou Node.js 18, vous devez d'abord l'installer curl dans votre image de conteneur Lambda. Pour obtenir des instructions, consultez Comment utiliser les packages binaires natifs de l'AMI Amazon Linux 2 avec Lambda sur AWS Re:Post.

Pour créer une extension Lambda qui empaquète l'agent Secrets Manager

  1. Créez une fonction Lambda en Python qui interroge http://localhost:2773/secretsmanager/get?secretId=MyTest pour obtenir le secret. Veillez à implémenter une logique de nouvelle tentative dans le code de votre application afin de prendre en compte les délais d'initialisation et d'enregistrement de l'extension Lambda.

  2. À la racine du package de code de l'agent Secrets Manager, exécutez les commandes suivantes pour tester l'extension Lambda.

    AWS_ACCOUNT_ID=<AWS_ACCOUNT_ID>
LAMBDA_ARN=<LAMBDA_ARN>

# Build the release binary 
cargo build --release --target=x86_64-unknown-linux-gnu

# Copy the release binary into the `bin` folder
mkdir -p ./bin
cp ./target/x86_64-unknown-linux-gnu/release/aws_secretsmanager_agent ./bin/secrets-manager-agent

# Copy the `secrets-manager-agent-extension.sh` script into the `extensions` folder.
mkdir -p ./extensions
cp aws_secretsmanager_agent/examples/example-lambda-extension/secrets-manager-agent-extension.sh ./extensions

# Zip the extension shell script and the binary 
zip secrets-manager-agent-extension.zip bin/* extensions/*

# Publish the layer version
LAYER_VERSION_ARN=$(aws lambda publish-layer-version \
    --layer-name secrets-manager-agent-extension \
    --zip-file "fileb://secrets-manager-agent-extension.zip" | jq -r '.LayerVersionArn')

# Attach the layer version to the Lambda function
aws lambda update-function-configuration \
    --function-name $LAMBDA_ARN \
    --layers "$LAYER_VERSION_ARN"

  3. Appelez la fonction Lambda pour vérifier que le secret est correctement extrait.

Étape 3 : récupérer des secrets avec l'agent Secrets Manager

Pour utiliser l'agent, vous devez appeler le point de terminaison local de l'agent Secrets Manager et inclure le nom ou l'ARN du secret en tant que paramètre de requête. Par défaut, l'agent Secrets Manager récupère la AWSCURRENT version du secret. Pour récupérer une autre version, vous pouvez définir versionStage ouversionId.

Pour protéger l'agent Secrets Manager, vous devez inclure un en-tête de jeton SSRF dans chaque demande :X-Aws-Parameters-Secrets-Token. L'agent Secrets Manager refuse les demandes qui ne contiennent pas cet en-tête ou qui contiennent un jeton SSRF non valide. Vous pouvez personnaliser le nom de l'en-tête SSRF dans leFichier de configuration.

L'agent Secrets Manager utilise le AWS SDK pour Rust, qui utilise la chaîne de fournisseurs d'informations d'identification par défaut. L'identité de ces informations d'identification IAM détermine les autorisations dont dispose l'agent Secrets Manager pour récupérer les secrets.

Autorisations requises :

  • secretsmanager:DescribeSecret

  • secretsmanager:GetSecretValue

Pour de plus amples informations, veuillez consulter Référence des autorisations .

Important

Une fois la valeur secrète saisie dans l'agent Secrets Manager, tout utilisateur ayant accès à l'environnement informatique et au jeton SSRF peut accéder au secret depuis le cache de l'agent Secrets Manager. Pour de plus amples informations, veuillez consulter Considérations sur la sécurité.

curl

L'exemple de curl suivant montre comment obtenir un secret auprès de l'agent Secrets Manager. L'exemple repose sur la présence du SSRF dans un fichier, où il est stocké par le script d'installation.

curl -v -H \
    "X-Aws-Parameters-Secrets-Token: $(</var/run/awssmatoken)" \
    'http://localhost:2773/secretsmanager/get?secretId=<YOUR_SECRET_ID>'; \
    echo
Python

L'exemple Python suivant montre comment obtenir un secret à partir de l'agent Secrets Manager. L'exemple repose sur la présence du SSRF dans un fichier, où il est stocké par le script d'installation.

import requests
import json

# Function that fetches the secret from Secrets Manager Agent for the provided secret id. 
def get_secret():
    # Construct the URL for the GET request
    url = f"http://localhost:2773/secretsmanager/get?secretId=<YOUR_SECRET_ID>"

    # Get the SSRF token from the token file
    with open('/var/run/awssmatoken') as fp:
        token = fp.read() 

    headers = {
        "X-Aws-Parameters-Secrets-Token": token.strip()
    }

    try:
        # Send the GET request with headers
        response = requests.get(url, headers=headers)

        # Check if the request was successful
        if response.status_code == 200:
            # Return the secret value
            return response.text
        else:
            # Handle error cases
            raise Exception(f"Status code {response.status_code} - {response.text}")

    except Exception as e:
        # Handle network errors
        raise Exception(f"Error: {e}")

Actualisez de force les secrets avec RefreshNow

L'agent Secrets Manager utilise un cache en mémoire pour stocker les valeurs secrètes, qu'il actualise régulièrement. Par défaut, cette actualisation a lieu lorsque vous demandez un secret après l'expiration du délai de vie (TTL), généralement toutes les 300 secondes. Cependant, cette approche peut parfois entraîner des valeurs secrètes périmées, en particulier si un secret change avant l'expiration de l'entrée du cache.

Pour pallier cette limitation, l'agent Secrets Manager prend en charge un paramètre appelé refreshNow dans l'URL. Vous pouvez utiliser ce paramètre pour forcer l'actualisation immédiate de la valeur d'un secret, en contournant le cache et en vous assurant de disposer du maximum up-to-date d'informations.

Comportement par défaut (sansrefreshNow)

  • Utilise les valeurs mises en cache jusqu'à l'expiration du TTL

  • Actualise les secrets uniquement après TTL (300 secondes par défaut)

  • Peut renvoyer des valeurs périmées si les secrets changent avant l'expiration du cache

Comportement avec refreshNow=true

  • Contourne complètement le cache

  • Récupère la dernière valeur secrète directement depuis Secrets Manager

  • Met à jour le cache avec la nouvelle valeur et réinitialise le TTL

  • Garantit que vous obtenez toujours la valeur secrète la plus récente

En utilisant ce refreshNow paramètre, vous pouvez vous assurer de toujours travailler avec les valeurs secrètes les plus récentes, même dans les scénarios où une rotation fréquente des secrets est nécessaire.

refreshNowcomportement des paramètres

refreshNowréglé sur true

Si l'agent Secrets Manager ne parvient pas à récupérer le secret depuis Secrets Manager, il renvoie une erreur et ne met pas à jour le cache.

refreshNowdéfini sur false ou non spécifié

L'agent Secrets Manager suit son comportement par défaut :

  • Si la valeur mise en cache est plus récente que le TTL, l'agent Secrets Manager renvoie la valeur mise en cache.

  • Si la valeur mise en cache est plus ancienne que le TTL, l'agent Secrets Manager appelle Secrets Manager.

Utilisation du paramètre RefreshNow

Pour utiliser le refreshNow paramètre, incluez-le dans l'URL de la requête GET de l'agent Secrets Manager.

Exemple : requête GET de l'agent Secrets Manager avec le paramètre RefreshNow
Important

La valeur par défaut de refreshNow est false. Lorsqu'il est défini surtrue, il remplace le TTL spécifié dans le fichier de configuration de l'agent Secrets Manager et envoie un appel d'API à Secrets Manager.

curl

L'exemple de curl suivant montre comment forcer l'agent Secrets Manager à actualiser le secret. L'exemple repose sur la présence du SSRF dans un fichier, où il est stocké par le script d'installation.

curl -v -H \
    "X-Aws-Parameters-Secrets-Token: $(</var/run/awssmatoken)" \
    'http://localhost:2773/secretsmanager/get?secretId=<YOUR_SECRET_ID>&refreshNow=true' \
    echo
Python

L'exemple Python suivant montre comment obtenir un secret à partir de l'agent Secrets Manager. L'exemple repose sur la présence du SSRF dans un fichier, où il est stocké par le script d'installation.

import requests
import json

# Function that fetches the secret from Secrets Manager Agent for the provided secret id. 
def get_secret():
    # Construct the URL for the GET request
    url = f"http://localhost:2773/secretsmanager/get?secretId=<YOUR_SECRET_ID>&refreshNow=true"

    # Get the SSRF token from the token file
    with open('/var/run/awssmatoken') as fp:
        token = fp.read() 

    headers = {
        "X-Aws-Parameters-Secrets-Token": token.strip()
    }

    try:
        # Send the GET request with headers
        response = requests.get(url, headers=headers)

        # Check if the request was successful
        if response.status_code == 200:
            # Return the secret value
            return response.text
        else:
            # Handle error cases
            raise Exception(f"Status code {response.status_code} - {response.text}")

    except Exception as e:
        # Handle network errors
        raise Exception(f"Error: {e}")

Configuration de l'agent Secrets Manager

Pour modifier la configuration de l'agent Secrets Manager, créez un fichier de configuration TOML, puis appelez./aws-secrets-manager-agent --config config.toml.

La liste suivante indique les options que vous pouvez configurer pour l'agent Secrets Manager.

  • log_level — Niveau de détail indiqué dans les journaux de l'agent Secrets Manager : DEBUG, INFO, WARN, ERROR ou NONE. La valeur par défaut est INFO.

  • http_port — Port du serveur HTTP local, compris entre 1024 et 65535. La valeur par défaut est 2773.

  • région — La AWS région à utiliser pour les demandes. Si aucune région n'est spécifiée, l'agent Secrets Manager détermine la région à partir du SDK. Pour plus d'informations, consultez Spécifier vos informations d'identification et la région par défaut dans le guide du développeur du AWS SDK pour Rust.

  • ttl_seconds — Le TTL en secondes pour les éléments mis en cache, compris entre 0 et 3 600. La valeur par défaut est 300. 0 indique qu'il n'y a pas de mise en cache.

  • cache_size — Le nombre maximum de secrets pouvant être stockés dans le cache, compris entre 1 et 1 000. La valeur par défaut est 1000.

  • ssrf_headers — Liste des noms d'en-têtes que l'agent Secrets Manager vérifie pour le jeton SSRF. La valeur par défaut est « X-Aws-Parameters-Secrets-Token ». X-Vault-Token

  • ssrf_env_variables — Liste de noms de variables d'environnement que l'agent Secrets Manager vérifie pour le jeton SSRF. La variable d'environnement peut contenir le jeton ou une référence au fichier du jeton comme dans : AWS_TOKEN=file:///var/run/awssmatoken La valeur par défaut est «AWS_TOKEN, AWS_SESSION _TOKEN ».

  • path_prefix — Le préfixe d'URI utilisé pour déterminer si la demande est une demande basée sur un chemin. La valeur par défaut est « /v1/ ».

  • max_conn — Le nombre maximum de connexions depuis des clients HTTP autorisées par l'agent Secrets Manager, compris entre 1 et 1 000. La valeur par défaut est 800.

Journalisation

L'agent Secrets Manager enregistre les erreurs localement dans le fichierlogs/secrets_manager_agent.log. Lorsque votre application appelle l'agent Secrets Manager pour obtenir un secret, ces appels apparaissent dans le journal local. Ils n'apparaissent pas dans les CloudTrail journaux.

L'agent Secrets Manager crée un nouveau fichier journal lorsque le fichier atteint 10 Mo, et il stocke jusqu'à cinq fichiers journaux au total.

Le journal n'est pas envoyé à Secrets Manager CloudTrail, ou CloudWatch. Les demandes d'obtention de secrets de la part de l'agent Secrets Manager n'apparaissent pas dans ces journaux. Lorsque l'agent Secrets Manager appelle Secrets Manager pour obtenir un secret, cet appel est enregistré CloudTrail avec une chaîne d'agent utilisateur contenantaws-secrets-manager-agent.

Vous pouvez configurer la connexion auFichier de configuration.

Considérations sur la sécurité

Pour une architecture d'agent, le domaine de confiance correspond à l'endroit où le point de terminaison de l'agent et le jeton SSRF sont accessibles, c'est-à-dire généralement l'ensemble de l'hôte. Le domaine de confiance de l'agent Secrets Manager doit correspondre au domaine dans lequel les informations d'identification du Secrets Manager sont disponibles afin de maintenir le même niveau de sécurité. Par exemple, sur Amazon, EC2 le domaine de confiance de l'agent Secrets Manager serait le même que celui des informations d'identification lors de l'utilisation de rôles pour Amazon EC2.

Les applications soucieuses de sécurité qui n'utilisent pas déjà une solution d'agent avec les informations d'identification de Secrets Manager verrouillées sur l'application devraient envisager d'utiliser des solutions spécifiques à la langue AWS SDKs ou de mise en cache. Pour de plus amples informations, veuillez consulter Obtenez des secrets auprès de AWS Secrets Manager.