AWS secretsmanager documentation change
Summary
Major restructuring and expansion of Secrets Manager Agent documentation including caching behavior, installation steps, configuration options, security considerations, and new sections about SSRF protection and FIPS compliance
Security assessment
Added explicit documentation about SSRF protections, cache security implications (unencrypted secrets in cache), and FIPS compliance features. While security-related documentation is enhanced, there's no evidence of addressing a newly discovered vulnerability.
Diff
diff --git a/secretsmanager/latest/userguide/secrets-manager-agent.md b/secretsmanager/latest/userguide/secrets-manager-agent.md index 6bc052c96..514cde175 100644 --- a//secretsmanager/latest/userguide/secrets-manager-agent.md +++ b//secretsmanager/latest/userguide/secrets-manager-agent.md @@ -5 +5 @@ -Step 1: Build the Secrets Manager Agent binaryStep 2: Install the Secrets Manager AgentStep 3: Retrieve secrets with the Secrets Manager AgentForce-refresh secrets with RefreshNowConfiguration fileLoggingSecurity considerations +How the Secrets Manager Agent worksUnderstanding Secrets Manager Agent cachingBuild the Secrets Manager AgentInstall the Secrets Manager AgentRetrieve secrets with the Secrets Manager AgentUnderstanding the refreshNow parameterConfiguration optionsOptional featuresLoggingSecurity considerations @@ -7 +7 @@ Step 1: Build the Secrets Manager Agent binaryStep 2: Install the Secrets Manage -# AWS Secrets Manager Agent +# Using the AWS Secrets Manager Agent @@ -9 +9 @@ Step 1: Build the Secrets Manager Agent binaryStep 2: Install the Secrets Manage -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. +## How the Secrets Manager Agent works @@ -11 +11 @@ The AWS Secrets Manager Agent is a client-side HTTP service that you can use to -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. 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. +The AWS Secrets Manager Agent is a client-side HTTP service that helps you standardize how you consume secrets from Secrets Manager across your compute environments. You can use it with the following services: @@ -13 +13 @@ The Secrets Manager Agent uses the AWS credentials you provide in your environme -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. + * AWS Lambda @@ -15 +15 @@ Because the Secrets Manager Agent uses an in-memory cache, it resets when the Se -The Secrets Manager Agent returns secret values in the same format as the response of `GetSecretValue`. Secret values are not encrypted in the cache. + * Amazon Elastic Container Service @@ -17 +17,31 @@ The Secrets Manager Agent returns secret values in the same format as the respon -To download the source code, see [https://github.com/aws/aws-secretsmanager-agent](https://github.com/aws/aws-secretsmanager-agent) on GitHub. + * Amazon Elastic Kubernetes Service + + * Amazon Elastic Compute Cloud + + + + +The Secrets Manager Agent retrieves and caches secrets in memory, allowing your applications to get secrets from localhost instead of making direct calls to Secrets Manager. The Secrets Manager Agent can only read secrets—it can't modify them. + +###### Important + +The Secrets Manager Agent uses the AWS credentials from your environment to call Secrets Manager. It includes protection against Server Side Request Forgery (SSRF) to help improve secret security. + +## Understanding Secrets Manager Agent caching + +The Secrets Manager Agent uses an in-memory cache that resets when the Secrets Manager Agent restarts. It periodically refreshes cached secret values based on the following: + + * The default refresh frequency (TTL) is 300 seconds + + * You can modify the TTL using a configuration file + + * The refresh occurs when you request a secret after the TTL expires + + + + +###### Note + +The Secrets Manager Agent doesn't include cache invalidation. 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 aren't encrypted in the cache. @@ -21 +51 @@ To download the source code, see [https://github.com/aws/aws-secretsmanager-agen - * Step 1: Build the Secrets Manager Agent binary + * Build the Secrets Manager Agent @@ -23 +53 @@ To download the source code, see [https://github.com/aws/aws-secretsmanager-agen - * Step 2: Install the Secrets Manager Agent + * Install the Secrets Manager Agent @@ -25 +55 @@ To download the source code, see [https://github.com/aws/aws-secretsmanager-agen - * Step 3: Retrieve secrets with the Secrets Manager Agent + * Retrieve secrets with the Secrets Manager Agent @@ -27 +57 @@ To download the source code, see [https://github.com/aws/aws-secretsmanager-agen - * Force-refresh secrets with RefreshNow + * Understanding the refreshNow parameter @@ -30,0 +61,2 @@ To download the source code, see [https://github.com/aws/aws-secretsmanager-agen + * Optional features + @@ -38 +70,11 @@ To download the source code, see [https://github.com/aws/aws-secretsmanager-agen -## Step 1: Build the Secrets Manager Agent binary +## Build the Secrets Manager Agent + +Before you begin, ensure you have the standard development tools and Rust tools installed for your platform. + +###### 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` + + @@ -40 +81,0 @@ To download the source code, see [https://github.com/aws/aws-secretsmanager-agen -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. @@ -45 +86,5 @@ RPM-based systems - 1. On RPM-based systems such as AL2023, you can install the development tools by using the Development Tools group. +###### To build on RPM-based systems + + 1. ###### Install development tools + +On RPM-based systems such as AL2023, install the Development Tools group: @@ -49 +94 @@ RPM-based systems - 2. Follow the instructions at [Install Rust](https://www.rust-lang.org/tools/install) in the _Rust documentation_. + 2. ###### Install Rust @@ -51 +96,3 @@ RPM-based systems - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +Follow the instructions at [Install Rust](https://www.rust-lang.org/tools/install) in the _Rust documentation_ : + + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions @@ -54 +101,3 @@ RPM-based systems - 3. Build the agent using the cargo build command: + 3. ###### Build the agent + +Build the Secrets Manager Agent using the cargo build command: @@ -58 +107 @@ RPM-based systems -You will find the executable under `target/release/aws-secrets-manager-agent`. +You will find the executable under `target/release/aws_secretsmanager_agent`. @@ -66 +115,5 @@ Debian-based systems - 1. On Debian-based systems such as Ubuntu, you can install the developer tools using the build-essential package. +###### To build on Debian-based systems + + 1. ###### Install development tools + +On Debian-based systems such as Ubuntu, install the build-essential package: @@ -70 +123 @@ Debian-based systems - 2. Follow the instructions at [Install Rust](https://www.rust-lang.org/tools/install) in the _Rust documentation_. + 2. ###### Install Rust @@ -72 +125,3 @@ Debian-based systems - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +Follow the instructions at [Install Rust](https://www.rust-lang.org/tools/install) in the _Rust documentation_ : + + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions @@ -75 +130,3 @@ Debian-based systems - 3. Build the agent using the cargo build command: + 3. ###### Build the agent + +Build the Secrets Manager Agent using the cargo build command: @@ -79 +136 @@ Debian-based systems -You will find the executable under `target/release/aws-secrets-manager-agent`. +You will find the executable under `target/release/aws_secretsmanager_agent`. @@ -87 +144,16 @@ Windows -To build on Windows, follow the instructions at [Set up your dev environment on Windows for Rust](https://learn.microsoft.com/en-us/windows/dev-environment/rust/setup) in the _Microsoft Windows documentation_. +###### To build on Windows + + 1. ###### Set up development environment + +Follow the instructions at [Set up your dev environment on Windows for Rust](https://learn.microsoft.com/en-us/windows/dev-environment/rust/setup) in the _Microsoft Windows documentation_. + + 2. ###### Build the agent + +Build the Secrets Manager Agent using the cargo build command: + + cargo build --release + +You will find the executable under `target/release/aws_secretsmanager_agent.exe`. + + + @@ -92 +164,3 @@ Cross-compile natively -On distributions where the mingw-w64 package is available such as Ubuntu, you can cross compile natively. +###### To cross-compile natively + + 1. ###### Install cross-compile tools @@ -93,0 +168 @@ On distributions where the mingw-w64 package is available such as Ubuntu, you ca +On distributions where the mingw-w64 package is available such as Ubuntu, install the cross-compile toolchain: @@ -99 +174,4 @@ On distributions where the mingw-w64 package is available such as Ubuntu, you ca - # Install the rust build targets + 2. ###### Add Rust build targets + +Install the Windows GNU build target: + @@ -102 +180,4 @@ On distributions where the mingw-w64 package is available such as Ubuntu, you ca - # Cross compile the agent for Windows + 3. ###### Build for Windows + +Cross-compile the agent for Windows: + @@ -105 +186,4 @@ On distributions where the mingw-w64 package is available such as Ubuntu, you ca -You will find the executable at `target/x86_64-pc-windows-gnu/release/aws-secrets-manager-agent.exe`. +You will find the executable at `target/x86_64-pc-windows-gnu/release/aws_secretsmanager_agent.exe`. + + + @@ -110 +194,3 @@ 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](https://github.com/cross-rs/cross). +###### To cross-compile using 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](https://github.com/cross-rs/cross). @@ -115,0 +202,3 @@ We recommend 32GB disk space for the build environment. + 1. ###### Set up Docker + +Install and configure Docker: @@ -121,0 +211,4 @@ We recommend 32GB disk space for the build environment. + 2. ###### Configure Docker permissions + +Add your user to the docker group: + @@ -125,0 +219,4 @@ We recommend 32GB disk space for the build environment. + 3. ###### Build for Windows + +Install cross and build the executable: + @@ -130 +226,0 @@ We recommend 32GB disk space for the build environment. -## Step 2: Install the Secrets Manager Agent @@ -132 +227,0 @@ We recommend 32GB disk space for the build environment. -Based on the type of compute, you have several options for installing the Secrets Manager Agent. @@ -134 +229,6 @@ Based on the type of compute, you have several options for installing the Secret -Amazon EKS, Amazon EC2, and Amazon ECS +