Jira Integration

Experimental Feature

The Jira integration is an experimental feature and may undergo changes in future releases.

Overview

This guide walks you through setting up the Jira integration for CVEScan. The process involves:

Creating an Atlassian OAuth 2.0 (3LO) integration.
Configuring CVEScan API.
Understanding the data storage & security implications.

Configuration

Step 1: Create an Atlassian OAuth 2.0 (3LO) Integration

To use the Jira integration, create an Atlassian OAuth 2.0 (3LO) integration in the Atlassian Developer Console and configure it with the appropriate callback URL and permissions.

IT Department Responsibility

We strongly recommend that your IT department manages this integration.

Setup Steps

Create an OAuth 2.0 (3LO) app: Navigate to the Atlassian Developer Console and create an OAuth 2.0 (3LO) app.
Add required permissions: In the Permissions section, add Jira API and configure it with the following classic scopes:
- read:jira-work
- write:jira-work
Configure OAuth callback: In the Authorization section, add an OAuth 2.0 (3LO) configuration and set the callback URL to the URL of the user profile page in CVEScan WebUI.

To find this URL: Log in to CVEScan WebUI, expand the sidebar (if closed), and click on your account information at the bottom of the sidebar.

Note

The user profile page is accessible by any authenticated user, and its URL is the same for all users.
Enable distribution: In the Distribution section, switch the distribution status to "Sharing" to make the app available to other users.

This step requires:
- Filling in the "Vendor name" field.
- Providing a "Privacy policy URL".
- Answering whether the app stores personal data. CVEScan's Jira integration does not store information classified as personal data. For further details, see Data Storage and Encryption. However, always verify the current Atlassian terms of service to ensure continued compliance.
Retrieve credentials: In the Settings section, copy the Client ID and Secret values. You will need these for the next step.

Step 2: Configure CVEScan API Environment Variables

Set the following environment variables for the CVEScan API:

Required Variables

CVESCAN_JIRA_AUTH_CLIENT_ID
The OAuth Client ID from your Atlassian app.
CVESCAN_JIRA_AUTH_CLIENT_SECRET
The OAuth Client Secret from your Atlassian app.
CVESCAN_ACTIVE_ENCRYPTION_KEY
The encryption key used to encrypt Jira credentials.
See Data Storage and Encryption for details.

Optional Variables

CVESCAN_INACTIVE_ENCRYPTION_KEYS
Semicolon-separated list of inactive encryption keys for key rotation support.
See Data Storage and Encryption for details.

Data Storage and Encryption

To enable the Jira integration, CVEScan stores sensitive user credentials in the database. This section explains what data is stored, how it is encrypted, and the security implications.

What Data is Stored

For each user who connects their Jira account, CVEScan stores the following information in encrypted form:

Jira Instance URL: The URL of the user's Atlassian cloud instance (e.g., https://your-domain.atlassian.net).
Cloud ID: The unique identifier of the Atlassian cloud instance.
Access Token: A bearer token used to make API requests on behalf of the user (expires after a short period, typically 1 hour).
Refresh Token: A long-lived token used to obtain new access tokens (expires after 90 days).

This data enables seamless integration with Jira without requiring users to re-authenticate for every action.

Encryption at Rest

All the data listed above is encrypted at rest using AES-256-GCM (Advanced Encryption Standard with Galois/Counter Mode), which provides both confidentiality and authenticity.

Understanding Active vs. Inactive Keys

The encryption module distinguishes between two types of keys:

Active Key: Used to encrypt all new data. Only one active key can be configured at a time. When CVEScan encrypts new data, it always uses the active key.
Inactive Keys: Used only for decrypting data that was previously encrypted with older keys. These keys are no longer used for encryption but remain available to maintain access to existing encrypted data.

This two-tier key system enables progressive key rotation without data migration. Old encrypted values remain decryptable while new values use the new active key.

Important: No Automatic Re-encryption

Updating the active key does not trigger automatic re-encryption of existing data. You must always add the previous active key to the inactive keys list to maintain access to data encrypted with it. Only remove an inactive key when you are certain no data in the database still uses it.

Encryption Key Configuration

CVESCAN_ACTIVE_ENCRYPTION_KEY

Format: uuid:base64string

Important: Encryption Key Generation

It is critical that encryption keys are generated using a cryptographically strong pseudorandom number generator (CSPRNG). Weak or predictable random number generators can lead to keys that are vulnerable to brute-force attacks or pattern analysis, compromising the security of all encrypted data.

CVESCAN_INACTIVE_ENCRYPTION_KEYS (Optional)

Format: uuid1:base64string1;uuid2:base64string2 (semicolon-separated)

Only required when performing key rotation to maintain access to data encrypted with previous keys.

Important Security Information

Environment Variables

The current implementation only supports passing configuration via environment variables. This has security implications, as environment variables may be logged or exposed in process listings. Depending on your deployment method and environment, consider implementing more secure alternatives.

Data Access

Even if someone has direct access to the data stored in the database, they will not be able to exploit the credentials without having access to the encryption keys.

Encryption Key Management

Generate encryption keys using a secure and cryptographically random method.
Store encryption keys securely and restrict access to authorized personnel only.