Best practices for rotating FOSSA access tokens

Overview

This document provides best practices for managing and rotating access tokens in FOSSA. FOSSA offers two types of access tokens:

1. Push-Only Token: Used exclusively to push analysis results to FOSSA.
2. Full Access Token: Provides full access to FOSSA APIs.

To ensure security and proper access management, it is crucial to create tokens with minimal permissions and rotate them regularly.

Creating Service Accounts

Create a Service Account: It is recommended to create a service account within your organization to handle the generation and rotation of access tokens. This ensures that tokens are not tied to individual user accounts, which may change or be deactivated over time.

Minimal Permissions: Assign minimal necessary permissions to the service account to limit potential security risks. Assign carefully the permissions for this service account based on the current permissions, which can be found here . For example, you may want to create a service account with a minimal role that has the following permissions:

1. Create projects
2. Edit projects
3. View projects

With these permissions in mind, you can then create a push-only access token that can only be used for FOSSA analysis via the FOSSA CLI. You can similarly create a full access token, depending on the information the service account needs to access (e.g. should it have the ability to access and edit policies?)

Generating Access Tokens

Generating access tokens are pretty straightforward and instructions to do so can be found here .

Push-Only Token

1. Purpose: Use this token to push analysis results to FOSSA.

Full Access Token

1. Purpose: Use this token for accessing FOSSA APIs.

Token Rotation

Regular token rotation is critical for maintaining security. The recommended rotation interval is between 80 to 180 days, depending on your organization's security policies.

Rotation Procedure

1. Schedule Regular Rotations: Implement a schedule for rotating tokens, ideally integrated with your organization's existing security practices.
2. Generate New Token:
   • Follow the steps in the "Generating Access Tokens" section to create a new token.
3. Update Systems:
   • Update all systems and applications using the old token with the new token.
   • Ensure that the old token is not used beyond its expiration.
4. Revoke Old Token:
   • Once the new token is confirmed to be working, revoke the old token to prevent any unauthorized access. This bash script creates a new FOSSA API key and deletes the old API key.

Security Considerations

• Secure Storage: Always store tokens in a secure manner, such as using a secrets management system like AWS Secrets Manager, HashiCorp Vault, or Azure Key Vault.
• Minimal Permissions: Apply the principle of least privilege when generating tokens to limit potential security impacts if a token is compromised.
• Monitoring: Monitor the usage of tokens and set up alerts for any suspicious activity.

Additional Resources

For detailed information on API token management, refer to the FOSSA API Reference Documentation.