AWS Secrets Manager Agent

The AWS Secrets Manager Agent is a client-side HTTP service that you can use to standardize consumption of secrets from Secrets Manager across environments such as AWS Lambda, Amazon Elastic Container Service, Amazon Elastic Kubernetes Service, and Amazon Elastic Compute Cloud. The Secrets Manager Agent can retrieve and cache secrets in memory so that your applications can consume secrets directly from the cache. That means you can fetch the secrets your application needs from the localhost instead of making calls to Secrets Manager. The Secrets Manager Agent can only make read requests to Secrets Manager - it can’t modify secrets.

The Secrets Manager Agent uses the AWS credentials you provide in your environment to make calls to Secrets Manager. The Secrets Manager Agent offers protection against Server Side Request Forgery (SSRF) to help improve secret security. The Agent also uses the post-quantum ML-KEM key exchange as the highest-priority key exchange by default. You can configure the Secrets Manager Agent by setting the maximum number of connections, the time to live (TTL), the localhost HTTP port, and the cache size.

Because the Secrets Manager Agent uses an in-memory cache, it resets when the Secrets Manager Agent restarts. The Secrets Manager Agent periodically refreshes the cached secret value. The refresh happens when you try to read a secret from the Secrets Manager Agent after the TTL has expired. The default refresh frequency (TTL) is 300 seconds, and you can change it by using a Configuration file which you pass to the Secrets Manager Agent using the --config command line argument. The Secrets Manager Agent does not include cache invalidation. For example, if a secret rotates before the cache entry expires, the Secrets Manager Agent might return a stale secret value.

The Secrets Manager Agent returns secret values in the same format as the response of GetSecretValue. Secret values are not encrypted in the cache.

To download the source code, see https://github.com/aws/aws-secretsmanager-agent on GitHub.

Topics

AWS Secrets Manager Agent

Step 1: Build the Secrets Manager Agent binary

To build the Secrets Manager Agent binary natively, you need the standard development tools and the Rust tools. Alternatively, you can cross-compile for systems that support it, or you can use Rust cross to cross-compile.

NOTE: To ensure a stable experience, use a specific git tag when building from source code. You can find a list of version tags here. Tags are in the pattern /v\d+\.\d+\.\d+/ and follow SemVer 2.0.0.

Example: git clone --branch <git tag> https://github.com/aws/aws-secretsmanager-agent.git

NOTE: Building the agent with the fips feature enabled on macOS currently requires the following workaround:

Create an environment variable called SDKROOT which is set to the result of running xcrun --show-sdk-path

[ RPM-based systems ]

On RPM-based systems such as AL2023, you can install the development tools by using the Development Tools group.
```
sudo yum -y groupinstall "Development Tools"
```

Follow the instructions at Install Rust in the Rust documentation.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions
. "$HOME/.cargo/env"

Build the agent using the cargo build command:
```
cargo build --release
```
You will find the executable under target/release/aws_secretsmanager_agent.

[ Debian-based systems ]

On Debian-based systems such as Ubuntu, you can install the developer tools using the build-essential package.
```
sudo apt install build-essential
```

Follow the instructions at Install Rust in the Rust documentation.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions
. "$HOME/.cargo/env"

Build the agent using the cargo build command:
```
cargo build --release
```
You will find the executable under target/release/aws_secretsmanager_agent.

[ Windows ]

To build on Windows, follow the instructions at Set up your dev environment on Windows for Rust in the Microsoft Windows documentation.

Build the agent using the cargo build command:
```
cargo build --release
```
You will find the executable under target/release/aws_secretsmanager_agent.exe.

[ Cross-compile natively ]

On distributions where the mingw-w64 package is available such as Ubuntu, you can cross compile natively.

# 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

You will find the executable at target/x86_64-pc-windows-gnu/release/aws_secretsmanager_agent.exe.

[ Cross compile with Rust cross ]

If the cross compile tools are not available natively on the system, you can use the Rust cross project. For more information, see https://github.com/cross-rs/cross.

Important
We recommend 32GB disk space for the build environment.

# 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

