AWS Secrets Manager Agente - AWS Secrets Manager
Etapa 1: criar o binário do Agente do Secrets ManagerEtapa 2: instalar o Agente do Secrets ManagerEtapa 3: recuperar segredos com o Agente do Secrets ManagerForce a atualização de segredos com RefreshNowArquivo de configuraçãoRegistro em logConsiderações sobre segurança

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

AWS Secrets Manager Agente

O AWS Secrets Manager Agente é um serviço HTTP do lado do cliente que você pode usar para padronizar o consumo de segredos do Secrets Manager em ambientes como Amazon Elastic Container Service, AWS Lambda Amazon Elastic Kubernetes Service e Amazon Elastic Compute Cloud. O Agente do Secrets Manager pode recuperar e armazenar segredos na memória para que suas aplicações possam consumir segredos diretamente do cache. Isso significa que é possível buscar os segredos de que sua aplicação precisa no host local em vez de fazer chamadas para o Secrets Manager. O Agente do Secrets Manager só pode fazer solicitações de leitura para o Secrets Manager — ele não pode modificar segredos.

O Secrets Manager Agent usa AWS as credenciais que você fornece em seu ambiente para fazer chamadas para o Secrets Manager. O Agente do Secrets Manager oferece proteção contra falsificação de solicitações do lado do servidor (SSRF) para ajudar a melhorar a segurança dos segredos. É possível configurar o Agente do Secrets Manager definindo o número máximo de conexões, o tempo de vida (TTL), a porta HTTP do host local e o tamanho do cache.

Como o Agente do Secrets Manager usa um cache em memória, ele é redefinido quando o Agente do Secrets Manager é reiniciado. O Agente do Secrets Manager atualiza periodicamente o valor do segredo armazenado em cache. A atualização acontece quando você tenta ler um segredo do Agente do Secrets Manager após a expiração do TTL. A frequência de atualização padrão (TTL) é de 300 segundos, e é possível alterá-la usando um Arquivo de configuração que você passa para o Agente do Secrets Manager usando o argumento da linha de comando --config. O Agente do Secrets Manager não inclui a invalidação do cache. Por exemplo, se um segredo alternar 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.

Para baixar o código-fonte, veja https://github.com/aws/aws-secretsmanager-agentem GitHub.

Etapa 1: criar o binário do Agente do Secrets Manager

Para criar o binário do Agente do Secrets Manager de forma nativa, você precisa das ferramentas de desenvolvimento padrão e das ferramentas Rust. Como alternativa, é possível fazer a compilação cruzada para sistemas que oferecem suporte a ele ou usar o cruzamento do Rust para fazer a compilação cruzada.

RPM-based systems

  1. Em sistemas baseados em RPM, como AL2 023, você pode instalar as ferramentas de desenvolvimento usando o grupo Ferramentas de Desenvolvimento.

    sudo yum -y groupinstall "Development Tools"

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

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

  3. Crie o agente usando o comando cargo build:

    cargo build --release

    Você encontrará o executável em target/release/aws-secrets-manager-agent.

Debian-based systems

  1. Em sistemas baseados no Debian, como o Ubuntu, é possível instalar as ferramentas do desenvolvedor usando o pacote build-essential.

    sudo apt install build-essential

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

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

  3. Crie o agente usando o comando cargo build:

    cargo build --release

    Você encontrará o executável em target/release/aws-secrets-manager-agent.

Windows

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

Cross-compile natively

Em distribuições em que o pacote mingw-w64 está disponível, como o Ubuntu, você pode fazer a compilação cruzada de forma nativa.

# 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

Você encontrará o executável em target/x86_64-pc-windows-gnu/release/aws-secrets-manager-agent.exe.

Cross compile with Rust cross

Se as ferramentas de compilação cruzada não estiverem disponíveis nativamente no sistema, será possível usar o projeto cruzado do Rust. 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.

# 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

Etapa 2: instalar o Agente do Secrets Manager

Com base no tipo de computação, você tem várias opções para instalar o Agente do Secrets Manager.

Amazon EKS, Amazon EC2, and Amazon ECS
Para instalar o Agente do Secrets Manager

  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, você pode conceder permissões para que seu aplicativo leia o arquivo de token com o seguinte comando usermod, onde <APP_USER> está o ID do usuário sob o qual seu aplicativo é executado.

    sudo usermod -aG awssmatokenreader <APP_USER>
Docker

É 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 com Docker

  1. Crie um Dockerfile para o contêiner auxiliar do Agente do Secrets Manager. O exemplo a seguir cria um contêiner do Docker com o binário 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. Crie um Dockerfile para sua aplicação cliente.

  3. Crie um arquivo Docker Compose para executar ambos os contêineres, certificando-se de que eles usem a mesma interface de rede. Isso é necessário porque o Agente do Secrets Manager não aceita solicitações de fora da interface localhost. O exemplo a seguir mostra um arquivo Docker Compose em que a chave network_mode anexa o contêiner secrets-manager-agent ao namespace de rede do contêiner client-application, o que permite que eles compartilhem a mesma interface de rede.

    Importante

    Você deve carregar AWS as credenciais e o token SSRF para que o aplicativo possa usar o Secrets Manager Agent. Veja o seguinte:

    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. Copie o binário do secrets-manager-agent para o mesmo diretório que contém seus arquivos Dockerfile e Docker Compose.

  5. Crie e execute os contêineres com base nos Dockerfiles fornecidos usando o comando docker-compose a seguir.

    docker-compose up --build

  6. No contêiner do cliente, agora é possível usar o Agente do Secrets Manager para recuperar segredos. Para obter mais informações, consulte Etapa 3: recuperar segredos com o Agente do Secrets Manager.

