Uso do agente do AWS Secrets Manager - AWS Secrets Manager
Como o Agente do Secrets Manager funcionaNoções básicas sobre o armazenamento em cache do Agente do Secrets ManagerCriação do Agente do Secrets ManagerInstalação do Agente do Secrets ManagerRecuperação de segredos com o Agente do Secrets ManagerNoções básicas sobre o parâmetro refreshNowOpções de configuraçãoRecursos opcionaisRegistro em logConsiderações sobre segurança

Uso do agente do AWS Secrets Manager

Como o Agente do Secrets Manager funciona

O agente do AWS Secrets Manager é um serviço de HTTP do lado do cliente que ajuda você a padronizar a forma como você consome segredos do Secrets Manager em seus ambientes computacionais. É possível usá-lo com serviços a seguir:

  • AWS Lambda

  • Amazon Elastic Container Service

  • Serviço Amazon Elastic Kubernetes

  • Amazon Elastic Compute Cloud

O Agente do Secrets Manager recupera e armazena segredos em cache na memória, permitindo que suas aplicações obtenham segredos do localhost em vez de fazer chamadas diretas para o Secrets Manager. O Agente do Secrets Manager só pode ler segredos, ele não pode modificá-los.

Importante

O Agente do Secrets Manager usa as credenciais da AWS do seu ambiente para chamar o Secrets Manager. Isso inclui proteção contra falsificação de solicitações do lado do servidor (SSRF) para ajudar a melhorar a segurança dos segredos. O Agente do Secrets Manager usa a troca de chaves pós-quântica ML-KEM como a troca de chaves de maior prioridade por padrão.

Noções básicas sobre o armazenamento em cache do Agente do Secrets Manager

O Agente do Secrets Manager usa um cache em memória, ele é redefinido quando o Agente do Secrets Manager é reiniciado. Ele atualiza periodicamente os valores de segredos em cache com base no seguinte:

  • A frequência de atualização padrão (TTL) é de 300 segundos

  • É possível modificar o TTL usando um arquivo de configuração

  • A atualização ocorre quando você solicita um segredo após a expiração do TTL

nota

O Agente do Secrets Manager não inclui a invalidação do cache. Se um segredo for alternado antes que a entrada do cache expire, o Agente do Secrets Manager poderá retornar um valor de segredo obsoleto.

O Agente do Secrets Manager retorna valores de segredos no mesmo formato da resposta de GetSecretValue. Os valores de segredos não são criptografados no cache.

Criação do Agente do Secrets Manager

Antes de começar, verifique se você tem as ferramentas de desenvolvimento padrão e as ferramentas do Rust instaladas em sua plataforma.

nota

Atualmente, criar o agente com o recurso fips ativado no macOS requer a solução alternativa a seguir:

  • Crie uma variável de ambiente chamada SDKROOT que é definida como o resultado da execução de xcrun --show-sdk-path

RPM-based systems
Para criar em sistemas baseados em RPM

  1. Use o script install fornecido no repositório.

    O script gera um token SSRF aleatório no startup e o armazena no arquivo /var/run/awssmatoken. O token pode ser lido pelo grupo awssmatokenreader criado pelo script de instalação.

  2. Para permitir que sua aplicação leia o arquivo de token, você precisa adicionar ao grupo awssmatokenreader a conta de usuário na qual sua aplicação é executada. Por exemplo, é possível conceder permissões para que sua aplicação leia o arquivo de token com o comando usermod a seguir, onde <APP_USER> é o ID do usuário sob o qual sua aplicação é executada.

    sudo usermod -aG awssmatokenreader <APP_USER>
    Instalação das ferramentas de desenvolvimento

    Em sistemas baseados em RPM, como o AL2023, instale o grupo Ferramentas de desenvolvimento.

    sudo yum -y groupinstall "Development Tools"
  3. Instalação do Rust

    Siga as instruções em Instalação do Rust na documentação do Rust.

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions
. "$HOME/.cargo/env"
  4. Criação do agente

    Crie o Agente do Secrets Manager usando o comando cargo build:

    cargo build --release

    Você encontrará o executável em target/release/aws_secretsmanager_agent.