Step 2: Install the Secrets Manager Agent

Based on the type of compute, you have several options for installing the Secrets Manager Agent.

[ Amazon EC2 ]

To install the Secrets Manager Agent

cd aws_secretsmanager_agent/configuration
Run the install script provided in the repository.

The script generates a random SSRF token on startup and stores it in the file /var/run/awssmatoken. The token is readable by the awssmatokenreader group that the install script creates.
To allow your application to read the token file, you need to add the user account that your application runs under to the awssmatokenreader group. For example, you can grant permissions for your application to read the token file with the following usermod command, where <APP_USER> is the user ID under which your application runs.
```
sudo usermod -aG awssmatokenreader <APP_USER>
```

[ Running as a Container Sidecar ]

You can run the Secrets Manager Agent as a sidecar container alongside your application by using Docker. Then your application can retrieve secrets from the local HTTP server the Secrets Manager Agent provides. For information about Docker, see the Docker documentation.

To create a sidecar container for the Secrets Manager Agent with Docker

Create a Dockerfile for the Secrets Manager Agent sidecar container. The following example creates a Docker container with the Secrets Manager Agent binary.

# 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"]

Create a Dockerfile for your client application.
Create a Docker Compose file to run both containers, being sure that they use the same network interface. This is necessary because the Secrets Manager Agent does not accept requests from outside the localhost interface. The following example shows a Docker Compose file where the network_mode key attaches the secrets-manager-agent container to the network namespace of the client-application container, which allows them to share the same network interface.

Important

You must load AWS credentials and the SSRF token for the application to be able to use the Secrets Manager Agent. For EKS and ECS, see the following:
- Manage access in the Amazon Elastic Kubernetes Service User Guide
- Amazon ECS task IAM role in the Amazon Elastic Container Service Developer Guide

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

Copy the secrets-manager-agent binary to the same directory that contains your Dockerfiles and Docker Compose file.
Build and run the containers based on the provided Dockerfiles by using the following https://docs.docker.com/reference/cli/docker/compose/ command.
```
docker-compose up --build
```
In your client container, you can now use the Secrets Manager Agent to retrieve secrets. For more information, see Step 3: Retrieve secrets with the Secrets Manager Agent.

[ AWS Lambda ]

You can package the Secrets Manager Agent as an AWS Lambda extension. Then you can add it to your Lambda function as a layer and call the Secrets Manager Agent from your Lambda function to get secrets.

The following instructions show how to get a secret named MyTest by using the example script secrets-manager-agent-extension.sh in https://github.com/aws/aws-secretsmanager-agent to install the Secrets Manager Agent as a Lambda extension.

To create a Lambda extension that packages the Secrets Manager Agent

Package the agent as a layer. From the root of the Secrets Manager Agent code package, run the following example commands:

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')

The default configuration of the agent will automatically set the SSRF token to the value set in the pre-set AWS_SESSION_TOKEN or AWS_CONTAINER_AUTHORIZATION_TOKEN environment variables (the latter variable for Lambda functions with SnapStart enabled). Alternatively, you can define the AWS_TOKEN environment variable with an arbitrary value for your Lambda function instead as this variable takes precedence over the other two. If you choose to use the AWS_TOKEN environment variable, you must set that environment variable with a lambda:UpdateFunctionConfiguration call.

Attach the layer version to your Lambda function:

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

Update your Lambda function to query http://localhost:2773/secretsmanager/get?secretId=MyTest with the X-Aws-Parameters-Secrets-Token header value set to the value of the SSRF token sourced from one the environment variables mentioned above to retrieve the secret. Be sure to implement retry logic in your application code to accommodate delays in initialization and registration of the Lambda extension.

Invoke the Lambda function to verify that the secret is being correctly fetched.

Step 3: Retrieve secrets with the Secrets Manager Agent

To use the agent, you call the local Secrets Manager Agent endpoint and include the name or ARN of the secret as a query parameter. By default, the Secrets Manager Agent retrieves the AWSCURRENT version of the secret. To retrieve a different version, you can set versionStage or versionId. To retrieve a secret using a different IAM role, you can set roleArn. For more information, see Role chaining (cross-account access).

