aws/aws-secretsmanager-agent
GitHub: aws/aws-secretsmanager-agent
一个基于 Rust 的本地 HTTP 代理服务，通过内存缓存减少应用对 AWS Secrets Manager 的直接调用，实现低延迟、标准化的密钥获取。
Stars: 656 | Forks: 38
# AWS Secrets Manager Agent
AWS Secrets Manager Agent 是一个客户端 HTTP 服务，您可以使用它在 AWS Lambda、Amazon Elastic Container Service、Amazon Elastic Kubernetes Service 和 Amazon Elastic Compute Cloud 等环境中标准化使用 Secrets Manager 中的密钥。Secrets Manager Agent 可以在内存中检索和缓存密钥，以便您的应用程序可以直接从缓存中使用密钥。这意味着您可以从 localhost 获取应用程序所需的密钥，而无需向 Secrets Manager 发起调用。Secrets Manager Agent 只能向 Secrets Manager 发起读取请求，无法修改密钥。
Secrets Manager Agent 使用您在环境中提供的 AWS 凭证来调用 Secrets Manager。Secrets Manager Agent 提供了针对服务器端请求伪造 (SSRF) 的防护，以帮助提高密钥安全性。默认情况下，该 Agent 还使用后量子 ML-KEM 密钥交换作为最高优先级的密钥交换。您可以通过设置最大连接数、生存时间 (TTL)、localhost HTTP 端口和缓存大小来配置 Secrets Manager Agent。
由于 Secrets Manager Agent 使用内存缓存，因此当 Secrets Manager Agent 重启时，缓存会被重置。Secrets Manager Agent 会定期刷新缓存的密钥值。当 TTL 过期后您尝试从 Secrets Manager Agent 读取密钥时，就会进行刷新。默认的刷新频率 (TTL) 为 300 秒，您可以通过[配置文件](#secrets-manager-agent-config)进行更改，并使用 `--config` 命令行参数将其传递给 Secrets Manager Agent。Secrets Manager Agent 不包含缓存失效功能。例如，如果密钥在缓存条目过期之前轮换，Secrets Manager Agent 可能会返回过期的密钥值。
Secrets Manager Agent 返回密钥值的格式与 `GetSecretValue` 的响应格式相同。密钥值在缓存中不加密。
要下载源代码，请前往 GitHub 上的 [https://github\.com/aws/aws\-secretsmanager\-agent](https://github.com/aws/aws-secretsmanager-agent)。
**主题**
- [AWS Secrets Manager Agent](#aws-secrets-manager-agent)
- [步骤 1：构建 Secrets Manager Agent 二进制文件](#step-1-build-the-secrets-manager-agent-binary)
- [\[ 基于 RPM 的系统 \]](#-rpm-based-systems-)
- [\[ 基于 Debian 的系统 \]](#-debian-based-systems-)
- [\[ Windows \]](#-windows-)
- [\[ 原生交叉编译 \]](#-cross-compile-natively-)
- [\[ 使用 Rust cross 进行交叉编译 \]](#-cross-compile-with-rust-cross-)
- [步骤 2：安装 Secrets Manager Agent](#step-2-install-the-secrets-manager-agent)
- [\[ Amazon EC2 \]](#-amazon-ec2-)
- [\[ 作为容器 Sidecar 运行 \]](#-running-as-a-container-sidecar-)
- [\[ AWS Lambda \]](#-aws-lambda-)
- [步骤 3：使用 Secrets Manager Agent 检索密钥](#step-3-retrieve-secrets-with-the-secrets-manager-agent)
- [\[ curl \]](#-curl-)
- [\[ Python \]](#-python-)
- [`refreshNow` 参数行为](#refreshnow-parameter-behavior)
- [使用 refreshNow 参数](#using-the-refreshnow-parameter)
- [示例 - 带有 refreshNow 参数的 Secrets Manager Agent GET 请求](#example---secrets-manager-agent-get-request-with-refreshnow-parameter)
- [\[ curl \]](#-curl--1)
- [\[ Python \]](#-python--1)
- [配置 Secrets Manager Agent](#configure-the-secrets-manager-agent)
- [基于文件的凭证](#file-based-credentials)
- [日志记录](#logging)
- [安全注意事项](#security-considerations)
- [在本地运行集成测试](#running-integration-tests-locally)
- [先决条件](#prerequisites)
- [所需的 AWS 权限](#required-aws-permissions)
- [运行测试](#running-tests)
- [选项 1：使用测试脚本](#option-1-using-the-test-script)
- [选项 2：手动执行](#option-2-manual-execution)
- [测试组织结构](#test-organization)
## 步骤 1：构建 Secrets Manager Agent 二进制文件
要原生构建 Secrets Manager Agent 二进制文件，您需要标准开发工具和 Rust 工具。或者，您可以在支持它的系统上进行交叉编译，或者使用 Rust cross 进行交叉编译。
**注意：** 为了确保体验稳定，请从源代码构建时使用特定的 git 标签。您可以在[此处](https://github.com/aws/aws-secretsmanager-agent/tags)找到版本标签列表。标签的格式为 `/v\d+\.\d+\.\d+/`，并遵循 [SemVer 2.0.0](https://semver.org/spec/v2.0.0.html)。
示例：`git clone --branch https://github.com/aws/aws-secretsmanager-agent.git`
#### [ 基于 RPM 的系统 ]
1. 在基于 RPM 的系统（例如 AL2023）上，您可以使用 Development Tools 组安装开发工具。
sudo yum -y groupinstall "Development Tools"
2. 按照 *Rust 文档*中 [Install Rust](https://www.rust-lang.org/tools/install) 的说明进行操作。
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions
. "$HOME/.cargo/env"
3. 使用 cargo build 命令构建代理：
cargo build --release
您可以在 `target/release/aws_secretsmanager_agent` 下找到该可执行文件。
#### [ 基于 Debian 的系统 ]
1. 在基于 Debian 的系统（例如 Ubuntu）上，您可以使用 build\-essential 软件包安装开发工具。
sudo apt install build-essential
2. 按照 *Rust 文档*中 [Install Rust](https://www.rust-lang.org/tools/install) 的说明进行操作。
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions
. "$HOME/.cargo/env"
3. 使用 cargo build 命令构建代理：
cargo build --release
您可以在 `target/release/aws_secretsmanager_agent` 下找到该可执行文件。
#### [ Windows ]
要在 Windows 上进行构建，请按照 *Microsoft Windows 文档*中 [Set up your dev environment on Windows for Rust](https://learn.microsoft.com/en-us/windows/dev-environment/rust/setup) 的说明进行操作。
1. 使用 cargo build 命令构建代理：
cargo build --release
您可以在 `target/release/aws_secretsmanager_agent.exe` 下找到该可执行文件。
#### [ 原生交叉编译 ]
在提供 mingw\-w64 软件包的发行版（例如 Ubuntu）上，您可以原生交叉编译。
```
# 安装 cross compile 工具链
sudo add-apt-repository universe
sudo apt install -y mingw-w64
# 安装 rust 编译目标
rustup target add x86_64-pc-windows-gnu
# 为 Windows Cross compile agent
cargo build --release --target x86_64-pc-windows-gnu
```
您可以在 `target/x86_64-pc-windows-gnu/release/aws_secretsmanager_agent.exe` 找到该可执行文件。
#### [ 使用 Rust cross 进行交叉编译 ]
如果系统原生不提供交叉编译工具，您可以使用 Rust cross 项目。有关更多信息，请参阅 [https://github\.com/cross\-rs/cross](https://github.com/cross-rs/cross)。
**重要**
我们建议为构建环境分配 32GB 的磁盘空间。
```
# 安装并启动 docker
sudo yum -y install docker
sudo systemctl start docker
sudo systemctl enable docker # Make docker start after reboot
# 授予我们在不使用 sudo 的情况下运行 docker images 的权限
sudo usermod -aG docker $USER
newgrp docker
# 安装 cross 并 cross compile 可执行文件
cargo install cross
cross build --release --target x86_64-pc-windows-gnu
```
## 步骤 2：安装 Secrets Manager Agent
根据计算类型的不同，您有多种安装 Secrets Manager Agent 的选项。
#### [ Amazon EC2 ]
**安装 Secrets Manager Agent**
1. `cd aws_secretsmanager_agent/configuration`
2. 运行存储库中提供的 `install` 脚本。
该脚本在启动时会生成一个随机的 SSRF token，并将其存储在文件 `/var/run/awssmatoken` 中。该 token 可由安装脚本创建的 `awssmatokenreader` 组读取。
3. 要允许您的应用程序读取 token 文件，您需要将应用程序运行所用的用户账户添加到 `awssmatokenreader` 组。例如，您可以使用以下 usermod 命令授予应用程序读取 token 文件的权限，其中 ** 是应用程序运行所用的用户 ID。
sudo usermod -aG awssmatokenreader
#### [ 作为容器 Sidecar 运行 ]
您可以使用 Docker 将 Secrets Manager Agent 作为 sidecar 容器与应用程序一起运行。然后，您的应用程序可以从 Secrets Manager Agent 提供的本地 HTTP 服务器检索密钥。有关 Docker 的信息，请参阅 [Docker 文档](https://docs.docker.com)。
**使用 Docker 创建用于 Secrets Manager Agent 的 sidecar 容器**
1. 为 Secrets Manager Agent sidecar 容器创建一个 Dockerfile。以下示例创建了一个包含 Secrets Manager Agent 二进制文件的 Docker 容器。
# 使用最新的 Debian image 作为基础
FROM debian:latest
# 设置容器内的 working directory
WORKDIR /app
# 将 Secrets Manager Agent 二进制文件复制到容器中
COPY secrets-manager-agent .
# 安装所有必要的依赖项
RUN apt-get update && apt-get install -y ca-certificates
# 将 entry point 设置为运行 Secrets Manager Agent 二进制文件
ENTRYPOINT ["./secrets-manager-agent"]
2. 为您的客户端应用程序创建一个 Dockerfile。
3. 创建一个 Docker Compose 文件来运行这两个容器，并确保它们使用相同的网络接口。这是必需的，因为 Secrets Manager Agent 不接受来自 localhost 接口外部的请求。以下示例展示了一个 Docker Compose 文件，其中 `network_mode` 键将 `secrets-manager-agent` 容器附加到 `client-application` 容器的网络命名空间，这允许它们共享相同的网络接口。
**重要**
您必须加载 AWS 凭证和 SSRF token，应用程序才能使用 Secrets Manager Agent。对于 EKS 和 ECS，请参阅以下内容：
* *Amazon Elastic Kubernetes Service 用户指南*中的[管理访问权限](https://docs.aws.amazon.com/eks/latest/userguide/cluster-auth.html)
* *Amazon Elastic Container Service 开发人员指南*中的 [Amazon ECS 任务 IAM 角色](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)
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. 将 `secrets-manager-agent` 二进制文件复制到包含您的 Dockerfile 和 Docker Compose 文件的同一目录中。
5. 使用以下 [https://docs.docker.com/reference/cli/docker/compose/](https://docs.docker.com/reference/cli/docker/compose/) 命令，根据提供的 Dockerfile 构建并运行容器。
docker-compose up --build
6. 在您的客户端容器中，您现在可以使用 Secrets Manager Agent 来检索密钥。有关更多信息，请参阅[步骤 3：使用 Secrets Manager Agent 检索密钥](#secrets-manager-agent-call)。
#### [ AWS Lambda ]
您可以[将 Secrets Manager Agent 打包为 AWS Lambda 扩展](https://docs.aws.amazon.com/lambda/latest/dg/packaging-layers.html)。然后，您可以[将其作为层添加到您的 Lambda 函数中](https://docs.aws.amazon.com/lambda/latest/dg/adding-layers.html)，并从您的 Lambda 函数调用 Secrets Manager Agent 来获取密钥。
以下说明展示了如何使用 [https://github\.com/aws/aws\-secretsmanager\-agent](https://github.com/aws/aws-secretsmanager-agent) 中的示例脚本 `secrets-manager-agent-extension.sh` 将 Secrets Manager Agent 作为 Lambda 扩展安装，以获取名为 *MyTest* 的密钥。
**创建打包 Secrets Manager Agent 的 Lambda 扩展**
1. 将代理打包为一个层。在 Secrets Manager Agent 代码包的根目录中，运行以下示例命令：
AWS_ACCOUNT_ID=
LAMBDA_ARN=
# 构建 release binary
cargo build --release --target=x86_64-unknown-linux-gnu
# 将 release binary 复制到 `bin` 文件夹中
mkdir -p ./bin
cp ./target/x86_64-unknown-linux-gnu/release/aws_secretsmanager_agent ./bin/secrets-manager-agent
# 将 `secrets-manager-agent-extension.sh` 示例脚本复制到 `extensions` 文件夹中。
mkdir -p ./extensions
cp aws_secretsmanager_agent/examples/example-lambda-extension/secrets-manager-agent-extension.sh ./extensions
# 将 extension shell 脚本和二进制文件打包为 Zip
zip secrets-manager-agent-extension.zip bin/* extensions/*
# 发布 layer 版本
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. 代理的默认配置会自动将 SSRF token 设置为预设的 `AWS_SESSION_TOKEN` 或 `AWS_CONTAINER_AUTHORIZATION_TOKEN` 环境变量中设置的值（后一个变量适用于启用了 SnapStart 的 Lambda 函数）。或者，您可以为 Lambda 函数定义带有任意值的 `AWS_TOKEN` 环境变量，因为该变量优先于其他两个变量。如果您选择使用 `AWS_TOKEN` 环境变量，则必须通过 `lambda:UpdateFunctionConfiguration` 调用来设置该环境变量。
3. 将层版本附加到您的 Lambda 函数：
# 将 layer 版本附加到 Lambda 函数
aws lambda update-function-configuration \
--function-name $LAMBDA_ARN \
--layers "$LAYER_VERSION_ARN"
4. 更新您的 Lambda 函数，使其查询 `http://localhost:2773/secretsmanager/get?secretId=MyTest`，并将 `X-A-Parameters-Secrets-Token` 标头值设置为从上述环境变量之一获取的 SSRF token 值，以检索密钥。请确保在应用程序代码中实现重试逻辑，以适应 Lambda 扩展初始化和注册过程中的延迟。
5. 调用 Lambda 函数以验证密钥是否被正确获取。
## 步骤 3：使用 Secrets Manager Agent 检索密钥
要使用该代理，您需要调用本地 Secrets Manager Agent endpoint，并将密钥的名称或 ARN 作为查询参数包含在内。默认情况下，Secrets Manager Agent 检索密钥的 `AWSCURRENT` 版本。要检索其他版本，您可以设置 `versionStage` 或 `versionId`。
为了帮助保护 Secrets Manager Agent，您必须在每个请求中包含 SSRF token 标头：`X-Aws-Parameters-Secrets-Token`。Secrets Manager Agent 会拒绝没有此标头或具有无效 SSRF token 的请求。您可以在[配置文件](#secrets-manager-agent-config)中自定义 SSRF 标头名称。
Secrets Manager Agent 使用 AWS SDK for Rust，该 SDK 使用 [https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html)。这些 IAM 凭证的身份决定了 Secrets Manager Agent 检索密钥所拥有的权限。
**所需权限： **
+ `secretsmanager:DescribeSecret`
+ `secretsmanager:GetSecretValue`
有关更多信息，请参阅[权限参考](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_iam-policies.html)。
**重要**
在密钥值被拉取到 Secrets Manager Agent 之后，任何有权访问计算环境和 SSRF token 的用户都可以从 Secrets Manager Agent 缓存中访问该密钥。有关更多信息，请参阅[安全注意事项](#secrets-manager-agent-security)。
#### [ curl ]
以下 curl 示例展示了如何从 Secrets Manager Agent 获取密钥。该示例依赖于存储在文件中的 SSRF（这是安装脚本存储它的位置）。
```
curl -v -H \
"X-Aws-Parameters-Secrets-Token: $('; \
echo
```
#### [ Python ]
以下 Python 示例展示了如何从 Secrets Manager Agent 获取密钥。该示例依赖于存储在文件中的 SSRF（这是安装脚本存储它的位置）。
```
import requests
import json
# 根据提供的 secret id 从 Secrets Manager Agent 获取 secret 的函数。
def get_secret():
# Construct the URL for the GET request
url = f"http://localhost:2773/secretsmanager/get?secretId="
# 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}")
```
**使用 `RefreshNow` 强制刷新密钥**
了解如何使用 refreshNow 参数强制 Secrets Manager Agent (SMA) 刷新密钥值。
Secrets Manager Agent 使用内存缓存来存储密钥值，并定期刷新。默认情况下，当生存时间 (TTL) 过期后您请求密钥时，会发生这种刷新，通常为每 300 秒一次。但是，这种方法有时会导致密钥值过期，尤其是在缓存条目过期之前密钥发生轮换的情况下。
为了解决这一限制，Secrets Manager Agent 在 URL 中支持一个名为 `refreshNow` 的参数。您可以使用此参数强制立即刷新密钥值，绕过缓存并确保您拥有最新的信息。
默认行为（不使用 `refreshNow`）：
- 使用缓存值，直到 TTL 过期
- 仅在 TTL（默认 300 秒）过期后刷新密钥
- 如果在缓存过期前密钥发生轮换，可能会返回过期值
使用 `refreshNow=true` 的行为：
- 完全绕过缓存
- 直接从 Secrets Manager 检索最新的密钥值
- 使用新值更新缓存并重置 TTL
- 确保您始终获取最新的密钥值
通过使用 `refreshNow` 参数，您可以确保始终使用最新的密钥值，即使在需要频繁轮换密钥的场景中也是如此。
## `refreshNow` 参数行为
`refreshNow` 设置为 `true`：
- 如果 Secrets Manager Agent 无法从 Secrets Manager 检索密钥，它将返回错误并且不更新缓存。
`refreshNow` 设置为 `false` 或未指定：
- Secrets Manager Agent 遵循其默认行为：
- 如果缓存值的新鲜度高于 TTL，Secrets Manager Agent 将返回缓存值。
- 如果缓存值早于 TTL，Secrets Manager Agent 将向 Secrets Manager 发起调用。
## 使用 refreshNow 参数
要使用 `refreshNow` 参数，请将其包含在 Secrets Manager Agent GET 请求的 URL 中。
### 示例 - 带有 refreshNow 参数的 Secrets Manager Agent GET 请求
#### [ curl ]
以下 curl 示例展示了如何强制 Secrets Manager Agent 刷新密钥。该示例依赖于存储在文件中的 SSRF（这是安装脚本存储它的位置）。
```
curl -v -H \
"X-Aws-Parameters-Secrets-Token: $(&refreshNow=true' \
echo
```
#### [ Python ]
以下 Python 示例展示了如何从 Secrets Manager Agent 获取密钥。该示例依赖于存储在文件中的 SSRF（这是安装脚本存储它的位置）。
```
import requests
import json
# 根据提供的 secret id 从 Secrets Manager Agent 获取 secret 的函数。
def get_secret():
# Construct the URL for the GET request
url = f"http://localhost:2773/secretsmanager/get?secretId=&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}")
```
## 配置 Secrets Manager Agent
要更改 Secrets Manager Agent 的配置，请创建一个 [TOML](https://toml.io/en/) 配置文件，然后调用 `./aws_secretsmanager_agent --config config.toml`。
以下列表显示了您可以为 Secrets Manager Agent 配置的选项。
+ **log\_level** – Secrets Manager Agent 日志中报告的详细信息级别：DEBUG、INFO、WARN、ERROR 或 NONE。默认值为 INFO。
+ **log\_to\_file** - 是记录到文件还是 stdout/stderr：`true` 或 `false`。默认值为 `true`。
+ **http\_port** – 本地 HTTP 服务器的端口，范围为 1024 到 65535。默认值为 2773。
+ **region** – 用于请求的 AWS 区域。如果未指定区域，Secrets Manager Agent 将从 SDK 确定区域。有关更多信息，请参阅 *AWS SDK for Rust 开发人员指南*中的[指定您的凭证和默认区域](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html)。
+ **ttl\_seconds** – 缓存项目的 TTL（以秒为单位），范围为 0 到 3600。默认值为 300。0 表示不进行缓存。
+ **cache\_size** – 可以存储在缓存中的最大密钥数量，范围为 1 到 1000。默认值为 1000。
+ **ssrf\_headers** – Secrets Manager Agent 用于检查 SSRF token 的标头名称列表。默认值为 "X\-Aws\-Parameters\-Secrets\-Token, X\-Vault\-Token"。
+ **ssrf\_env\_variables** – Secrets Manager Agent 按顺序检查 SSRF token 的环境变量名称列表。环境变量可以包含 token 或对 token 文件的引用，例如：`AWS_TOKEN=file:///var/run/awssmatoken`。默认值为 "AWS\_TOKEN, AWS\_SESSION\_TOKEN, AWS\_CONTAINER\_AUTHORIZATION\_TOKEN"。
+ **path\_prefix** – 用于确定请求是否为基于路径的请求的 URI 前缀。默认值为 "/v1/"。
+ **max\_conn** – Secrets Manager Agent 允许来自 HTTP 客户端的最大连接数，范围为 1 到 1000。默认值为 800。
+ **credentials\_file\_path** – 包含标准 AWS 凭证文件格式的 AWS 凭证的文件路径。设置后，代理将从此文件读取凭证，而不是使用默认的 SDK 凭证提供程序链。当文件更改时，代理会自动重新加载凭证，使其与将刷新后的凭证传送到文件系统的凭证轮换系统兼容。此参数是可选的。
## 基于文件的凭证
默认情况下，Secrets Manager Agent 使用 [AWS SDK 默认凭证提供程序链](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credproviders.html)向 Secrets Manager 进行身份验证。这适用于 Amazon EC2（通过 IMDS）、Lambda 和 ECS/EKS（通过容器凭证）。
对于将凭证传送到文件系统的环境，例如使用 [IAM Roles Anywhere](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/introduction.html) 或其他凭证管理系统的本地主机，您可以将代理配置为从文件读取凭证。
### 凭证文件格式
凭证文件必须使用标准的 AWS 凭证文件格式：
```
[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token = IQoJb3JpZ2luX2Vj...
```
### 配置
在您的配置文件中设置 `credentials_file_path` 参数：
```
region = "us-east-1"
credentials_file_path = "/path/to/credentials"
```
### 凭证刷新行为
代理会自动检测并重新读取文件中已更新的凭证：
+ 代理每 5 分钟检查一次凭证文件是否有更改。
+ 当文件的修改时间发生变化时，代理会重新加载凭证。
+ 如果在重新加载期间文件丢失或格式不正确，代理将继续使用之前缓存的凭证，并在下一个周期重试。
+ 凭证将提供给具有 10 分钟过期窗口的 AWS SDK，确保 SDK 定期从提供程序请求新的凭证。
### 启动行为
代理被设计为无论凭证文件处于何种状态都能成功启动：
+ 如果文件存在且包含有效凭证，代理会立即加载它们。
+ 如果文件丢失、为空或格式不正确，代理将在没有凭证的情况下启动，并且后台重新加载任务将在有效凭证出现时获取它们。
+ 当配置了基于文件的凭证时，代理会在启动时跳过 STS 凭证验证检查，因为凭证文件可能尚不存在。`validate_credentials` 设置将继续应用于非基于文件的凭证源。
+ 对 Secrets Manager 的调用将失败，直到有效凭证可用。代理进程本身将保持运行，并在凭证出现在文件中后开始处理请求。
### 安全性
在 Unix 系统上，如果凭证文件的权限超过了仅限所有者（`0600`），代理会记录一条警告。请考虑限制文件权限：
```
chmod 600 /path/to/credentials
```
## 日志记录
Secrets Manager Agent 将错误本地记录到文件 `logs/secrets_manager_agent.log` 或 stdout/stderr 中，具体取决于 `log_to_file` 配置变量。当您的应用程序调用 Secrets Manager Agent 获取密钥时，这些调用会显示在本地日志中。它们不会出现在 CloudTrail 日志中。
Secrets Manager Agent 在文件大小达到 10 MB 时会创建一个新的日志文件，总共最多存储五个日志文件。
日志不会发送到 Secrets Manager、CloudTrail 或 CloudWatch。从 Secrets Manager Agent 获取密钥的请求不会出现在这些日志中。当 Secrets Manager Agent 调用 Secrets Manager 获取密钥时，该调用会记录在 CloudTrail 中，其用户代理字符串包含 `aws-secrets-manager-agent`。
您可以在[配置文件](#secrets-manager-agent-config)中配置日志记录。
## 安全注意事项
对于代理架构，信任域是可以访问代理 endpoint 和 SSRF token 的地方，通常是整个主机。Secrets Manager Agent 的信任域应与 Secrets Manager 凭证可用的域相匹配，以保持相同的安全态势。例如，在 Amazon EC2 上，当使用 Amazon EC2 角色时，Secrets Manager Agent 的信任域将与凭证的域相同。
尚未使用将 Secrets Manager 凭证锁定到应用程序的代理解决方案且注重安全的应用程序，应考虑使用特定语言的 AWS SDK 或缓存解决方案。有关更多信息，请参阅[获取密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html)。
## 在本地运行集成测试
AWS Secrets Manager Agent 包含一套全面的集成测试，用于针对真实的 AWS Secrets Manager 验证功能。这些测试涵盖了缓存行为、安全功能、配置选项、版本管理和错误处理场景。
### 先决条件
- 具有在 AWS Secrets Manager 中创建、读取、更新和删除密钥权限的 AWS 凭证
- 已安装 Rust 工具链
- 可以访问用于测试的 AWS 账户
### 所需的 AWS 权限
您的 AWS 凭证必须具备以下权限：
- `secretsmanager:CreateSecret`
- `secretsmanager:GetSecretValue`
- `secretsmanager:DescribeSecret`
- `secretsmanager:UpdateSecret`
- `secretsmanager:UpdateSecretVersionStage`
- `secretsmanager:PutSecretValue`
- `secretsmanager:DeleteSecret`
### 运行测试
#### 选项 1：使用测试脚本
1. 使用适当的权限配置您的 AWS 凭证
2. 运行测试脚本：
./test-local.sh
#### 选项 2：手动执行
1. 使用适当的权限配置您的 AWS 凭证
2. 构建代理二进制文件：
cargo build
3. 运行集成测试：
cd integration-tests
cargo test -- --test-threads=1
### 测试组织结构
集成测试被组织成以下模块：
- **`secret_retrieval.rs`** - 测试核心密钥检索功能，包括名称/ARN 查找、二进制密钥、大型密钥和错误处理
- **`cache_behavior.rs`** - 测试缓存机制，包括 TTL 过期、refreshNow 参数和绕过缓存 (TTL=0)
- **`security.rs`** - 测试安全功能，包括 SSRF token 验证和 X-Forwarded-For 标头拒绝
- **`version_management.rs`** - 测试密钥版本转换和轮换场景
- **`configuration.rs`** - 测试配置参数，包括健康检查和基于路径的请求
- **`file_credentials.rs`** - 测试基于文件的凭证加载，包括有效/无效/缺失凭证、自我修复（启动后出现凭证）和凭证轮换
标签：Amazon EC2, Amazon ECS, Amazon EKS, AWS, AWS Lambda, Docker, DPI, meg, ML-KEM, Python安全, Secrets Manager, SSRF防护, StruQ, TTL, 代码分析, 信息安全, 内存缓存, 凭证管理, 可视化界面, 后量子密码学, 安全防御评估, 客户端代理, 开源, 本地HTTP服务, 请求拦截, 防服务器端请求伪造