Debian-based systems
Para criar em sistemas baseados em Debian
  1. Instalação das ferramentas de desenvolvimento

    Em sistemas baseados no Debian, como o Ubuntu, instale o pacote build-essential.

    sudo apt install build-essential
  2. Instalação do Rust

    Siga as instruções em Instalação do Rust na documentação do Rust.

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions
. "$HOME/.cargo/env"
  3. Criação do agente

    Crie o Agente do Secrets Manager usando o comando cargo build:

    cargo build --release

    Você encontrará o executável em target/release/aws_secretsmanager_agent.

Windows
Para criar no Windows
  1. Configuração do ambiente de desenvolvimento

    Siga as instruções em Configuração do seu ambiente de desenvolvimento no Windows para Rust na documentação do Microsoft Windows.

  2. Criação do agente

    Crie o Agente do Secrets Manager usando o comando cargo build:

    cargo build --release

    Você encontrará o executável em target/release/aws_secretsmanager_agent.exe.

Cross-compile natively
Para compilar de forma cruzada
  1. Instalação das ferramentas de compilação cruzada

    Em distribuições em que o pacote mingw-w64 está disponível, como o Ubuntu, instale o conjunto de ferramentas de compilação cruzada.

    # Install the cross compile tool chain
sudo add-apt-repository universe
sudo apt install -y mingw-w64
  2. Adição de destinos de criação do Rust

    Instale o destino de compilação do Windows GNU:

    rustup target add x86_64-pc-windows-gnu
  3. Criação no Windows

    Faça a compilação cruzada do agente para Windows:

    cargo build --release --target x86_64-pc-windows-gnu

    Você encontrará o executável em target/x86_64-pc-windows-gnu/release/aws_secretsmanager_agent.exe.

Cross compile with Rust cross
Para fazer a compilação cruzada usando o Rust cross

Se as ferramentas de compilação cruzada não estiverem disponíveis nativamente no sistema, será possível usar o projeto Rust cross. Para obter mais informações, consulte https://github.com/cross-rs/cross.

Importante

Recomendamos 32 GB de espaço em disco para o ambiente de compilação.

  1. Configurar o Docker

    Instalação e configuração do Docker

    # Install and start docker
sudo yum -y install docker
sudo systemctl start docker
sudo systemctl enable docker # Make docker start after reboot
  2. Configuração das permissões do Docker

    Adicione seuusuário ao grupo do docker:

    # Give ourselves permission to run the docker images without sudo
sudo usermod -aG docker $USER
newgrp docker
  3. Criação no Windows

    Instale o cross e crie o executável:

    # Install cross and cross compile the executable
cargo install cross
cross build --release --target x86_64-pc-windows-gnu

Instalação do Agente do Secrets Manager

Escolha seu ambiente de computação entre as opções de instalação a seguir.

Amazon EC2
Para instalar o Agente do Secrets Manager no Amazon EC2
  1. Navegação até o diretório de configurações

    Mude para o diretório de configurações:

    cd aws_secretsmanager_agent/configuration
  2. Execução do script de instalação

    Execute o script install fornecido no repositório.

    O script gera um token SSRF aleatório no startup e o armazena no arquivo /var/run/awssmatoken. O token pode ser lido pelo grupo awssmatokenreader criado pelo script de instalação.

  3. Configuração de permissões de aplicações

    Adicione a conta de usuário na qual sua aplicação é executada ao grupo awssmatokenreader:

    sudo usermod -aG awssmatokenreader APP_USER

    Substitua APP_USER pelo ID de usuário sob o qual sua aplicação é executada.

Container Sidecar

É possível executar o Agente do Secrets Manager como um contêiner auxiliar junto com sua aplicação usando o Docker. Então, sua aplicação pode recuperar segredos do servidor HTTP local fornecido pelo Agente do Secrets Manager. Para obter informações sobre o Docker, consulte a documentação do Docker.

