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 prevent malicious users from accessing any exposed secrets. It also scans all of the documentation your team has published, regardless of the type of workspace it's found in.

The Secret Scanner is available on all Postman plans and is turned on by default. If you're on an Enterprise plan with the Advanced Security Admin add-on, Secret Scanner will monitor team workspaces in addition to public workspaces and documentation.

How Secret Scanner works

Postman's Secret Scanner is turned on by default for all Postman teams. It follows all updates made by team members and scans them for supported secrets.

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

Postman delivers scan results 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 Slack integration to alert you in Slack if this occurs.

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.

Secret Scanner dashboard

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.

Resolve detected secret

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 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.
Resolve detected secret

Secret Scanner summary emails

Team Admins, Super Admins, and Workspace Admins can stay informed about Secret Scanner findings by subscribing to weekly or monthly summary emails. Subscribers will receive a monthly summary email on the first of every month or 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 option. From there, you can select the box for either weekly or monthly summaries—or both—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.

    Create custom pattern

To edit a custom pattern, select the edit icon 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 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.

    Create custom pattern dry run

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.

    Custom pattern dry run results

    If you want to make changes to the dry run, select the delete icon 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 Slack integration 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.

Last modified: 2023/12/15