To help protect the Secrets Manager Agent, you must include a SSRF token header as part of each request: X-Aws-Parameters-Secrets-Token. The Secrets Manager Agent denies requests that don’t have this header or that have an invalid SSRF token. You can customize the SSRF header name in the Configuration file.

The Secrets Manager Agent uses the AWS SDK for Rust, which uses the https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html. The identity of these IAM credentials determines the permissions the Secrets Manager Agent has to retrieve secrets.

**Required permissions: **

secretsmanager:DescribeSecret
secretsmanager:GetSecretValue

For more information, see Permissions reference.

Important
After the secret value is pulled into the Secrets Manager Agent, any user with access to the compute environment and SSRF token can access the secret from the Secrets Manager Agent cache. For more information, see Security considerations.

[ curl ]

The following curl example shows how to get a secret from the Secrets Manager Agent. The example relies on the SSRF being present in a file, which is where it is stored by the install script.

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

[ Python ]

The following Python example shows how to get a secret from the Secrets Manager Agent. The example relies on the SSRF being present in a file, which is where it is stored by the install script.

import requests

# 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-refresh secrets with RefreshNow

Learn how to use the refreshNow parameter to force the Secrets Manager Agent (SMA) to refresh secret values.

Secrets Manager Agent uses an in-memory cache to store secret values, which it refreshes periodically. By default, this refresh occurs when you request a secret after the Time to Live (TTL) has expired, typically every 300 seconds. However, this approach can sometimes result in stale secret values, especially if a secret rotates before the cache entry expires.

To address this limitation, Secrets Manager Agent supports a parameter called refreshNow in the URL. You can use this parameter to force an immediate refresh of a secret’s value, bypassing the cache and ensuring you have the most up-to-date information.

Default behavior (without refreshNow):

Uses cached values until TTL expires
Refreshes secrets only after TTL (default 300 seconds)
May return stale values if secrets rotate before the cache expires

Behavior with refreshNow=true:

Bypasses the cache entirely
Retrieves the latest secret value directly from Secrets Manager
Updates the cache with the fresh value and resets the TTL
Ensures you always get the most current secret value

By using the refreshNow parameter, you can ensure that you’re always working with the most current secret values, even in scenarios where frequent secret rotation is necessary.

`refreshNow` parameter behavior

refreshNow set to true:

If Secrets Manager Agent can’t retrieve the secret from Secrets Manager, it returns an error and does not update the cache.

refreshNow set to false or not specified:

Secrets Manager Agent follows its default behavior:
- If the cached value is fresher than the TTL, Secrets Manager Agent returns the cached value.
- If the cached value is older than the TTL, Secrets Manager Agent makes a call to Secrets Manager.

Using the refreshNow parameter

To use the refreshNow parameter, include it in the URL for the Secrets Manager Agent GET request.

Example - Secrets Manager Agent GET request with refreshNow parameter

Important: The default value of refreshNow is false. When set to true, it overrides the TTL specified in the Secrets Manager Agent configuration file and makes an API call to Secrets Manager.

[ curl ]

The following curl example shows how force Secrets Manager Agent to refresh the secret. The example relies on the SSRF being present in a file, which is where it is stored by the install script.

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

[ Python ]

The following Python example shows how to get a secret from the Secrets Manager Agent. The example relies on the SSRF being present in a file, which is where it is stored by the install script.

import requests

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

Role chaining (cross-account access)

The Secrets Manager Agent supports retrieving secrets using IAM role assumption (role chaining). This allows you to access secrets in other AWS accounts or with different IAM permissions without running separate agent instances.

To retrieve a secret using a different IAM role, include the roleArn query parameter in your request. The Secrets Manager Agent uses STS AssumeRole to obtain temporary credentials for the specified role and then retrieves the secret with those credentials.

The Secrets Manager Agent creates and caches a separate caching client for each unique role ARN. Role clients are created lazily on first request and reused for subsequent requests with the same role ARN. Each role client maintains its own independent cache, so the same secret fetched with different roles will have separate cache entries.

**Required permissions: **

