Secret Scanner

The Postman Secret Scanner scans public workspaces and published documentation to detect any exposed secrets. It checks all of the collections, global variables, environment variables, API schemas, and documentation in public workspaces to safeguard your organization from potential threats and malicious users attempting to access any exposed secrets.

The Secret Scanner is available for public workspaces in all Postman plans and is turned on by default. If you're on an Enterprise plan with the Advanced Security Admin add-on, the Secret Scanner will monitor team and public workspaces, and published documentation regardless of the type of workspace it's found in.

How Secret Scanner works

The Secret Scanner monitors your team's public workspaces and the collections, environments, global variables, API schemas, and documentation contained within them for exposed secrets. If you're on the Enterprise plan with the Advanced Security Admin add-on, the Secret Scanner will also monitor collections and APIs in your team workspaces, and documentation your team has published regardless of the type of workspace it's found in.

Postman's Secret Scanner is turned on by default for public workspaces in all Postman teams, and it delivers scan results in the Secret Scanner results. It follows all updates made by team members in public workspaces, and scans them for supported secrets. If an exposed secret is found, Postman notifies you by email.

Postman also delivers scan results for Enterprise teams in the Secret Scanner dashboard. If an exposed secret is found, Postman notifies you by email and in-app notification. You can also set up Postman's integration for Slack to alert you in Slack if this occurs.

It's recommended that you use your Postman Vault to store sensitive data as vault secrets. Only you can access and use values associated with your vault secrets, and vault secrets aren't synced to the Postman cloud. If you want to share sensitive data with collaborators, you can store it in an environment as a secret type variable.

Replace exposed secrets in public workspaces

Team Admins, Super Admins, and Workspace Admins will receive an email if the Secret Scanner detects exposed secrets, such as API keys, in your public workspaces. If secrets are detected in your public workspace, its visibility will be changed to team for Postman teams or personal for individual users. Learn more about types of workspace.

To protect your organization, never share sensitive data in your public workspaces. You can give your API consumers a placeholder variable or vault secret, such as {{vault:postman-api-key}}. A vault secret reference is recommended because your API consumers can add the vault secret to their Postman Vault with their own value, and only they can access it.

Select View exposed secrets in the email to open the Secret Scanner results. Review the results to replace each exposed secret with a placeholder for a variable or vault secret. Once you replace all exposed secrets, you can convert the workspace to a public workspace.

(Professional and Enterprise plans only) If there's a pending request to convert the workspace to a public workspace, you can also open the workspace settings and select Check status to check the status of the scan. If exposed secrets are detected, select View results to open the Secret Scanner results.

To replace each exposed secret, do the following:

1. In the Secret Scanner results window, review the details for each exposed secret:

   • Element type - The element type that has the exposed secret.
   • Element name - The name of the element type that has the exposed secret.
   • Secret name - The authorization type of the exposed secret.
   • Secret value - The partially masked value of the exposed secret.
   • Location - The path to the element with the exposed secret. You can select the path to open the exposed secret in a new tab.

2. Select Replace all to replace all exposed secrets with vault secrets at the same time. The value of each exposed secret is replaced with a reference to a vault secret based on the detected key or token. For example, if a Postman API key is detected, the key will be replaced with {{vault:postman-api-key}}. Then the Secret Scanner will scan your workspace again.

   

   It's important that you also revoke the exposed secrets the Secret Scanner detects.

   You can also remove or replace each secret one at a time. Under Location, select the path next to each exposed secret to open it in a new tab. Remove each exposed secret, or replace each value with a placeholder or vault secret reference that's relevant to your API. Then follow the steps to convert the workspace to a public workspace.

3. If no exposed secrets are detected, follow the steps in the Secret Scanner results window to make your workspace public:

   • If you have permission to convert a workspace, select Make workspace public to convert the workspace to a public workspace.
   • Otherwise, select Go to settings to request the workspace to be converted to a public workspace.

   Learn more about converting a workspace to a public workspace.

Secret Scanner dashboard

The Secret Scanner dashboard is available on Postman Enterprise plans. Secret Scanner reports are available on the Enterprise plan with the Advanced Security Admin add-on.

Team Admins and Super Admins can view detected secrets, configure default and custom patterns, and review Secret Scanner reports in the Secret Scanner dashboard. To open the dashboard, select Team > Team Settings in the Postman header. Then, select Secret Scanner in the left sidebar.

Resolve detected secrets

Team Admins and Super Admins can review the default and custom secrets that the Secret Scanner has found in the Secrets detected tab of the Secret Scanner dashboard. You can filter findings by visibility type, workspace name, and secret type. To view the details for a detected secret, select it from the list.

Admins and Super Admins can access all identified secrets within a team, including ones in public workspaces. Workspace Admins can also view secrets within the workspaces they manage.

Each detected secret shows where it was found and when it was detected. To view the SHA256 hash value of a detected secret, hover over the partially hidden value under its name and select the information icon .

To resolve a detected secret, select Unresolved and then select the reason for resolving it. You can resolve a finding with the following reasons:

• Revoked - This secret has been revoked.
• False positive - This secret isn't valid.
• Won't fix - This secret isn't relevant.

Secret Scanner summary emails

Team Admins, Super Admins, and Workspace Admins can stay informed about Secret Scanner findings by subscribing to daily, weekly, or monthly summary emails. You'll receive the following based on your selections:

• A daily summary email every day at 12:00 AM UTC.
• A monthly summary email on the first of every month.
• A weekly summary email every Monday.

