Jira
Written By Dan Crawford
Last updated 6 days ago
PGP's Jira integration enables automatic and manual creation of vulnerability alerts as Jira tickets, streamlining your security workflow. This guide will walk you through the setup process, which typically takes 5-10 minutes to complete.
Prerequisites
Before beginning the integration setup, ensure you have:
- Access to create API tokens in your Atlassian account
- Designated Jira project (or projects) for security vulnerabilities
PGP Configuration
To begin setting up your Jira integration, first access your organization's settings. Log into your PGP account and locate the Settings section at the bottom right of the page:
Once you're on the Settings page, you'll find the Notifications Settings tab. This is where you'll configure how PGP communicates with external systems like Jira. Look for the "Add Notification" button and click to see the available integration options. Among these options, you'll find the Jira tile - select this to begin configuring your integration.
Jira Configuration
Jira configuration is a two-step process. The first step is authentication, and the second step is tailoring the messaging to your needs and Jira setup. Before collecting authentication information from Jira, review the screenshot below, which shows the PGP authentication setup screen where you'll enter these details. Having this view in mind will help you understand exactly what information we need to gather from Jira.
Let's walk through each step.
First, you'll need to locate your Jira base URL. Log into your Jira instance and look at the address bar in your browser. Your base URL will be in the format https://your-domain.atlassian.net. Make note of this URL. Don't include any additional path information like /jira or other extensions. You'll need this URL when we return to PGP.
Next, we'll set up the authentication that allows PGP to communicate securely with Jira. This requires creating an API token through Atlassian. Your API token will need to have the following permissions:
- BROWSE_PROJECTS
- CREATE_ISSUES
- EDIT_ISSUES
- ADD_COMMENTS
- RESOLVE_ISSUES
- EDIT_OWN_COMMENTS
To create the API token, visit the Atlassian API Tokens page by clicking on your profile picture in Jira, selecting "Manage Account":
Navigate to the Security section:
Navigate to the API tokens page:
Alternatively, you can go directly to the API tokens page at https://id.atlassian.com/manage/api-tokens. Once there, click the "Create API Token" button.
Give your token a meaningful label that will help you identify its purpose later, such as "PGP Integration."
After clicking Create, you'll see your newly generated token. This is a crucial moment - copy this token immediately and store it somewhere secure, as you won't be able to view it again after closing this dialog. Treat this token with the same care as you would a password, as it provides access to your Jira instance.
More on Atlassian API tokens can be found here.
The User Email field in PGP will take the email of the user that created the API token in Jira. To find this in Jira, click on the account icon at the top right. You can view and copy the email that that will go in the User Email field.
With your base URL, API token, and User Email secured, return to PGP and add this information to the Jira setup dialog.
Once PGP is successfully authenticated to Jira, the second step of the setup will begin: tailoring PGP messaging to your Jira instance. Fill out the Integration Name section. Select one of the projects available through the API token provided. Choose a type - PGP will send issues to Jira under the type you specify here (e.g., story, bug, task). You can also decide whether you want Jira to automatically create issues in the Jira project you've chosen. If you choose to enable automatic issue creation, all PGP vulnerabilities at or above the selected severity level will be created as the desired issue type in the selected Jira project.
Click Connect to complete the setup.
Manual Ticket Creation
Whether or not you enable automatic Jira Issue creation, you can manually create issues for vulnerabilities.
On every vulnerability, under the More Actions dropdown, you will see "Create New Ticket". Clicking this will prompt PGP to send this vulnerability and its details to the Jira Project of your choosing. You can also add multiple Jira Projects in PGP so different Jira groups receive different information.
Once the ticket has been created, PGP will display relevant information in the vulnerability drawer.
If a ticket has already been manually created in Jira, that ticket can be associated with a vulnerability in PGP by going to the More Actions dropdown and choosing Associate Existing Ticket.
Once the vulnerability has been associated, you'll see that ticket and relevant information in the vulnerability drawer.
What Information Goes Into Jira Tickets
When PGP creates a Jira ticket, it includes comprehensive vulnerability information to help your team understand and remediate the security issue. Here's what you'll find in each ticket:
Ticket Title (Summary)
The ticket title displays the vulnerability name. This appears at the top of the Jira issue and in issue lists.
Ticket Description
The description field contains detailed information about the vulnerability, formatted in Jira markup. It includes:
- PGP Link: A direct link to view the vulnerability in your PGP instance. This allows team members to access the full vulnerability details, history, and context within PGP.
- Severity: The severity level of the vulnerability (Critical, High, Medium, Low, Info, or Exposure). This helps prioritize remediation efforts.
- Assets Impacted: A table listing all assets affected by this vulnerability. The table includes two columns:
- DNS: The domain name or IP address of the affected asset
- Name: The name or identifier of the affected asset (such as port targets or webpage URLs)
- Vulnerability Definition: The complete vulnerability definition content, including technical details, impact assessment, remediation recommendations, and any references. This content is automatically converted from markdown to Jira markup format, preserving formatting, code blocks, lists, and other structured elements.
- Additional Evidence: If evidence has been collected for the vulnerability, it appears in a dedicated "Additional Evidence" section. Text-based evidence is included directly in the description, while binary evidence files are attached separately (see Attachments below).
Project and Issue Type
The ticket is created in the Jira project you specified during integration setup. The issue type (such as Bug, Task, or Story) is also determined by your template configuration. These fields appear in the Jira issue's metadata and determine where the ticket appears in your Jira workflows.
Labels
If the vulnerability has tags associated with it in PGP, those tags are automatically added as labels to the Jira ticket. Labels are sanitized to meet Jira's requirements (alphanumeric characters, hyphens, and underscores only) and appear in the Labels field of the issue. This helps with filtering, searching, and organizing tickets.
Attachments
PGP automatically attaches relevant files to the Jira ticket:
- Screenshots: Any screenshots referenced in the vulnerability definition or evidence are extracted and uploaded as image attachments. These appear in the Attachments section of the Jira issue.
- Evidence Files: Binary evidence files that cannot be displayed as text are attached to the ticket. These files are named with the format "evidence-[vulnerability-name]" and appear in the Attachments section.
- Proof Files: If proof data exists for the vulnerability, it is attached as a file named "proof-[vulnerability-name]". This provides additional technical details that may be needed for remediation.
All attachments are accessible directly from the Jira issue, allowing team members to review visual evidence and technical details without leaving Jira.
We hope these instructions are helpful! If you would like any topic discussed in more detail or need further assistance, please contact us at support@praetorian.com.