sts:AssumeRole on the target role ARN
The target role must have secretsmanager:GetSecretValue and secretsmanager:DescribeSecret permissions

**Error responses: **

400 – If the roleArn format is invalid or the maximum number of assumed roles has been reached.
403 – If the STS AssumeRole call fails (for example, the trust policy does not allow the agent’s identity to assume the role).

You can configure the maximum number of simultaneous assumed roles with the max_roles option in the Configuration file. The default is 20.

Note: Assumed roles are not evicted from the agent’s role cache. Once the maximum number of roles has been reached, requests with new role ARNs will be rejected with a 400 error until the agent is restarted.

[ curl ]

The following curl example shows how to retrieve a secret using a different IAM role.

curl -v -H \
    "X-Aws-Parameters-Secrets-Token: $(</var/run/awssmatoken)" \
    'http://localhost:2773/secretsmanager/get?secretId=<YOUR_SECRET_ID>&roleArn=arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>'; \
    echo

[ Python ]

The following Python example shows how to retrieve a secret using a different IAM role.

import requests

def get_secret_cross_account():
    role_arn = "arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>"
    url = f"http://localhost:2773/secretsmanager/get?secretId=<YOUR_SECRET_ID>&roleArn={role_arn}"

    with open('/var/run/awssmatoken') as fp:
        token = fp.read()

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

    try:
        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.text
        else:
            raise Exception(f"Status code {response.status_code} - {response.text}")

    except Exception as e:
        raise Exception(f"Error: {e}")

Pre-fetching

The Secrets Manager Agent supports pre-fetching secrets into the cache at startup. This allows your application to read secrets from the cache immediately without waiting for the first request to trigger a cache miss and network call.

To enable pre-fetching, add a [prefetch] section to your Configuration file. You can specify secrets to pre-fetch in two ways:

Explicit secrets – List specific secret IDs or ARNs using [[prefetch.secrets]] entries.
Tag-based discovery – Discover secrets by tag key using [[prefetch.filter_tags]] entries. The agent calls BatchGetSecretValue with tag key filters to find and cache all secrets that have the specified tag key, regardless of the tag’s value.

You can use both methods together. Each entry optionally accepts a role_arn field for cross-account pre-fetching via role chaining.

**Required permissions: **

secretsmanager:BatchGetSecretValue – Required for all pre-fetching operations.
secretsmanager:ListSecrets – Required when using tag-based discovery (filter_tags).

**Pre-fetch configuration options: **

cache_buffer_ratio – The maximum fraction of the cache to fill per caching client during pre-fetch, in the range 0.1 to 1.0. The default is 0.8.
max_jitter_seconds – The maximum random delay in seconds before starting the pre-fetch task, in the range 0 to 10. The default is 0 (no jitter). Use this to prevent fleet-wide synchronized API calls.

Example - Pre-fetch with explicit secrets

[[prefetch.secrets]]
secret_id = "arn:aws:secretsmanager:us-west-2:123456789012MySecret-AbCdEf"

[[prefetch.secrets]]
secret_id = "cross-account-secret"
role_arn = "arn:aws:iam::987654321098:role/SecretAccessRole"

Example - Pre-fetch with explicit secrets (inline syntax)

[prefetch]
max_jitter_seconds = 5
cache_buffer_ratio = 0.9
secrets = [
  { secret_id = "arn:aws:secretsmanager:us-west-2:123456789012MySecret-AbCdEf" },
  { secret_id = "cross-account-secret", role_arn = "arn:aws:iam::987654321098:role/SecretAccessRole" },
]
filter_tags = [
  { key = "Environment" },
  { key = "Team", role_arn = "arn:aws:iam::987654321098:role/SecretAccessRole" },
]

Example - Pre-fetch with tag-based discovery

[[prefetch.filter_tags]]
key = "Environment"

[[prefetch.filter_tags]]
key = "Team"
role_arn = "arn:aws:iam::987654321098:role/SecretAccessRole"

Example - Full configuration with pre-fetching

log_level = "info"
http_port = 2773
ttl_seconds = 300
region = "us-east-1"
max_roles = 5