AWS Lambda

Você pode empacotar o Secrets Manager Agent como uma AWS Lambda extensão. 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 nome secreto MyTest usando o script secrets-manager-agent-extension.sh de exemplo https://github.com/aws/aws-secretsmanager-agentpara instalar o Secrets Manager Agent como uma extensão Lambda.

nota

O script de exemplo usa o comando curl, que está incluído nos runtimes baseados no Amazon Linux 2023, como Python 3.12 e Node.js 20. Se você usa um ambiente de runtime baseado no Amazon Linux 2, como Python 3.11 ou Node.js 18, deve primeiro instalar o curl em sua imagem de contêiner do Lambda. Para obter instruções, consulte Como posso usar os pacotes binários nativos do Amazon Linux 2 AMI com o Lambda no AWS re:POST.

Para criar uma extensão do Lambda que empacote o Agente do Secrets Manager

  1. Crie uma função do Lambda do Python que consulte http://localhost:2773/secretsmanager/get?secretId=MyTest para obter 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.

  2. Na raiz do pacote de código do Agente do Secrets Manager, execute os comandos a seguir para testar a extensão do 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. Invoque a função do Lambda para verificar se o segredo está sendo buscado corretamente.

Etapa 3: recuperar segredos com o Agente do Secrets Manager

Para usar o agente, você chama o endpoint local do Agente do Secrets Manager e inclui 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, é possível definir versionStage ou versionId.

Para ajudar a proteger o Agente do Secrets Manager, você deve 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 Arquivo de configuração.

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

Permissões obrigatórias:

  • secretsmanager:DescribeSecret

  • secretsmanager:GetSecretValue

Para obter mais informações, consulte Referência de permissões.

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.

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

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

Force a atualização de segredos com RefreshNow

O Secrets Manager Agent usa um cache na memória para armazenar valores secretos, que são atualizados periodicamente. Por padrão, essa atualização ocorre quando você solicita um segredo após a expiração do Time to Live (TTL), normalmente a cada 300 segundos. No entanto, essa abordagem às vezes pode resultar em valores secretos obsoletos, especialmente se um segredo girar antes que a entrada do cache expire.

Para resolver essa limitação, o Secrets Manager Agent suporta um parâmetro chamado refreshNow na URL. Você pode usar esse parâmetro para forçar uma atualização imediata do valor de um segredo, ignorando o cache e garantindo que você tenha o máximo up-to-date de informações.

Comportamento padrão (semrefreshNow)

  • Usa valores em cache até que o TTL expire

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

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

Comportamento com refreshNow=true

  • Ignora completamente o cache

  • Recupera o valor secreto 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

Ao usar o refreshNow parâmetro, você pode garantir que esteja sempre trabalhando com os valores secretos mais atuais, mesmo em cenários em que a rotação frequente de segredos é necessária.

refreshNowcomportamento do parâmetro

refreshNow definido como true

Se o Secrets Manager Agent não conseguir recuperar o segredo do Secrets Manager, ele retornará um erro e não atualizará o cache.

refreshNowdefinido como false ou não especificado

O Secrets Manager Agent segue seu comportamento padrão:

  • Se o valor em cache for mais recente que o TTL, o Secrets Manager Agent retornará o valor em cache.

  • Se o valor em cache for mais antigo que o TTL, o Secrets Manager Agent fará uma chamada para o Secrets Manager.

Usando o parâmetro RefreshNow

Para usar o refreshNow parâmetro, inclua-o na URL da solicitação GET do Secrets Manager Agent.

exemplo Exemplo - Solicitação GET do Secrets Manager Agent com o parâmetro RefreshNow
Importante

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

curl

O exemplo de curl a seguir mostra como forçar o Secrets Manager Agent 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

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-secrets-manager-agent --config config.toml.

A lista a seguir mostra as opções que podem ser configuradas para o Agente do Secrets Manager.

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

  • http_port: a porta para o servidor HTTP local, no intervalo de 1024 a 65535. O padrão é 2773.

  • região — A AWS região 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 é 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 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 para o token 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”.

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

Registro em log

O Agente do Secrets Manager registra erros em log localmente no arquivo logs/secrets_manager_agent.log. Quando sua aplicação chama o Agente do Secrets Manager para obter um segredo, essas chamadas aparecem no log local. Eles não aparecem nos CloudTrail registros.

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.

O registro 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 Secrets Manager Agent faz uma chamada para o Secrets Manager para obter um segredo, essa chamada é gravada CloudTrail com uma string de agente de usuário contendoaws-secrets-manager-agent.

É possível configurar o log usando no Arquivo de configuração.

Considerações sobre seguranç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, na Amazon, EC2 o domínio de confiança do Secrets Manager Agent seria o mesmo que o domínio das credenciais ao usar funções para a Amazon EC2.

Aplicativos preocupados com a segurança que ainda não estão usando uma solução de agente com as credenciais do Secrets Manager bloqueadas no aplicativo devem considerar o uso de soluções específicas do idioma AWS SDKs ou de armazenamento em cache. Para obter mais informações, consulte Obtenha segredos de AWS Secrets Manager.