# Jira

The Jira integration provides enterprise-grade, bidirectional vulnerability management between Interlynk and Jira. It supports automatic ticket creation, VEX field synchronization, and status tracking across both platforms.

***

## Purpose

* Create Jira tickets for vulnerabilities discovered in SBOMs — manually or automatically via policy violations.
* Synchronize VEX (Vulnerability Exploitability eXchange) status bidirectionally between Interlynk and Jira.
* Map vulnerability severity to Jira priority and custom fields.
* Track remediation progress across both platforms.

***

## Setup Steps

### Step 1: Connect Jira

1. Navigate to **Settings > Organization > Integrations**.
2. Click **Jira**.
3. Enter the following:
   * **Jira Host URL**: Your Jira instance URL (e.g., `https://yourcompany.atlassian.net`).
   * **User Email**: The email of the Jira user account that Interlynk will use.
   * **API Token**: A Jira API token generated for the user account.
4. Click **Verify** to test the connection.
5. On success, the verification panel displays: account name, account ID, account type, Jira URL, version, deployment type, and server title.
6. Click **Save**.

### Step 2: Provision Vulnerability Management

After connecting Jira, set up the vulnerability management configuration to enable custom field mapping and bidirectional sync.

1. Navigate to **Settings > Organization > Integrations > Jira Vulnerability Management**.
2. Click **Initialize**.
3. Interlynk provisions the following resources in your Jira instance (8-step process):
   1. Custom issue type (`InterlynkVuln`)
   2. Issue type scheme
   3. Custom fields (11 VEX-related fields)
   4. Workflow
   5. Workflow scheme
   6. Screen with fields
   7. Screen scheme
   8. Issue type screen scheme
4. Wait for provisioning to complete. Status is displayed as **In Progress**, **Completed**, or **Failed** (with the specific step that failed).

### Step 3: Associate Jira Projects

After provisioning, associate Jira projects with the vulnerability management configuration:

1. Select the Jira **project** from the dropdown.
2. The issue type scheme and screen scheme are applied to the project.
3. Repeat for each project that should receive vulnerability tickets.

### Step 4: Configure Per-Product Settings

For each Interlynk product that should create Jira tickets:

1. Navigate to **Settings > Organization > Ticketing**.
2. Locate the product and expand its settings.
3. Configure:
   * **Jira Project Key**: The target project for tickets.
   * **Issue Type**: Select from available types (task, story, bug, or InterlynkVuln).
   * **Default Assignee**: The Jira user who receives new tickets (optional).
   * **Default Reporter**: The Jira user listed as reporter (optional, required by some Jira projects).
   * **Epic Link**: Associate tickets with a Jira epic (optional).
   * **Enable Sync**: Toggle bidirectional synchronization on/off.

***

## Ticket Creation

### Manual Ticket Creation

Create Jira tickets for individual or multiple vulnerabilities:

1. Navigate to a product's vulnerability view.
2. Select one or more vulnerabilities.
3. Click **Create Jira Issue**.
4. The issue creation modal displays:
   * Pre-populated fields based on the vulnerability (summary, description, severity, affected package).
   * Standard fields: project, issue type, assignee, reporter, priority, labels.
   * VEX fields: status, justification, action response, impact statement, notes, action statement.
5. Click **Create** to submit.

**Bulk creation** supports up to 50 issues per request.

### Automatic Ticket Creation

Automatic ticket creation is driven by **policy violations**:

1. Define a policy with vulnerability conditions and enable **Create Ticket** on the policy.
2. When a policy scan produces violations, the `BulkAutoTicketCreationJob` processes them.
3. Tickets are created in batches of 50 per Jira project.
4. Each violation is linked to its Jira ticket. Duplicate tickets are not created for existing links.

***

## Field Mapping

### Standard Fields

| Interlynk Field  | Jira Field            | Notes                                        |
| ---------------- | --------------------- | -------------------------------------------- |
| Vulnerability ID | Summary (title)       | Auto-generated                               |
| Description      | Description           | Includes component and vulnerability details |
| Severity         | Priority              | Mapped via priority mapping (see below)      |
| Affected package | Labels / Custom field | Configurable                                 |
| SBOM version     | Affected Versions     | Extracted from SBOM metadata                 |

### VEX Custom Fields

The following VEX fields are synced bidirectionally as Jira custom fields:

| Custom Field             | Type   | Description                                                                                         |
| ------------------------ | ------ | --------------------------------------------------------------------------------------------------- |
| Vulnerability ID         | Text   | CVE or vulnerability identifier                                                                     |
| Affected Package         | Text   | Package name                                                                                        |
| Affected Package Version | Text   | Package version                                                                                     |
| VEX Status               | Select | `affected`, `not_affected`, `fixed`, `in_triage`                                                    |
| VEX Justification        | Select | `code_not_reachable`, `code_not_present`, `requires_configuration`, `requires_dependency`, and more |
| VEX Action Response      | Select | `can_not_fix`, `will_not_fix`, `update`, `rollback`, `workaround_available`                         |
| VEX Impact Statement     | Text   | Freeform impact description                                                                         |
| VEX Internal Notes       | Text   | Internal team notes                                                                                 |
| VEX Action Statement     | Text   | Remediation action description                                                                      |
| CVSS Score               | Number | CVSS vulnerability score                                                                            |
| Severity                 | Select | `critical`, `high`, `medium`, `low`                                                                 |
| EPSS Score               | Number | Exploit Prediction Scoring System score                                                             |
| Fix Available            | Select | Whether a fix is available                                                                          |
| Interlynk SBOM Link      | URL    | Link back to the SBOM in Interlynk                                                                  |