[prefetch]
cache_buffer_ratio = 0.6
max_jitter_seconds = 5

[[prefetch.secrets]]
secret_id = "arn:aws:secretsmanager:us-west-2:123456789012MySecret-AbCdEf"

[[prefetch.secrets]]
secret_id = "arn:aws:secretsmanager:us-east-1:987654321098CrossAccount-AbCdEf"
role_arn = "arn:aws:iam::987654321098:role/SecretAccessRole"

[[prefetch.filter_tags]]
key = "Environment"

[[prefetch.filter_tags]]
key = "Team"
role_arn = "arn:aws:iam::987654321098:role/TagRole"

Configure the Secrets Manager Agent

To change the configuration of the Secrets Manager Agent, create a TOML config file, and then call ./aws_secretsmanager_agent --config config.toml.

The following list shows the options you can configure for the Secrets Manager Agent.

log_level – The level of detail reported in logs for the Secrets Manager Agent: DEBUG, INFO, WARN, ERROR, or NONE. The default is INFO.
log_to_file - Whether to log to a file or stdout/stderr: true or false. The default is true.
http_port – The port for the local HTTP server, in the range 1024 to 65535. The default is 2773.
region – The AWS Region to use for requests. If no Region is specified, the Secrets Manager Agent determines the Region from the SDK. For more information, see Specify your credentials and default Region in the AWS SDK for Rust Developer Guide.
ttl_seconds – The TTL in seconds for the cached items, in the range 0 to 3600. The default is 300. 0 indicates that there is no caching.
cache_size – The maximum number of secrets that can be stored in the cache, in the range 1 to 1000. The default is 1000.
ssrf_headers – A list of header names the Secrets Manager Agent checks for the SSRF token. The default is “X-Aws-Parameters-Secrets-Token, X-Vault-Token”.
ssrf_env_variables – A list of environment variable names the Secrets Manager Agent checks in sequential order for the SSRF token. The environment variable can contain the token or a reference to the token file as in: AWS_TOKEN=file:///var/run/awssmatoken. The default is “AWS_TOKEN, AWS_SESSION_TOKEN, AWS_CONTAINER_AUTHORIZATION_TOKEN".
path_prefix – The URI prefix used to determine if the request is a path based request. The default is “/v1/“.
max_conn – The maximum number of connections from HTTP clients that the Secrets Manager Agent allows, in the range 1 to 1000. The default is 800.
max_roles – The maximum number of IAM roles the Secrets Manager Agent can assume simultaneously for cross-account access, in the range 1 to 20. The default is 20. For more information, see Role chaining (cross-account access).

Optional features

The Secrets Manager Agent can be built with optional features by passing the --features flag to cargo build. The available features are:

fips: restricts the cipher suites used by the agent to only FIPS-approved ciphers

Logging

The Secrets Manager Agent logs errors locally to the file logs/secrets_manager_agent.log or to stdout/stderr depending on the log_to_file config variable. When your application calls the Secrets Manager Agent to get a secret, those calls appear in the local log. They do not appear in the CloudTrail logs.

The Secrets Manager Agent creates a new log file when the file reaches 10 MB, and it stores up to five log files total.

The log does not go to Secrets Manager, CloudTrail, or CloudWatch. Requests to get secrets from the Secrets Manager Agent do not appear in those logs. When the Secrets Manager Agent makes a call to Secrets Manager to get a secret, that call is recorded in CloudTrail with a user agent string containing aws-secrets-manager-agent.

You can configure logging in the Configuration file.

Security considerations

For an agent architecture, the domain of trust is where the agent endpoint and SSRF token are accessible, which is usually the entire host. The domain of trust for the Secrets Manager Agent should match the domain where the Secrets Manager credentials are available in order to maintain the same security posture. For example, on Amazon EC2 the domain of trust for the Secrets Manager Agent would be the same as the domain of the credentials when using roles for Amazon EC2.

Security conscious applications that are not already using an agent solution with the Secrets Manager credentials locked down to the application should consider using the language-specific AWS SDKs or caching solutions. For more information, see Get secrets.

