How to use AWS Secrets Manager in the CLI [With Examples]

Shlomi Kushchi
May 18, 2023
Start Free
How to use AWS Secrets Manager in the CLI [With Examples]

Secrets are for hackers what candy is for kids: they just can’t seem to get enough of it. While credentials and secrets help protect your systems, if poorly managed, they can quickly get into the hands of cyber attackers. And just like a kid in a candy shop, a hacker with unlimited access to your credentials can cause severe damage. 

Considering that a staggering 37% of cyberattacks result from stolen credentials, you can’t afford not to manage your secrets properly. The AWS Secrets Manager tool was built with these risks in mind. It helps AWS users secure and store sensitive information when running on their clouds, which can then be complemented by tools like Gitleaks, that focus on secret detection. 

This article delves into the intricacies of AWS Secrets Manager, exploring its features and practical examples of using the service via the Command Line Interface (CLI).

Secrets everywhere meme

An overview of AWS Secrets Manager

AWS Secrets Manager is a secrets management service provided by Amazon Web Services (AWS) that helps you protect sensitive information, such as access keys, passwords, and API keys, securely and centrally. It offers a convenient way to manage, store, and rotate secrets, enabling developers and security professionals to follow best practices when dealing with sensitive data in their applications.

It also integrates with other AWS tools and services, such as AWS Identity and Access Management (IAM), AWS Key Management Service (KMS), and AWS CloudTrail.

Understanding secrets and their values

In AWS Secrets Manager, a secret is a logical container for sensitive information consisting of a secret name and one or more secret values. Secret values are the sensitive data, such as passwords, API keys, or access tokens, that you want to store securely. Each secret value can have a unique version identifier, allowing you to track and manage different versions of the same secret.

Some examples of secrets include:

  • Database credentials, such as usernames and passwords
  • API keys for accessing third-party services
  • OAuth tokens for authentication and authorization
  • SSH keys for accessing servers and other resources
Common types of secrets

Features of AWS Secrets Manager

1. Securely store secrets

AWS Secrets Manager lets you securely store secrets in a centralized location, protecting sensitive data against unauthorized access and leaks. All secrets are encrypted using AWS Key Management Service (KMS) keys, which provide additional security and control over your encryption keys. This secure storage helps you comply with data protection regulations and maintain a strong security posture.

2. Manage the secret lifecycle

With AWS Secrets Manager, you can define and manage the entire lifecycle of your secrets, including creating, updating, and deleting secrets and managing secret versions and their metadata. The service lets you set up custom policies for secret rotation and expiration, helping you maintain up-to-date and secure credentials throughout your applications.

3. Automate secret rotation

One of the key features of AWS Secrets Manager is its ability to automate the rotation of secrets. The service can automatically generate new secrets and update the ones your applications use regularly or based on custom policies. Automated secret rotation helps to minimize the risk of compromised credentials and promotes best practices for managing sensitive data.

4. Access control

AWS Secrets Manager integrates with AWS Identity and Access Management (IAM), allowing you to define fine-grained access control policies for your secrets. You can specify which users or roles have permission to access, modify, or delete secrets, ensuring that only authorized personnel can interact with your sensitive data. This level of control helps you maintain a secure environment and comply with regulatory requirements.

5. Audit and monitor secret usage

Integration with AWS CloudTrail allows you to monitor and audit the use of your secrets in AWS Secrets Manager. CloudTrail logs all API calls to the service, providing a detailed record of who accessed your secrets, their location, and timings. You can use this information for security analysis, compliance audits, and troubleshooting.

6. Cross-account access

AWS Secrets Manager supports cross-account access, enabling you to share secrets securely between different AWS accounts. This feature simplifies the management of secrets in multi-account environments and ensures that sensitive data is accessible only by authorized accounts, further enhancing the security of your infrastructure.

AWS Secrets Manager

Using AWS Secrets Manager in the CLI

You can integrate AWS Secrets Manager through the AWS console, SDK, CLI, or CloudFormation. This section will focus on using the AWS Command Line Interface (CLI), a powerful and flexible tool that allows you to interact with AWS services directly from the command line, enabling you to automate tasks and create scripts for various use cases.

In the following sections, we will provide examples of using AWS Secrets Manager in CLI to manage your secrets. These examples will help you understand the basic operations and the syntax for the most common commands related to secrets management.

1. Creating a new secret and attaching tags

You can use the create-secret command to create a new secret using the AWS CLI. This command allows you to specify the secret name, value, and optional tags for easier organization and management:

 aws secretsmanager create-secret --name MySecret --secret-string "my-secret-value" --tags Key=Environment,Value=Production

This command creates a new secret named "MySecret" with the value "my-secret-value" and attaches the "Environment" tag with the value "Production."

2. Listing all secrets

To list all secrets stored in AWS Secrets Manager, you can use the list-secrets command:

 aws secretsmanager list-secrets

You will then see the complete list of secrets, including their names, ARNs, and other metadata.

3. Listing all versions of a secret

To list all versions of a specific secret, use the list-secret-version-ids command:

 aws secretsmanager list-secret-version-ids --secret-id MySecret

4. Retrieving a secret value

To retrieve the value of a secret and its additional metadata, such as the version ID and ARN, use the get-secret-value command:

 aws secretsmanager get-secret-value --secret-id MySecret

5. Retrieving the previous version of a secret

If you need to retrieve a previous version of a secret, use the get-secret-value command with the --version-id or --version-stage flag:

 aws secretsmanager get-secret-value --secret-id MySecret --version-id <previous-version-id>

This command returns the value of the specified previous version of the "MySecret" secret.

6. Viewing the details of a secret

To view the details of a secret, including its description, rotation configuration, and tags, use the describe-secret command:

 aws secretsmanager describe-secret --secret-id MySecret

7. Modifying a secret

To modify the value of an existing secret, use the update-secret command:

 aws secretsmanager update-secret --secret-id MySecret --secret-string "new-secret-value"

8. Creating a secret and encrypting it with KMS Key ID

To create a secret and encrypt it using a specific AWS KMS key, use the create-secret command with the --kms-key-id flag:

 aws secretsmanager create-secret --name MySecret --secret-string "my-secret-value" --kms-key-id <kms-key-id>

9. Creating Key/Value Pair Secret from a JSON file

To create a secret with key/value pairs from a JSON file, first, create a JSON file with your desired key/value pairs:


  "key1": "value1",

  "key2": "value2",

  "key3": "value3"


Save the file as my_secret_data.json. Then, use the create-secret command and pass the JSON file as the secret value:

 aws secretsmanager create-secret --name MySecret --secret-string file://my_secret_data.json

This command creates a new secret named "MySecret" with the key/value pairs defined in the JSON file.

10. Deleting a secret

To delete a secret, use the delete-secret command:

 aws secretsmanager delete-secret --secret-id MySecret

This command deletes the "MySecret" secret. Note that the secret will be scheduled for deletion and will be removed after the default recovery window of 30 days. You can also use the --force-delete-without-recovery flag to delete the secret immediately without the recovery window.

Enhance your secrets management with Jit

AWS Secrets Manager is a powerful solution for managing your organization's credentials and secrets. For even more robust protection, Jit orchestrates various open-source security tools such as the AWS security tool Prowler and the secrets detection solution Gitleaks. Deploying these tools through Jit and scanning only for new code means you can protect your entire CI/CD pipeline much more efficiently.

Start your secrets management journey with Jit today.

Instantly achieve continuous product security, from day 0