### Severity to Priority Mapping

| Interlynk Severity | Jira Priority |
| ------------------ | ------------- |
| Critical           | Highest       |
| High               | High          |
| Medium             | Medium        |
| Low                | Low           |
| Unknown            | Lowest        |

***

## Bidirectional Synchronization

### Jira to Interlynk (Pull Sync)

Interlynk polls Jira on a schedule to pull updates from Jira tickets back into vulnerability records.

**What syncs from Jira to Interlynk:**

* VEX Status changes
* VEX Justification updates
* VEX Action Response
* Impact and action statements
* Internal notes

**How it works:**

1. The `JiraVulnSyncJob` runs on a schedule for organizations with the feature enabled.
2. The job fetches Jira tickets in batches of 50 using JQL queries.
3. For each ticket, the sync handler compares field values between Jira and Interlynk.
4. Changed fields are applied to the corresponding Interlynk vulnerability record.
5. A `ComponentVulnLog` entry is created for audit purposes.

**Manual sync:** You can trigger an immediate sync from **Settings > Organization > Ticketing** by clicking the sync button.

### Interlynk to Jira (Push Sync)

When VEX dispositions are updated in Interlynk, changes are pushed to the corresponding Jira ticket.

**What syncs from Interlynk to Jira:**

* VEX Status
* VEX Justification
* VEX Action Response
* Impact and action statements
* A comment is added to the Jira ticket documenting the change

**How it works:**

1. When a vulnerability disposition is updated in Interlynk, the `JiraVexPushJob` is triggered.
2. The reverse field mapper converts Interlynk values to Jira custom field option IDs.
3. The Jira ticket is updated via the Jira REST API.
4. A comment is added to the ticket for audit trail.

### Sync Configuration

| Setting                   | Description                                       |
| ------------------------- | ------------------------------------------------- |
| Enable Sync (per product) | Toggles bidirectional sync for a specific product |
| Last Synced At            | Timestamp of the most recent sync                 |
| Last Sync Status          | Success or failure (with error details)           |

***

## Required Permissions

### Jira User Permissions

The Jira user account used for the integration requires:

| Permission             | Purpose                                                         |
| ---------------------- | --------------------------------------------------------------- |
| Browse Projects        | Read project metadata and issue types                           |
| Create Issues          | Create vulnerability tickets                                    |
| Edit Issues            | Update ticket fields during sync                                |
| Add Comments           | Add sync comments to tickets                                    |
| Manage Schemes (Admin) | Required for provisioning custom fields, workflows, and schemes |

### Interlynk Permissions

| Permission           | Purpose                                |
| -------------------- | -------------------------------------- |
| `view_connections`   | View Jira integration settings         |
| `edit_connections`   | Configure Jira connection and settings |
| `delete_connections` | Remove the Jira integration            |

***

## Security Notes

* Jira API tokens are encrypted at rest.
* The integration uses Jira REST API v3 — no webhooks are required. All synchronization is poll-based.
* Use a **dedicated Jira service account** rather than a personal account to avoid disruption if a team member leaves.
* Grant the Jira service account only the permissions listed above.
* The provisioning step creates resources in your Jira instance — coordinate with your Jira admin before initializing.

***

## Troubleshooting

| Issue                             | Cause                                                   | Resolution                                                                         |
| --------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Connection verification fails     | Invalid URL, email, or API token                        | Re-check the Jira Host URL, email, and generate a new API token                    |
| Provisioning fails at a step      | Insufficient Jira admin permissions                     | Ensure the Jira user has scheme management permissions                             |
| Tickets not created automatically | Policy does not have "Create Ticket" enabled            | Enable the flag on the policy and ensure the product has a Jira project configured |
| Sync not updating Interlynk       | Sync disabled for the product                           | Enable sync in the ticketing settings for the product                              |
| VEX fields missing on Jira ticket | Provisioning not completed                              | Complete the provisioning process or re-initialize                                 |
| Duplicate tickets                 | Multiple policies triggering for the same vulnerability | Consolidate policies or use exclusion rules                                        |
| Sync shows errors                 | Jira API rate limits or network issues                  | Check the `last_sync_status` for error details; retry later                        |

***

## Common Misconfigurations

| Issue                                 | Symptom                                         | Fix                                                             |
| ------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------- |
| Personal Jira account used            | Integration breaks when employee leaves         | Use a dedicated service account                                 |
| Jira project not associated           | Tickets fail to create                          | Associate the Jira project with vulnerability management config |
| Issue type not configured per product | Default issue type may not have required fields | Configure the correct issue type in ticketing settings          |
| Sync enabled but no project key set   | Sync job runs but finds nothing to sync         | Set the Jira project key for each product                       |

***

## Recommended Best Practices

* Use a **dedicated Jira service account** with scoped permissions.
* Enable **bidirectional sync** only for products actively being triaged — unnecessary sync adds API load.
* Use the **InterlynkVuln** issue type (created during provisioning) for full VEX field support.
* Configure **automatic ticket creation** via policies to reduce manual effort for high-severity vulnerabilities.
* Review **sync status** regularly in the ticketing settings to catch failed syncs early.
* Coordinate with your Jira admin before provisioning to avoid conflicts with existing schemes.