Jira Integration #
This section outlines the configuration steps necessary for creating a Jira project to manage vulnerabilities in the MyOrbik application and the associated REST API endpoints. The configuration process is implemented in the jira_service module.
Introduction #
The purpose of this document is to provide a clear guide on setting up a Jira project to manage and track vulnerabilities in MyOrbik. The configuration will allow MyOrbik to interact with Jira’s API to create and manage issues related to vulnerabilities identified in the application and its endpoints.
This integration uses Jira’s REST API (v3) to automate project setup and issue creation.
Prerequisites #
Before interacting with Jira’s REST API, you must set up basic authentication using a Jira user account with administrator permissions. The authentication requires the user’s email and an API token for access.
The following parameters are required when initializing the jira_service module:
- url: The URL of the Jira instance (e.g., https://orbik-team.atlassian.net).
- email: The email address of a Jira user with administrator permissions.
- token: The API token, which can be managed in Account Settings -> Security.
- account_id: The account ID of the Jira user with administrator permissions. To retrieve this ID, go to Atlassian Administration -> User Management, select the user, and extract the ID from the URL.
- client_id: The UUID of the client for identification.
Automating Jira Project Creation #
This section explains the steps to automatically create necessary elements for the Jira project configuration using Jira’s REST API v3.
Issue Type Creation #
The first step is to create a custom issue type for vulnerabilities in MyOrbik. Use the following API call to create the issue type:
POST /rest/api/3/issuetype
Body:
{
“name”: “Vulnerability myOrbik”
}
After the call, the response will return a 201 status with the new issue type’s id (string), which will be used in later API calls.
Issue Type Scheme #
Next, create an issue type scheme that includes the “Vulnerability myOrbik” issue type. This can be done with the following API call:
POST /rest/api/3/issuetypescheme
Body:
{
“name”: “Vulnerability myOrbik type scheme”,
“defaultIssueTypeId”: “ID of the custom issue type”,
“issueTypeIds”: [“ID of the custom issue type”]
}
The response will return a 201 status with the issueTypeSchemeId (string), which will be used for further configuration.
Custom Fields Creation #
To manage vulnerabilities effectively, create several custom fields. These fields will track key data points, such as product details, CVE identifiers, and vulnerability responses. The following fields are needed:
- Product name (text field)
- Product version (text field)
- CPE name (text field)
- CPE version (text field)
- CVE (text field)
- Revised score (numeric field)
- Justification (multi-select field)
- Details (textarea)
- Response (multi-select field)
Each field is created using the following API call:
POST /rest/api/3/field
Body (for text fields):
{
“name”: “Field name”,
“description”: “Field description”,
“type”: “com.atlassian.jira.plugin.system.customfieldtypes:textfield”
}
For numeric fields, use:
{
“type”: “com.atlassian.jira.plugin.system.customfieldtypes:float”
}
For textarea fields, use:
{
“type”: “com.atlassian.jira.plugin.system.customfieldtypes:textarea”
}
For multi-select fields, use:
{
“type”: “com.atlassian.jira.plugin.system.customfieldtypes:select”
}
Each call returns a 201 status with an id (string) for each field.
Creating Field Options (For Multi-Select Fields) #
For the Justification and Response fields, you need to define the available options. After creating the fields, the following steps should be followed:
- First, get the context of the custom field:
GET /rest/api/3/field/{fieldId}/context
Use the returned values[0][“id”] from the response.
- Then, create the options for the multi-select fields:
POST /rest/api/3/field/{fieldId}/context/{contextId}/option
Body for the Justification field:
{
“options”: [
{“value”: “Code not present”},
{“value”: “Code not reachable”},
{“value”: “Requires configuration”},
{“value”: “Requires dependency”},
{“value”: “Requires environment”},
{“value”: “Protected by compiler”},
{“value”: “Protected at runtime”},
{“value”: “Protected at perimeter”},
{“value”: “Protected by migrating control”}
]
}
Body for the Response field:
{
“options”: [
{“value”: “Can not fix”},
{“value”: “Will not fix”},
{“value”: “Update”},
{“value”: “Rollback”},
{“value”: “Workaround available”}
]
}
Field Configuration #
Field configurations define how the custom fields behave in Jira. In this case, you’ll configure fields such as Product name and CVE to be mandatory.
POST /rest/api/3/fieldconfiguration
Body:
{
“name”: “Vulnerability myOrbik field configuration”
}
The response will return a 201 status with the id (float) for use in subsequent calls.
Update Field Configuration #
Once the field configuration is created, you can update it to make specific fields required. This can be done by using the following API call:
PUT /rest/api/3/fieldconfiguration/{fieldConfigurationId}/fields
Body:
{
“fieldConfigurationItems”: [
{
“id”: “ID of the product name field”,
“isRequired”: true
},
{
“id”: “ID of the cve field”,
“isRequired”: true
}
]
}
This ensures that the Product name and CVE fields are marked as required during issue creation.
Field Configuration Scheme #
After creating the field configuration, you need to create a field configuration scheme to map the field configuration to the issue types.
POST /rest/api/3/fieldconfigurationscheme
Body:
{
“name”: “Vulnerability myOrbik field configuration scheme”
}
The response will return a 201 status with the id (string) for use in subsequent API calls.
Assign Issue Types to Field Configuration Scheme #
To assign the field configuration to the issue types, use the following API call:
PUT /rest/api/3/fieldconfigurationscheme/{schemeId}/mapping
Body:
{
“mappings”: [
{
“fieldConfigurationId”: “ID of the field configuration”,
“issueTypeId”: “default”
},
{
“fieldConfigurationId”: “ID of the field configuration”,
“issueTypeId”: “ID of the custom issue type”
}
]
}
Ensure that a mapping with the default issue type is included.
Screens #
Screens in Jira group together fields that are shown when creating or editing an issue. Three different screens will be created, each corresponding to a specific vulnerability management stage:
- Vulnerability review screen (fields for product name, product version, CPE name, CPE version, and CVE)
- Vulnerability assessment screen (includes the previous fields plus revised score, justification, and details)
- Vulnerability address screen (includes the previous fields plus justification, response, and details)
Each screen will have its own set of fields that are added through different API calls.
Vulnerability Review Screen #
POST /rest/api/3/screens
Body:
{
“name”: “Vulnerability myOrbik review screen”
}
The response will return a 201 status with the id (float) for use in subsequent calls.
Once the screen is created, you can obtain the default tab ID for this screen:
GET /rest/api/3/screens/{reviewScreenId}/tabs
Adding Fields to the Screen Tab #
Add fields to the screen tab, including the required summary and description fields, as well as other custom fields:
POST /rest/api/3/screens/{reviewScreenId}/tabs/{tabId}/fields
Body:
{
“fieldId”: “summary”
}
Subsequent calls for additional fields:
{“fieldId”: “description”}
{“fieldId”: “Product name”}
{“fieldId”: “Product version”}
{“fieldId”: “CPE name”}
{“fieldId”: “CPE version”}
{“fieldId”: “CVE”}
Vulnerability Assessment Screen #
POST /rest/api/3/screens
Body:
{
“name”: “Vulnerability myOrbik assessment screen”
}
The response will return a 201 status with the id (float).
After creating the screen, obtain the tab ID:
GET /rest/api/3/screens/{assessmentScreenId}/tabs
Adding Fields to the Assessment Screen Tab #
Add fields to the assessment screen tab:
{“fieldId”: “summary”}
{“fieldId”: “description”}
{“fieldId”: “Product name”}
{“fieldId”: “Product version”}
{“fieldId”: “CPE name”}
{“fieldId”: “CPE version”}
{“fieldId”: “CVE”}
{“fieldId”: “Revised score”}
{“fieldId”: “Justification”}
{“fieldId”: “Details”}
Vulnerability Address Screen #
POST /rest/api/3/screens
Body:
{
“name”: “Vulnerability myOrbik address screen”
}
The response will return a 201 status with the id (float).
After the screen is created, obtain the tab ID:
GET /rest/api/3/screens/{addressScreenId}/tabs
Adding Fields to the Address Screen Tab #
Add fields to the address screen tab:
{“fieldId”: “summary”}
{“fieldId”: “description”}
{“fieldId”: “Product name”}
{“fieldId”: “Product version”}
{“fieldId”: “CPE name”}
{“fieldId”: “CPE version”}
{“fieldId”: “CVE”}
{“fieldId”: “Justification”}
{“fieldId”: “Response”}
{“fieldId”: “Details”}
Screen Schemes #
A screen scheme associates a screen with the actions for editing, viewing, or using the default action for an issue.
Review Screen Scheme #
POST /rest/api/3/screenscheme
Body:
{
“name”: “Vulnerability myOrbik review screen scheme”,
“screens”: {
“default”: “id of review screen”,
“edit”: “id of review screen”,
“view”: “id of review screen”
}
}
The response will return a 201 status with the id (float).
Assessment Screen Scheme #
POST /rest/api/3/screenscheme
Body:
{
“name”: “Vulnerability myOrbik assessment screen scheme”,
“screens”: {
“default”: “id of assessment screen”,
“edit”: “id of assessment screen”,
“view”: “id of assessment screen”
}
}
The response will return a 201 status with the id (float).
Address Screen Scheme #
POST /rest/api/3/screenscheme
Body:
{
“name”: “Vulnerability myOrbik address screen scheme”,
“screens”: {
“default”: “id of address screen”,
“edit”: “id of address screen”,
“view”: “id of address screen”
}
}
The response will return a 201 status with the id (float).
Screen Scheme by Issue Type #
To associate screen schemes with issue types, use the following API call:
POST /rest/api/3/issuetypescreenscheme
Body:
{
“name”: “Vulnerability myOrbik type review screen scheme”,
“issueTypeMappings”: [
{
“issueTypeId”: “default”,
“screenSchemeId”: “id of review screen scheme”
},
{
“issueTypeId”: “id of custom issue type”,
“screenSchemeId”: “id of review screen scheme”
}
]
}
The response will return a 201 status with the id (string) for use in subsequent API calls.
Workflows #
Creating a custom workflow involves defining states and transitions between those states. The following states are required:
- Detected
- In triage
- Exploitable
- Resolved
- False positive
- Not affected
The custom workflow is created by the following API call:
POST /rest/api/3/workflow
Body:
{
“scope”: {
“type”: “GLOBAL”
},
“statuses”: [
{
“name”: “Detected (myOrbik)”,
“statusCategory”: “TODO”,
“statusReference”: “uuid of detected status”
},
{
“name”: “In triage (myOrbik)”,
“statusCategory”: “IN_PROGRESS”,
“statusReference”: “uuid of in triage status”
},
{
“name”: “Exploitable (myOrbik)”,
“statusCategory”: “IN_PROGRESS”,
“statusReference”: “uuid of exploitable status”
},
{
“name”: “Resolved (myOrbik)”,
“statusCategory”: “DONE”,
“statusReference”: “uuid of resolved status”
},
{
“name”: “False positive (myOrbik)”,
“statusCategory”: “DONE”,
“statusReference”: “uuid of false positive status”
},
{
“name”: “Not affected (myOrbik)”,
“statusCategory”: “DONE”,
“statusReference”: “uuid of not affected status”
}
],
“workflows”: [
{
“name”: “myOrbik workflow”,
“statuses”: [
{
“properties”: {},
“statusReference”: “uuid of detected status”
},
{
“properties”: {},
“statusReference”: “uuid of in triage status”
},
{
“properties”: {},
“statusReference”: “uuid of exploitable status”
},
{
“properties”: {},
“statusReference”: “uuid of resolved status”
},
{
“properties”: {},
“statusReference”: “uuid of false positive status”
},
{
“properties”: {},
“statusReference”: “uuid of not affected status”
}
],
“transitions”: [
{
“id”: “99999”,
“name”: “Initial”,
“type”: “INITIAL”,
“to”: {
“statusReference”: “uuid of detected status”
},
“transitionScreen”: {
“ruleKey”: “system:transition-screen”,
“parameters”: {
“screenId”: “id of review screen”
}
}
},
{
“id”: “99998”,
“name”: “Detected”,
“type”: “GLOBAL”,
“to”: {
“statusReference”: “uuid of detected status”
}
},
{
“id”: “99997”,
“name”: “In triage”,
“type”: “GLOBAL”,
“to”: {
“statusReference”: “uuid of in triage status”
},
“transitionScreen”: {
“ruleKey”: “system:transition-screen”,
“parameters”: {
“screenId”: “id of assessment screen”
}
}
},
{
“id”: “99996”,
“name”: “Exploitable”,
“type”: “GLOBAL”,
“to”: {
“statusReference”: “uuid of exploitable status”
},
“transitionScreen”: {
“ruleKey”: “system:transition-screen”,
“parameters”: {
“screenId”: “id of assessment screen”
}
}
},
{
“id”: “99995”,
“name”: “Resolved”,
“type”: “GLOBAL”,
“to”: {
“statusReference”: “uuid of resolved status”
},
“transitionScreen”: {
“ruleKey”: “system:transition-screen”,
“parameters”: {
“screenId”: “id of address screen”
}
}
},
{
“id”: “99994”,
“name”: “False positive”,
“type”: “GLOBAL”,
“to”: {
“statusReference”: “uuid of false positive status”
},
“transitionScreen”: {
“ruleKey”: “system:transition-screen”,
“parameters”: {
“screenId”: “id of address screen”
}
}
},
{
“id”: “99993”,
“name”: “Not affected”,
“type”: “GLOBAL”,
“to”: {
“statusReference”: “uuid of not affected status”
},
“transitionScreen”: {
“ruleKey”: “system:transition-screen”,
“parameters”: {
“screenId”: “id of address screen”
}
}
}
]
}
]
}
Workflow Scheme #
Finally, a workflow scheme must be created to associate the custom workflow with the issue types.
POST /rest/api/3/workflowscheme
Body:
{
“name”: “myOrbik workflow scheme”,
“defaultWorkflow”: “name of the workflow”,
“issueTypeMappings”: {
“id of issue type”: “name of the workflow”
}
}
The response will return a 201 status with the id (float).
Create Project #
Finally, with all the previous configurations in place, the project can be created:
POST /rest/api/3/project
Body:
{
“assigneeType”: “UNASSIGNED”,
“key”: “MYO”,
“name”: “myOrbik vulns”,
“projectTypeKey”: “software”,
“fieldConfigurationScheme”: “id of field configuration scheme”,
“issueTypeScheme”: “id of issue type scheme”,
“issueTypeScreenScheme”: “id of issue type screen scheme”,
“leadAccountId”: “lead account id”,
“workflowScheme”: “id of workflow scheme”
}
This will create a project that uses all the previously configured settings.
