Netlify Docs
Ask Netlify

Contact

Configure & deploy site /Environment variables /

Enhanced security with Secrets Controller

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.

This page outlines the environment variable secrets policy, how to manage environment variable secrets on Netlify, and how secrets scanning proactively finds embedded secrets before they’re exposed.

# 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 processing scope 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 dev deploy context will not have this policy applied to it. As such, only the value for the dev deploy 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 under

    Site configuration Environment variables
    or under
    Team settings Environment variables
    . For new or existing variables, select Contains secret values to flag that an environment variable contains a secret.

    • If importing from an .env file in the Netlify UI, import all variables first, then select
      Options Edit
      and select Contains secret values to flag specific environment variables as secrets.

  • With the Netlify CLI, use env:set with the --secret flag 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 createEnvVars and updateEnvVar to create or modify a site environment variable with the is_secret field 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:

  • plaintext
  • base64-encoded
  • URI-encoded

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

 abc
def
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 false to 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. Values can be substrings of paths or use a glob pattern format.

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.

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.

←