Navigate to Notification preferences or select your avatar in the Postman header, then select Settings > Notifications to view the Secret Scanner summary options. From there, you can select the box for either daily, weekly, or monthly summaries—or all—and save your preferences.

Manage Secret Scanner findings with the Postman API

The Secret Scanner Postman API endpoints are available on the Postman Enterprise plan with the Advanced Security Admin add-on.

Team Admins, Super Admins, and Workspace Admins can access Secret Scanner findings through the Postman API. Using the Postman API enables you to create custom automated workflows to retrieve and resolve identified secrets. To learn more, see the Postman API documentation.

Supported secrets

The Secret Scanner searches for a variety of secrets by default. You can also add your team's proprietary third-party app tokens that aren't supported yet using custom patterns.

Default patterns

By default, the Secret Scanner checks for tokens issued by common service providers including Amazon, Google, GitHub, Stripe, and Twilio. To view the complete list of default patterns, open the Secret Scanner and select Configure patterns.

Custom patterns

Custom patterns are available on Postman Enterprise plans.

You can use custom patterns to scan your team's proprietary tokens and any third-party app tokens that aren't scanned by default. You can also dry run custom patterns before adding them to the Secret Scanner, enabling you to test the results that the custom pattern returns.

Your team can add a total of five patterns. You must be a Community Manager or team member with both Developer and Admin roles to add custom patterns.

To add custom patterns, do the following:

1. Open Postman and select Team > Team Settings in the Postman header. Select Secret Scanner in the left sidebar, then select the Configure patterns tab.

2. In the Custom patterns section, select +.

3. In the Pattern details section, add the following details for the custom token:

   • Name - The name of your custom pattern.
   • Regex - The regular expression that specifies the pattern of the secrets you want to find a match for.
   • Sample value - A sample value used to validate the regular expression pattern.

4. In the Scan activation section, select one of the following:

   • Add pattern to secret scanner - Add the secrets the Secret Scanner finds to the Secrets detected tab in the dashboard. By default, the Scan existing elements checkbox is selected, meaning the Secret Scanner will use the custom pattern to scan existing elements. If you'd like to only scan new elements, clear the Scan existing elements checkbox.

   • Dry run the pattern first with select workspaces - Dry run the custom pattern before adding it to the Secret Scanner. You can select up to 20 public or team workspaces for the dry run. The results of the dry run won't be added to the Secrets detected tab in the dashboard. Learn more about creating a custom pattern dry run.

5. Select Add Custom Pattern or Dry Run Pattern, depending on the option you selected in the Scan activation section.

   

To edit a custom pattern, select the edit icon next to a custom pattern. Edit the name or regular expression, update the sample value, then select Save. If you edited the regular expression, select one of the following to confirm your changes:

• Keep Existing Leaks - Show detected secrets in the Secrets detected tab that are associated with earlier iterations of this custom pattern.
• Remove Existing Leaks - Remove detected secrets from the Secrets detected tab that are associated with earlier iterations of this custom pattern.

When you edit a regular expression in a custom pattern, the updated regular expression is used to scan new elements only. To scan existing elements with the changes to the pattern, create a new custom pattern and make sure the Scan existing elements checkbox is selected.

To delete a custom pattern, select the delete icon next to a custom pattern. Then select Delete to confirm. When you delete a custom pattern, all detected secrets associated with this pattern will be removed from the Secrets detected tab in the dashboard.

Dry run custom patterns

When you create a custom pattern, you can choose to dry run the regular expression pattern before adding it to the Secret Scanner. This enables you to test the results that the regular expression pattern returns. You can dry run the pattern on up to 20 public or team workspaces. If the dry run works as expected, you can add the custom pattern to the Secret Scanner, enabling your team to review the results in your dashboard.

The results of the dry run won't be added to the Secrets detected tab in the dashboard. You must manually add the custom pattern to the Secret Scanner.

To dry run a custom pattern, do the following:

1. Add a custom pattern, and select Dry run the pattern first with select workspaces in the Scan activation section.

2. Select public or team workspaces to scan. You can select up to 20 workspaces.

3. Select Dry Run Pattern.

   

To view the dry run results and add the custom pattern, do the following:

1. Select the Configure patterns tab.

2. In the Custom patterns section, select View results next to the custom pattern when the dry run is completed. You can select results from the dry run to view more details.

   To run the dry run again, select Re-run Scan in the top right of Results from dry run page.

3. If the dry run performed as expected, you can add the custom pattern to the Secret Scanner, enabling you to view the results in the dashboard. In the Results from dry run page, select Add Pattern to Secret Scanner.

   

   If you want to make changes to the dry run, select the delete icon next to the custom pattern in the dashboard. Then add the custom pattern and dry run it with your changes.

4. To confirm, select one of the following:

   • Ignore Existing Elements - Scan only new elements with this custom pattern.
   • Scan Existing Elements - Scan new and existing elements with this custom pattern.

Protect Postman API keys in GitHub

Postman also works with GitHub to ensure that your Postman API keys are secure. If you commit a valid Postman API key to a public GitHub repository, Postman notifies you by email and in-app notification. You can also set up Postman's integration for Slack to alert you in Slack if this occurs.

It's recommended you delete the exposed API key in your API keys dashboard. You can then generate a new API key to continue working with the Postman API.

Protect Postman API keys in GitLab

This feature is available on GitLab Ultimate plans.

Postman works with GitLab to protect your Postman API keys in GitLab public repositories. If you accidentally commit a valid Postman API key to a public GitLab repository, Postman notifies you by email and in-app notification.

It's recommended you delete the exposed API key in your API keys dashboard immediately. You can then generate a new API key to continue working with the Postman API.