Para criar um contêiner auxiliar para o Agente do Secrets Manager
  1. Criação do Dockerfile do agente

    Crie um Dockerfile para o contêiner auxiliar do Agente do 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. Criação do Dockerfile da aplicação

    Crie um Dockerfile para sua aplicação cliente.

  3. Criação do arquivo Docker Compose

    Crie um arquivo Docker Compose para executar ambos os contêineres com uma interface de rede compartilhada:

    Importante

    É necessário carregar as credenciais da AWS e o token SSRF para que a aplicação possa usar o Agente do Secrets Manager. Para o Amazon EKS e o Amazon ECS, consulte:

    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. Cópia de binário do agente

    Copie o binário do secrets-manager-agent para o mesmo diretório que contém seus arquivos Dockerfile e Docker Compose.

  5. Criação e execução dos contêineres

    Crie e execute os contêineres usando o Docker Compose:

    docker-compose up --build
  6. Próximas etapas

    Agora é possível usar o Agente do Secrets Manager para recuperar segredos do seu contêiner cliente. Para obter mais informações, consulte Recuperação de segredos com o Agente do Secrets Manager.

Lambda

É possível empacotar o Agente do Secrets Manager como uma extensão do LAmbda. Em seguida, é possível adicioná-lo à sua função do Lambda como uma camada e chamar o Agente do Secrets Manager a partir da sua função da Lambda para obter segredos.

As instruções a seguir mostram como obter um segredo chamado MyTest usando o script de exemplo secrets-manager-agent-extension.sh em https://github.com/aws/aws-secretsmanager-agent para instalar o Agente do Secrets Manager como uma extensão do Lambda.

