# 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**: The target Jira project for tickets.
   * **Work Type (Issue Type)**: Select from issue types available in your Jira project. Interlynk queries your Jira project's create metadata and only renders issue types that project actually supports. Select **InterlynkVuln** for full VEX field support (requires provisioning to be completed first).
   * **Epic**: Link new tickets to an existing Jira Epic (optional). The dropdown lists Epics in the selected project.
   * **Default Assignee**: The Jira user who receives new tickets (optional).
   * **Default Reporter**: The Jira user listed as reporter (optional, required by some Jira projects).
   * **Components**: Route tickets to specific Jira Components within the project (optional). The field appears only when the selected project and issue type support a Components field.
   * **Bi-directional Sync**: Toggle two-way synchronization between Jira and Interlynk.

### Step 5: Test Your Integration

After configuring per-product settings, create a test ticket to verify the connection and field mapping before enabling automatic ticket creation:

1. In the per-product Jira settings, ensure **Project** and **Work Type** are selected.
2. Click **Create Test Ticket**.
3. A sample ticket is created in Jira using the current configuration. Verify it appears in the correct project with the expected fields populated.
4. Delete the test ticket from Jira after verification.

***

## 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.

### Ticket Title Format

Auto-created tickets use the format:

```
Policy Violation: <product-name> (<environment>): <vulnerability-id> in <package-name>
```

This makes it immediately clear which product and environment the violation came from without opening the ticket.

### 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)       | Format: `Policy Violation: <product> (<env>): <vuln-id> in <package>` |
| Description      | Description           | Includes component details, severity level, and CVSS score            |
| Severity         | Priority              | Mapped via priority mapping (see below)                               |
| Affected package | Labels / Custom field | Configurable                                                          |
| SBOM version     | Affected Versions     | Automatically included from SBOM metadata                             |
| Components       | Jira Components       | Routes to the Jira component(s) configured in product settings        |

### 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 — also pushed to Jira when updated in Interlynk                      |
| 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)           |

{% hint style="info" %}
Bidirectional sync works across all configured Jira issue types, not just **InterlynkVuln**. If you use standard issue types (task, bug, story), VEX field sync operates on whichever custom fields those issue types expose.
{% endhint %}

***

## Organization-Level Jira Defaults

Set default Jira configuration for all products in the organization, so new products inherit sensible settings without manual per-product configuration:

1. Navigate to **Settings > Organization > Environment Defaults**.
2. Find the **Jira Defaults** section.
3. Configure defaults for: Project, Work Type (Issue Type), Epic, Assignee, Reporter, and Components.
4. Choose whether to apply defaults to **all existing projects** or only **future projects**.

Per-product settings override organization defaults. If a product has no Jira configuration set, it inherits the organization defaults.

***

## 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            |

### Permission Health Checks

Interlynk proactively checks the Jira user's permissions and reports any that are missing, so integration failures surface early rather than during ticket creation or sync.

***

## 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                                |
| Components field not appearing in settings | Selected project or issue type does not have a Components field | Verify the Jira project has a Components field enabled for the chosen issue type           |
| Test ticket creation disabled              | No project or issue type selected                               | Select both Project and Work Type before using Create Test Ticket                          |
| Duplicate Jira connection                  | Attempting to add a second Jira connection for the same org     | Only one Jira connection is allowed per organization; edit the existing connection instead |

***

## 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.interlynk.io/administration/jira.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.