Most APIs in the real world require authentication. This process involves sending sensitive information with your request, allowing the server to verify and process it. Sensitive information includes:
- API keys
- Passwords
- Tokens
- Webhook URLs
- …and anything that should be secure and treated as a password
Postman environments and Postman Vault are powerful features that help safeguard sensitive information when making requests. You can use secret environment variables to ensure their value doesn’t persist and securely manage sensitive authentication details without compromising security. This approach protects confidential data values.
Postman Vault lets you store your secrets locally, so you can store and reuse sensitive data as secrets in your local instance of Postman. You can reuse these secrets in all of your workspaces in your Postman team, and they aren’t synced to the Postman cloud.
However, what measures can be taken if sensitive information is accidentally saved and shared? Is there a way to be notified of such potential security breaches?
Postman has addressed this concern with the Secret Scanner, a feature designed to detect and address any potentially exposed secrets within your Postman assets. The Secret Scanner examines all your Postman assets, identifies any potential secrets that may have been accidentally exposed, and lets you resolve them in Postman.
When the Secret Scanner detects a new exposed secret you’ll receive an email notification. You can even configure integrations with Slack to receive real-time Slack notifications.
In the Secret Scanner dashboard, you can see the list of unresolved detected secrets along with information on where and how each is exposed, making it easier for you to get started resolving each. You must then manually mark each secret as resolved, one at a time, in the dashboard.
However, if you’re looking for a faster way to manage your secrets without the time-consuming process of doing it manually, you’re in luck. The Postman API endpoints—available with Postman’s Enterprise plans —enable you to programmatically manage your secrets. You can:
- Get a paginated list of detected secrets. Filter results by workspace, resolution status (false positive, revoked, or an accepted risk), secret type, or whether secrets are resolved.
- Get all the types of secrets.
- Get the list of locations for a specific secret and where it’s exposed in Postman, such as requests, examples, or APIs. You’ll also get a link to the Postman app for the resource so you can validate the risk.
- Given a specific secret, you can use the Update detected secret resolution status endpoint to resolve it.
Streamline resolution management with the Postman API
To help you get started, we’ve built a command-line utility example that uses the Postman API to programmatically list and resolve exposed secrets. You can find the source code in our secret-scanner-postman-api GitHub repo.
How does it work?
We’ve created a small Postman API wrapper that enables users to list and resolve secrets in a workspace (check the apiClient.js file for details). We also created a JavaScript file that you can run as a shell script.
You’ll need a valid Postman API key saved as the POSTMAN_API_KEY environment variable to run the following command:
export POSTMAN_API_KEY=PMAK_your_key
The postmanSecretScannerAPI.js command receives the following arguments:
./postmanSecretScannerAPI.js --workspace <workspaceId> --operation <operation> [--secretIds <secretIds>] [--status <status>] [--limit <limit=10>]
In this command:
workspaceIdis the ID of the workspace you want to review.operationis the operation to perform:listorresolve. For theresolveoperation, thesecretIdsandstatusarguments are required.secretIdsis a comma-separated list of the secret IDs to resolve if you are performing aresolveoperation.statusis the status to set for the secrets when performing theresolveoperation:FALSE_POSITIVE,REVOKED, orACCEPTED_RISK.limitis an optional argument that defines the maximum number of secrets to return in the table. Note that each secret can be detected in several locations. For each secret displayed, an additional API request is performed. This value defaults to10.
Find and resolve your exposed secrets in Postman
To find all secrets exposed in a workspace and their location, perform a list operation:
./postmanSecretScannerAPI.js --workspaceId {workspaceId} --operation list --limit 5
The command’s output resembles the following:
Total secrets unresolved in workspace: 11
Showing a table of the first 5 secrets
+--------------+------------------------+----------+-------------+------------------+
| Secret ID | Secret Type | Location | Occurrences | Resource Deleted |
+--------------+------------------------+----------+-------------+------------------+
| NjYyMjcyNw== | Authorization Password | request | 1 | false |
| NjYyMjcyNw== | Authorization Password | request | 1 | false |
| NjcxNTY2Ng== | Authorization Secret | request | 0 | true |
| ODIzNTkzMw== | Postman API Key | request | 1 | false |
| ODIzNTkzMw== | Postman API Key | request | 0 | false |
| NjYyMzU4OA== | Postman Collection Key | example | 0 | true |
| NjYyMzU4OA== | Postman Collection Key | example | 0 | true |
| NjYxMDk1Mg== | AWS Access Key | request | 0 | false |
| NjYxMDk1Mg== | AWS Access Key | request | 1 | false |
+--------------+------------------------+----------+-------------+------------------+
In this response, the Secret Type column tells you the type of secret that’s exposed and the Occurrences column lists the number of times that secret was found in the workspace. A value of 0 indicates that the secret previously existed in the workspace and can be easily resolved.
The location column values are the Postman elements containing the secret, such as requests, examples, and APIs. The output may also return more than one row for an element. This is because secrets can be in multiple locations. For example, the NjYyMjcyNw== secret ID was found in two different requests in the workspace.
If the Resource Deleted column returns true, then it’s safe to resolve the secret.
Note that for each secret, the system performs additional API requests to get the secret locations. Take this into account when calling the command and use the limit argument to reduce the number of requests because the Postman API has rate and usage limits.
Resolving secrets
Once you’ve got a list of the secrets exposed in the workspace, use the resolve operation to resolve their status:
./postmanSecretScannerAPI.js --workspaceId 51679e9a-b94f-4ac1-b1c1-7a8d035436cf --operation resolve --secretIds NjcxNTY2Ng==,NjYyMzU4OA== --status ACCEPTED_RISK
The command returns an output that resembles the following:
Secrets resolved: 2
Note that the system performs an API call for each secret ID passed in the secretIds list. You should consider this when you call this command. We recommend using the limit argument to reduce the number of requests.
Powerful tools for managing secrets
With Postman API’s Secret Scanner endpoints, you can quickly and efficiently manage your detected secrets without the hassle of manual processes. Integrate the Secret Scanner endpoints into your workflow using our custom-built CLI utility to swiftly resolve multiple exposed secrets. With these powerful tools at your disposal, managing exposed secrets has never been simpler.