Running Integration Tests Locally

The AWS Secrets Manager Agent includes a comprehensive integration test suite that validates functionality against real AWS Secrets Manager. These tests cover caching behavior, security features, configuration options, version management, and error handling scenarios.

Prerequisites

AWS credentials with permissions to create, read, update, and delete secrets in AWS Secrets Manager
Rust toolchain installed
Access to an AWS account for testing

Required AWS Permissions

Your AWS credentials must have the following permissions:

secretsmanager:CreateSecret
secretsmanager:GetSecretValue
secretsmanager:DescribeSecret
secretsmanager:UpdateSecret
secretsmanager:UpdateSecretVersionStage
secretsmanager:PutSecretValue
secretsmanager:DeleteSecret
secretsmanager:BatchGetSecretValue
secretsmanager:ListSecrets
sts:AssumeRole

Required IAM Roles (for role chaining tests)

The role chaining integration tests require two IAM roles in the same account:

secrets-manager-agent — Must be assumable by the test runner’s identity and have secretsmanager:GetSecretValue and secretsmanager:DescribeSecret permissions.
secrets-manager-agent-no-access — Must be assumable by the test runner’s identity but have no Secrets Manager permissions. Used to verify access-denied behavior.

Both roles must have a trust policy that allows the identity running the tests to call sts:AssumeRole. The account ID is discovered automatically via sts:GetCallerIdentity.

Running Tests

Option 1: Using the test script

Configure your AWS credentials with appropriate permissions
Run the test script:
```
./test-local.sh
```

Option 2: Manual execution

Configure your AWS credentials with appropriate permissions
Build the agent binary:
```
cargo build
```

Run the integration tests:

cd integration-tests
cargo test -- --test-threads=1

Test Organization

The integration tests are organized into the following modules:

secret_retrieval.rs - Tests core secret retrieval functionality including name/ARN lookup, binary secrets, large secrets, and error handling
cache_behavior.rs - Tests caching mechanisms including TTL expiration, refreshNow parameter, and cache bypass (TTL=0)
security.rs - Tests security features including SSRF token validation and X-Forwarded-For header rejection
version_management.rs - Tests secret version transitions and rotation scenarios
configuration.rs - Tests configuration parameters including health checks and path-based requests
role_chaining.rs - Tests cross-account secret retrieval via IAM role assumption, including invalid role ARN handling, access denied scenarios, refreshNow with role chaining, and separate per-role cache isolation
prefetch.rs - Tests pre-fetching secrets into the cache at startup, including explicit secrets, tag-based discovery, inline TOML syntax, cross-account pre-fetching via role chaining, and resilience to nonexistent secrets

Description

Why is this change being made?

What is changing?

Related Links

Testing

How was this tested?

When testing locally, provide testing artifact(s):

Reviewee Checklist

Reviewer Checklist

AWS Secrets Manager Agent

Step 1: Build the Secrets Manager Agent binary

[ RPM-based systems ]

[ Debian-based systems ]

[ Windows ]

[ Cross-compile natively ]

[ Cross compile with Rust cross ]

Step 2: Install the Secrets Manager Agent

[ Amazon EC2 ]

[ Running as a Container Sidecar ]

[ AWS Lambda ]

Step 3: Retrieve secrets with the Secrets Manager Agent

[ curl ]

[ Python ]

refreshNow parameter behavior

Using the refreshNow parameter

Example - Secrets Manager Agent GET request with refreshNow parameter

[ curl ]

[ Python ]

Role chaining (cross-account access)

[ curl ]

[ Python ]

Pre-fetching

Example - Pre-fetch with explicit secrets

Example - Pre-fetch with explicit secrets (inline syntax)

Example - Pre-fetch with tag-based discovery

Example - Full configuration with pre-fetching

Configure the Secrets Manager Agent

Optional features

Logging

Security considerations

Running Integration Tests Locally

Prerequisites

Required AWS Permissions

Required IAM Roles (for role chaining tests)

Running Tests

Option 1: Using the test script

Option 2: Manual execution

Test Organization

`refreshNow` parameter behavior