With Secrets Controller, your team can protect and manage environment variable values that require additional layers of security. Flag which environment variables are secrets, and Netlify will apply stricter requirements to them. While Netlify handles all environment variables securely, including encrypted storage, Secrets Controller protects environment variable secrets with an opinionated policy and additional security features.
# Environment variable secrets policy
Not all environment variables are created equal. Environment variable secrets are sensitive values that would have a detrimental impact on your organization or end users if they were accessed by the wrong party. When you flag environment variables as secret, Netlify’s opinionated policy enforces how these values are accessed and which scopes and features you can use with them.
This policy’s design removes options that could allow your team to inadvertently expose secrets and drives your team to be explicit about where secret values should be accessible.
Environment variable secrets have the following policy applied to them:
- Secret values are write-only. After setting a value using the UI, CLI, or API, you will no longer have access to a human-readable version of the value.
- Secret values must be set to explicit deploy contexts and scopes to avoid unexpected exposure.
- After an environment variable is flagged as a secret, you cannot remove the flag to reveal the secret’s value.
- Environment variable secrets cannot have the
post processingscope to avoid inadvertently exposing the value through features like snippet injection.
- Only code running on Netlify’s systems can read the original, unmasked values. Your code running on edge functions, serverless functions, build process, etc. will have the original unmasked values of the environment variables. Code running outside of Netlify’s hosted systems will have masked versions of the environment variable values.
- A value set in the environment variable’s
devdeploy context will not have this policy applied to it. As such, only the value for the
devdeploy context will be unmasked from the UI, CLI, and API. This will allow developers to continue developing with non-secret values that are explicitly for development.
None of these policy enforcements can be changed or customized using any form of configuration.
Values are masked except in dev context
Our UI, CLI, and API won’t return unmasked values of environment variable secrets for any deploy context besides
dev. Using the CLI to do a production build with
netlify build won’t include the raw, unmasked values. Per the policy, only code running on our systems have access to the unmasked value.
# Manage secret values
Environment variables that are marked as secret use the same underlying systems for configuring and managing values as other environment variables do. As such, you can use the same flows for creating and modifying environment variables. During those flows you can flag variables as secret if the values contain secrets.
# Configure environment variable secrets
Environment variables are configured through Netlify’s UI, CLI, or API. For each method, you can specify values as secrets:
In the Netlify UI, create and modify variables underor under . For new or existing variables, select
Contains secret valuesto flag that an environment variable contains a secret.
- If importing from an
.envfile in the Netlify UI, import all variables first, then select and select
Contains secret valuesto flag specific environment variables as secrets.
- If importing from an
With the Netlify CLI, use
--secretflag to create or modify a site environment variable to be an environment variable secret. Review our Get Started with Netlify CLI guide to learn more.
With the Netlify API, use
updateEnvVarto create or modify a site environment variable with the
is_secretfield set to
true. Review our Get Started with Netlify API guide to learn more.
Environment variable secret values can be created and modified, but they’re not human-readable from the UI, CLI, or API after they’re flagged as secret. To avoid allowing access to secret values, once you flag an environment variable as a secret, this flag cannot be removed.
# Use secret values
Environment variable secrets are environment variables that have restricted access. Per the secrets policy, only code running on Netlify will receive the raw, unmasked values. Within your code, you use environment variable secrets the same way as you use traditional environment variables.
Only values that are configured for the
dev deploy context are human readable from the UI, CLI, and API. This allows developers to use development context environment variables locally. All other contexts have restricted access based on our environment variables secrets policy.
# Secrets scanning overview
When you explicitly mark which environment variables have secret values, Netlify proactively protects your team with secrets scanning. This process scans your repository code and build output files for the existence of secret values. If the scanning process finds secret values, it fails the build and adds the location of the secret values to the deploy log. Secrets scanning happens before publish and deploy steps to ensure secret values aren’t exposed publicly or stored in files that are downloadable by members of your Netlify team.
It’s easy to inadvertently add code that injects secrets into server and client code. When this happens, it can go undetected a long time after the initial leak. Secrets exposure can cost your company a lot of time, money, and customer trust. Secrets scanning is an essential security layer to protect your teams and end users.
Do I need Netlify secrets scanning if I’m scanning secrets on my repo?
We recommend using all security tools available to keep your team and users safe. While repository-specific secret scanning is a helpful tool for scanning secrets that your repository is aware of, there are secret values on Netlify that your code repo is unlikely to discover. For example, database passwords or server secret keys provided at runtime are unlikely to be in your code repository’s list of secrets.
# Secrets scanning process
Secrets scanning searches all files that are in your site’s build, including code pulled from the repo and files generated during the build.
To reduce the chances of false positives, secrets scanning only searches for environment variable secret values that have more than four characters and are not booleans.
In the common build steps that inject data into files or bundles, you don’t always use the plaintext version of those values. Given this, Netlify’s secret scanning will search for different permutations of values in the following formats:
In addition to the different encodings, any values that appear to be a multi-line string will also have their full value searched as a single line string and in multi-line form.
For example, with an environment variable secret such as
SECRET_ALPHABET="abc\ndef\nghi" the scanner will find four matches in the following file.
abc\ndef\nghi <- plaintext
YWJjCmRlZgpnaGk= <- base64 encoded
abc%0Adef%0Aghi <- uri encoded
ghi <- the multi line value
# Configure secrets scanning
When using environment variable secrets, secrets scanning is enabled automatically. Netlify will begin scanning on the next build after an environment variable is marked as secret. You may configure how the scanning works by setting any of the following environment variables at the site or team level.
Set these environment variables to some or all deploy contexts to customize secrets scanning for your site or team needs:
SECRETS_SCAN_ENABLED: default is
true. Set to
falseto entirely disable secrets scanning protections for the site/team.
SECRETS_SCAN_OMIT_KEYS: default is empty. Set to a comma separated list of key names that should not be scanned for within this site or team.
SECRETS_SCAN_OMIT_PATHS: default is empty. Set to a comma separated list of file paths (relative to the repository root) that should not be scanned within this site or team.
When you set the values at the team level, you may use site-specific environment variable values to override the team level settings. Review the environment variable overrides section to understand how to apply these settings to meet your team’s needs.
# Enhancing the sensitive variable policy
Netlify provides all customers who are using public repositories the ability to keep sensitive variables private and away from untrusted deploys through the sensitive variable policy. This feature provides you with the ability to protect sensitive variables on sites that use public repositories. To provide the sensitive variable policy capabilities, Netlify attempts to detect sensitive values based on heuristics such as the key name and the shape of the value.
Secrets Controller is designed to offer advanced security around explicitly flagged secrets and is only available on Core Enterprise plans.
When using Secrets Controller with a public repository, the sensitive variable policy applies to these environment variables:
- any variables that Netlify automatically detects as sensitive, even if they are not specifically flagged with
Contains secret values
- any variables explicitly flagged as sensitive by selecting
Contains secret values
With the sensitive variable policy, you can choose how to manage access to sensitive values for deploys from your public repo. Explicitly marked secret values are included in this policy.
Did you find this doc useful?
Your feedback helps us improve our docs.