## Why It Matters

The people who triage a vulnerability report are almost never the people who fix it. Triage happens in Kit; the fix happens on an engineering board. Without a link between the two, someone copy-pastes the report into Jira by hand — and from that moment the two systems drift. The ticket says "In Review" while the report says "Validated", nobody can answer "is this actually fixed?", and the researcher waits.

Connecting Jira closes that loop. One click on a report creates the engineering ticket, and the link between them is a real record Kit maintains — not a URL somebody pasted into a comment.

It also solves the quieter problem: hand-copying tends to paste **everything**, including the reproduction steps and the researcher's email, into a project whose real audience nobody has audited. Kit's integration pushes a deliberate stub instead.

## What You Need

- Kit account with the **VDP Add-on** enabled
- A Jira Cloud site (Jira Data Center and Jira Server are not supported)
- An Atlassian account that can see the target project
- Module-admin rights in Kit — connecting a tracker is an organization-level decision

> [!NOTE]
> Kit uses **OAuth 2.0 (3LO)**. There is no API-token field, and that is not an oversight: Atlassian's security requirements prohibit apps from collecting user API tokens. You will sign in to Atlassian and grant access.

## Setup

### 1. Connect your Atlassian account

1. Go to [**VDP > Settings > Issue tracker**](/csirt/settings/tracker_connection)
2. Click **Connect Jira**
3. Sign in to Atlassian and approve the requested access
4. Pick the Jira site to use, if your Atlassian account has more than one

The grant belongs to the person who authorized it. Kit records who that was, because when that person leaves the organization the connection stops working and you need to know whose access to renew.

> [!WARNING]
> Some Atlassian organizations require an admin to approve third-party apps. If approval is required, the connect step fails with a message from Atlassian rather than a Kit error — forward the request to whoever administers your Atlassian org.

### 2. Choose a project and issue type

1. On the settings page, click **Choose project**
2. Pick the project that should receive vulnerability work
3. Pick the issue type new tickets are created with (usually Bug or Task)

Kit reads the project type while you do this. If it is a **Jira Service Management** project, milestone comments are switched off by default — JSM forces comments created through the platform API to be public, which would expose them to your external service-desk requesters.

Kit also reads the priority names your chosen project and issue type accept, and maps report severities onto them (critical → Highest, high → High, and so on). Two cases are worth knowing, and the settings page tells you when either applies:

- **Your project uses its own priority names**, or runs in a language other than English. Kit will not invent a priority it cannot match, so those reports are filed with whatever default priority the project applies. The severity is always written into the ticket description regardless.
- **Your project has no priority field** on its create screen, which is common in team-managed projects. Kit then sends no priority at all.

To control the mapping yourself, set a `priority_map` override on the connection — there is no screen for it yet.

### 3. Confirm it works

Click **Test connection**. Kit makes an authenticated round trip to your site and reports the result.

## Pushing a Report

Open any report. In the right-hand column you will find an **Issue tracker** card.

1. Click **Create issue**
2. Read the panel showing what is sent and what stays in Kit
3. Click **Create issue**

The card shows a spinner while the ticket is being created, then the issue key, its status, and a link that opens Jira in a new tab.

Any team member who can see the report can do this — it is routine triage, the same permission level as attaching a link. Configuring the connection is the admin-only part.

## What Leaves Kit

This is the part worth reading carefully. By default a pushed ticket is a **stub**: enough for an engineer to schedule the work, and no more.

| Sent to Jira | Stays in Kit |
|---|---|
| Report title and its Kit reference | The vulnerability description |
| Severity and CVSS score | Reproduction steps |
| Vulnerability type | The affected endpoint |
| Affected product area | Proof-of-concept files and screenshots |
| Remediation due date | The researcher's name, email and payout details |
| A link back to the report in Kit | Internal notes and the conversation thread |

The reasoning is not caution for its own sake. Jira's effective audience is unknowable from Kit: org-wide project permissions, marketplace apps holding issue-read scope, CSV exports, and backups that outlive the ticket. The fields Kit withholds are the same ones it encrypts at rest, so pushing them would move your most protected data into your least controlled system.

**Researcher identity and bounty amounts have no toggle at all.** The absence of the option is the guarantee.

### Sharing full details anyway

Some teams do want the description in the ticket. That requires **two** independent gates:

1. An admin turns on **Allow full vulnerability details** in *VDP > Settings > Issue tracker*
2. The person pushing the report ticks the box for that specific ticket

Both default to off. With the program-level setting off, the checkboxes do not even render — and a hand-crafted request cannot bypass them, because Kit re-checks the program setting when it builds the payload.

When report text is included it is placed in a code block, so Jira renders it exactly as the researcher wrote it instead of interpreting it as markup.

> [!TIP]
> Leave it off. The ticket links back to Kit, and the engineer who needs the repro steps can open the report — under your access controls, with the view recorded.

## Remediation Status

The card shows the ticket's own status label as your board words it ("In Review", "Ready for QA"), because that is what the engineer sees. Kit maps it internally to one of five states — Not started, In progress, Fixed, Won't fix, Unknown — using Jira's fixed status *categories* rather than status names, so no per-project workflow mapping is required.

**Kit never resolves a report because Jira says Done.** "Done" on an engineering board routinely means "merged, not deployed", and resolving a report has consequences the person dragging a card cannot be assumed to intend: the researcher is notified, the bounty flow opens, and disclosure timers move. Kit surfaces the finished ticket and leaves the decision with a human.

## Unlinking and Retries

- **Unlink** removes the link in Kit only. The ticket stays in Jira, where it may already carry an engineer's comments and a fix branch — Kit is not the system of record over there.
- **Retry** re-runs a push that failed. It is safe to press twice: Kit tags each ticket with a unique key and looks for that tag before creating anything, so a request that timed out after Jira had already created the ticket adopts the existing one instead of making a second.
- **Disconnecting** the integration removes Kit's copy of the grant and its tracking rows. Every ticket you already created stays in Jira.

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| "Jira access was revoked" | The grant was revoked in Atlassian, or the authorizing user was deactivated | Reconnect from the settings page; a different admin can re-authorize |
| "That project has no usable issue type" | The project only exposes sub-task types | Pick a different project, or add a standard issue type in Jira |
| The ticket was rejected on a field | A required custom field the stub does not fill in | Check the error shown on the card, then adjust the project's field configuration so the field is optional on create |
| No **Create issue** button appears | No tracker is connected, or the VDP Add-on is not active | Connect one under *VDP > Settings > Issue tracker* |

## Quick Checklist

- [ ] VDP Add-on active on the account
- [ ] Atlassian account connected, and you know who authorized it
- [ ] Target project and issue type chosen
- [ ] Test connection passes
- [ ] Checked the settings page for a priority-mapping notice on your chosen project
- [ ] Decided, deliberately, whether full vulnerability details may be shared
- [ ] If this is a Jira Service Management project, confirmed milestone comments are off