Para criar uma extensão do Lambda para o Agente do Secrets Manager
  1. Empacotamento da camada do agente

    Na raiz do pacote de código do Agente do Secrets Manager, execute os comandos a seguir:

    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` example 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')
  2. Configurar o token de SSRF

    A configuração padrão do agente definirá automaticamente o token de SSRF com o valor definido nas variáveis de ambiente predefinidas AWS_SESSION_TOKEN ou AWS_CONTAINER_AUTHORIZATION_TOKEN (a última variável para funções do Lambda com o SnapStart ativado). Como alternativa, é possível definir a variável de ambiente AWS_TOKEN com um valor arbitrário para sua função do Lambda, pois essa variável tem precedência sobre as outras duas. Se você optar por usar a variável de ambiente AWS_TOKEN, deverá definir essa variável de ambiente com uma chamada a lambda:UpdateFunctionConfiguration.

  3. Vinculação da camada à função

    Vincule a versão da camada à sua função do Lambda.

    # Attach the layer version to the Lambda function
aws lambda update-function-configuration \
    --function-name $LAMBDA_ARN \
    --layers "$LAYER_VERSION_ARN"
  4. Atualizar um código de função

    Atualize sua função do Lambda para fazer uma consulta a http://localhost:2773/secretsmanager/get?secretId=MyTest com o valor de cabeçalho X-Aws-codes-Secrets-Token definido como o valor do token de SSRF proveniente de uma das variáveis de ambiente mencionadas acima para recuperar o segredo. Certifique-se de implementar a lógica de repetição no código da aplicação para acomodar atrasos na inicialização e no registro da extensão do Lambda.

  5. Testar a função

    Invoque a função do Lambda para verificar se o segredo está sendo buscado corretamente.

Recuperação de segredos com o Agente do Secrets Manager

Para recuperar um segredo, chame o endpoint local do Agente do Secrets Manager e incluia o nome ou ARN do segredo como um parâmetro de consulta. Por padrão, o Agente do Secrets Manager recupera a versão AWSCURRENT do segredo. Para recuperar uma versão diferente, use o parâmetro versionStage ou versionId.

Importante

Para ajudar a proteger o Agente do Secrets Manager, é necessário incluir um cabeçalho de token SSRF como parte de cada solicitação: X-Aws-Parameters-Secrets-Token. O Agente do Secrets Manager nega solicitações que não tenham esse cabeçalho ou que tenham um token SSRF inválido. É possível personalizar o nome do cabeçalho SSRF em Configurar o Agente do Secrets Manager.

Permissões obrigatórias

O Agente do Secrets Manager usa o SDK da AWS para Rust, que usa a cadeia de fornecedores de credenciais da AWS. A identidade dessas credenciais do IAM determina as permissões que o Agente do Secrets Manager tem para recuperar segredos.

  • secretsmanager:DescribeSecret

  • secretsmanager:GetSecretValue

Para obter mais informações sobre permissões, consulte Referência de permissões para o AWS Secrets Manager.

Importante

Depois que o valor do segredo é inserido no Agente do Secrets Manager, qualquer usuário com acesso ao ambiente computacional e ao token SSRF pode acessar o segredo a partir do cache do Agente do Secrets Manager. Para obter mais informações, consulte Considerações sobre segurança.

Exemplo de solicitações

curl
exemplo Exemplo: obtenção de um segredo usando curl

O exemplo de curl a seguir mostra como obter um segredo do Agente do Secrets Manager. O exemplo depende da presença do SSRF em um arquivo, que é onde ele é armazenado pelo script de instalação.

curl -v -H \\
    "X-Aws-Parameters-Secrets-Token: $(/var/run/awssmatoken)" \\
    'http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID' \\
    echo
Python
exemplo Exemplo: obtenção de um segredo usando Python

O exemplo de Python a seguir mostra como obter um segredo do Agente do Secrets Manager. O exemplo depende da presença do SSRF em um arquivo, que é onde ele é armazenado pelo script de instalação.

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}")

Noções básicas sobre o parâmetro refreshNow

O Agente do Secrets Manager usa um cache em memória para armazenar valores de segredos, que são atualizados periodicamente. Por padrão, essa atualização ocorre quando você solicita um segredo após a expiração da vida útil (TTL), normalmente a cada 300 segundos. No entanto, essa abordagem às vezes pode resultar em valores de segredo obsoletos, especialmente se um segredo for alternado antes que a entrada do cache expire.

Para resolver essa limitação, o Agente do Secrets Manager oferece suporte a um parâmetro chamado refreshNow na URL. É possível usar esse parâmetro para forçar uma atualização imediata do valor de um segredo, ignorando o cache e garantindo que você tenha as informações mais atualizadas.

Comportamento padrão (sem refreshNow)

  • Usa valores em cache até que o TTL expire

  • Atualiza segredos somente após o TTL (padrão de 300 segundos)

  • Pode retornar valores obsoletos se os segredos forem alternados antes que o cache expire

Comportamento com refreshNow=true

  • Ignora completamente o cache

  • Recupera o valor do segredo mais recente diretamente do Secrets Manager

  • Atualiza o cache com o novo valor e redefine o TTL

  • Garante que você sempre obtenha o valor secreto mais atual

Atualização forçada de um valor de segredo

Importante

O valor padrão de refreshNow é false. Quando definido como true, substitui o TTL especificado no arquivo de configuração do Agente do Secrets Manager e faz uma chamada de API para o Secrets Manager.

curl
exemplo Exemplo: atualização forçada de um segredo usando curl

O exemplo de curl a seguir mostra como forçar o Agente do Secrets Manager a atualizar o segredo. O exemplo depende da presença do SSRF em um arquivo, que é onde ele é armazenado pelo script de instalação.

curl -v -H \\
"X-Aws-Parameters-Secrets-Token: $(/var/run/awssmatoken)" \\
'http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID&refreshNow=true' \\
echo
Python
exemplo Exemplo: atualização forçada de um segredo usando Python

O exemplo de Python a seguir mostra como obter um segredo do Agente do Secrets Manager. O exemplo depende da presença do SSRF em um arquivo, que é onde ele é armazenado pelo script de instalação.

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}")

Configurar o Agente do Secrets Manager

Para alterar a configuração do Agente do Secrets Manager, crie um arquivo de configuração TOML e, em seguida, chame ./aws_secretsmanager_agent --config config.toml.

Opções de configuração
log_level

O nível de detalhes relatado nos logs do Agente do Secrets Manager: DEBUG, INFO, WARN, ERROR ou NONE. O padrão é INFO.

log_to_file

Se deve enviar o log para um arquivo ou para stdout/stderr: true ou false. O padrão é “”. true.

http_port

A porta do servidor de HTTP local, no intervalo de 1024 a 65535. O padrão é 2773.

region

A região da AWS a ser usada para solicitações. Se nenhuma região for especificada, o Agente do Secrets Manager determinará a região a partir do SDK. Para obter mais informações, consulte Especificação das suas credenciais e região padrão no Guia do desenvolvedor do SDK da AWS para Rust.

ttl_seconds

O TTL, em segundos, para os itens em cache, no intervalo de 0 a 3600. O padrão é de 300. 0 indica que não há armazenamento em cache.

cache_size

O número máximo de segredos que podem ser armazenados no cache, no intervalo de 1 a 1000. O padrão é 1000.

ssrf_headers

Uma lista de nomes de cabeçalhos que o Agente do Secrets Manager verifica para o token de SSRF. O padrão é "X-Aws-Parameters-Secrets-Token, X-Vault-Token".

ssrf_env_variables

Uma lista de nomes de variáveis de ambiente que o Agente do Secrets Manager verifica em ordem sequencial para o token de SSRF. A variável de ambiente pode conter o token ou uma referência ao arquivo de token, como em: AWS_TOKEN=file:///var/run/awssmatoken. O padrão é "AWS_TOKEN, AWS_SESSION_TOKEN, AWS_CONTAINER_AUTHORIZATION_TOKEN".

path_prefix

O prefixo do URI usado para determinar se a solicitação é baseada em caminho. O padrão é "/v1/".

max_conn

O número máximo de conexões de clientes HTTP que o Agente do Secrets Manager permite, na faixa de 1 a 1000. O padrão é 800.

Recursos opcionais

O Agente do Secrets Manager pode ser criado com recursos opcionais passando o sinalizador --features para cargo build. Os recursos disponíveis são:

Recursos de compilação
prefer-post-quantum

Torna X25519MLKEM768 o algoritmo de troca de chaves de maior prioridade. Caso contrário, ele estará disponível, mas não será de maior prioridade. X25519MLKEM768 é um algoritmo de troca de chaves híbrido e pós-quântico seguro.

fips

Restringe os conjuntos de cifras usados pelo agente somente a cifras aprovadas pelo FIPS.

Registro em log

Log local

O Agente do Secrets Manager registra erros em log localmente no arquivo logs/secrets_manager_agent.log ou em stdout/stderr, dependendo da variável de configuração log_to_file. Quando sua aplicação chama o Agente do Secrets Manager para obter um segredo, essas chamadas aparecem no log local. Elas não são exibidas nos logs do CloudTrail.

Alternância de logs

O Agente do Secrets Manager e armazena até cinco arquivos de log no total e cria um novo arquivo de log quando o arquivo atinge 10 MB.

Logs de serviço da AWS

O log não vai para o Secrets Manager, CloudTrail ou CloudWatch. As solicitações para obter segredos do Agente do Secrets Manager não aparecem nesses logs. Quando o Agente do Secrets Manager faz uma chamada para o Secrets Manager para obter um segredo, essa chamada é gravada no CloudTrail com uma string de agente do usuário contendo aws-secrets-manager-agent.

É possível configurar as opções de log em Configurar o Agente do Secrets Manager.

Considerações sobre segurança

Domínio de confiança

Para uma arquitetura de agente, o domínio de confiança é onde o endpoint do agente e o token SSRF estão acessíveis, o que geralmente é o host inteiro. O domínio de confiança do Agente do Secrets Manager deve corresponder ao domínio em que as credenciais do Secrets Manager estão disponíveis para manter a mesma postura de segurança. Por exemplo, no Amazon EC2, o domínio de confiança do Agente do Secrets Manager seria o mesmo que o domínio das credenciais ao usar funções para o Amazon EC2.

Importante

Aplicações preocupadas com a segurança que ainda não estejam usando uma solução de agente com as credenciais do Secrets Manager bloqueadas na aplicação devem considerar o uso de SDKs da AWS específicos do idioma ou soluções de cache. Para obter mais informações, consulte Obtenção de segredos.