API key hygiene

API keys are among the secrets that OWASP addresses under secrets management. OWASP describes a secret's lifecycle in terms of creation, rotation, revocation, and expiration. It states that a newly created secret should have sufficient cryptographic strength for its intended purpose and be defined with the minimum privileges needed for the task.

Limiting permissions and access

According to OWASP, a user authorized to read or modify a secret, and the system that user employs to access it, are points where the secret could be exposed. OWASP recommends defining granular access permissions for every object and component in the secret management system and applying the Least Privilege principle.

GitHub says to select only the necessary permissions or scopes when creating a personal access token. The token's expiration date should also be limited to the period needed. When creating a GitHub App, the application should be granted only the minimum necessary permissions; the same applies to a workflow using GITHUB_TOKEN in GitHub Actions.

According to GitHub, a token is limited to the resources its owner can access and act on. The scopes and permissions granted to the token further restrict that access. A token does not grant the user additional access permissions they would not normally have.

GitHub says not to share a personal access token with other people. If a team needs to share credentials, they can be kept in a secure shared system. For a GitHub Actions workflow that needs API access, credentials can be stored in an encrypted secret and used by the workflow.

Keeping keys separate from code

GitHub says not to hardcode tokens, keys, and application secrets in code. It states that unencrypted tokens and keys should not be pushed to any repository, including a private repository. GitHub Actions secrets and Codespaces secrets are among the options GitHub offers for this purpose.

GitHub also asks that personal access tokens not be passed as plain text on the command line. Credentials should not be shared through unencrypted messaging or email systems. OWASP also states that secrets should not be transmitted as plain text.

According to GitHub, when using a personal access token in a script, the token can be stored as a GitHub Actions secret and the script run through GitHub Actions. The token can also be stored as a Codespaces secret and the script run in Codespaces. GitHub says that if these options are not possible, credentials can be kept in a .env file. This file should be encrypted and should not be pushed to any repository.

In a container environment, OWASP explains that a file containing a secret can be made available to the application as a mounted volume. The volume should be mounted by the orchestrator when needed, rather than placed in the container definition. Placing it in the container definition can cause the secret to be exposed along with that definition.

According to OWASP, environment variables are generally accessible to all processes. They can also appear in logs or system dumps. OWASP does not recommend using environment variables unless other methods are not possible. It also states that secrets should not be hardcoded in Docker ENV or ARG commands.

In another method described by OWASP, a sidecar container retrieves the secret from a secret manager and writes it to a shared volume. The application container reads the secret from that volume. The sidecar can refresh the secret at regular intervals. OWASP states that this arrangement separates the application from the details of the secret management solution.

Expiration, rotation, and revocation

OWASP recommends creating secrets that expire after a specified period when possible. Expiration can be enforced by the system using the secret. An expiration time set in the secret management system can also trigger the rotation process. OWASP says applications should verify that a secret is still active before relying on it.

When using dynamic secrets, OWASP recommends setting a short lease period when possible and revoking credentials that are no longer needed. Restarting an application does not automatically revoke stolen credentials. Those credentials can be used until they expire or are revoked by the service they are associated with.

OWASP states that errors can occur when rotating static keys manually. It recommends automating the rotation process or at least carrying it out with sufficient technical support. The methods it describes include phased rotation and using the new key for Write operations and the old key for Read operations.

For CI/CD, OWASP describes an approach in which the pipeline deploys the application using a platform identity. The deployed service retrieves its own secrets directly from the secret manager at runtime. This way, the application's runtime secrets do not pass through the CI/CD pipeline.

According to OWASP, when a pipeline obtains dynamic credentials from a secret manager, the runner stopping or the build completing does not automatically revoke those credentials. The credentials expire at the end of the configured lease period or are explicitly revoked when no longer needed.

Detecting leaks

GitHub secret scanning scans Git history across all branches of a repository for hardcoded credentials. It covers API keys, passwords, tokens, and other known secret types. GitHub also rescans repositories periodically when secret types are added.

GitHub's automatic scanning is not limited to code. Issue and pull request titles, descriptions, and comments; GitHub Discussions content; wikis; and secret gists are also among the areas scanned. When a credential leak is detected in a repository, GitHub creates an alert in the Security and quality tab with details about the exposed information.

GitHub explains that secret scanning coverage can be extended with generic patterns and custom patterns. Generic patterns can cover private keys, connection strings, and general API keys that are not tied to a specific service provider. Custom patterns allow regular expressions to be defined to detect organization-specific secrets that default patterns do not cover.

According to GitHub, validity checks help determine the order of response by verifying whether a detected secret is still active. When this feature is enabled, secret scanning can contact the issuing service to determine whether the credential has been revoked.

GitHub states that some secrets detected by secret scanning are handled through partnerships with service providers. When such a secret is detected, a notification is sent to the provider. The provider can take action, such as revoking the credential. These secrets are not shown in repository alerts.

Responding to an exposed key

OWASP says exposed keys should be revoked immediately. Quickly creating and implementing a new secret is also part of the response process. OWASP recommends using an automated process to support repeatability and reduce implementation errors when creating and implementing the new secret.

GitHub says to create a new credential for a leaked token or other credential. The old credential is then replaced with the new one everywhere it is stored or used, and the old compromised credential is deleted. The process GitHub describes covers all places where the old credential is used and stored.

OWASP asks that revoked or rotated secrets be immediately removed from the system where they were exposed. This includes secrets found in code or logs. It states that a process should be in place to preserve log integrity when removing a secret from a log.

A secret can also be removed from Git history. However, GitHub says that if the credential has already been revoked, removing it from history can be time-consuming and unnecessary in many cases. OWASP states that rewriting history can break other links to the relevant commit.

If another user's personal access token has been exposed on GitHub or elsewhere, GitHub states that a revocation request can be submitted through the REST API.

Records and limitations

OWASP asks that secret management audit records capture who requested a secret and for which system and role, whether the request was accepted, and when and by whom or what the secret was used. Expiration, attempts to reuse an expired secret, authentication and authorization failures, and management operations are also among the events to be recorded.

According to OWASP, audit records should be resistant to attempts to modify or delete them. The timestamps in the records need to be accurate. OWASP says to synchronize time across the infrastructure and monitor clock drift and manual clock changes.

OWASP also asks that metadata about a secret be kept, including its intended purpose, type, who created it, and who uses it. For a manually rotated secret, this information also includes the rotation time and the person to contact if a problem occurs.

Dynamic secrets are not suitable for every service. OWASP states that the service being connected to may not support creating temporary roles or credentials. In addition, creating dynamic secrets often requires a long-lived static secret. According to OWASP, OpenID Connect also does not replace other application secrets such as API keys.