Jira Integration¶

Faraday's Jira integration allows you to export confirmed vulnerabilities as Jira issues with full field mapping and maintain bidirectional status synchronization via Jira Automation rules. When a vulnerability status changes in Faraday, the linked Jira issue transitions automatically — and vice versa.

Availability: Commercial feature (requires licensed Faraday instance).

Verified against: Faraday Server v5.19.0 codebase, wiki doc dated 2025-10-28.

Overview¶

Status Mapping¶

Status mapping is fully configurable per project. You define both incoming (Jira → Faraday) and outgoing (Faraday → Jira) mappings independently.

Available Faraday statuses:

Jira statuses depend on your project's workflow configuration and are fetched dynamically from your Jira instance.

Prerequisites¶

• A running Faraday Server instance (commercial edition)
• A Jira instance (Jira Cloud or Jira Server 8.x+)
• Ability to create an Application Link in Jira
• Network connectivity between Faraday Server and Jira

Step 1: Configure Connection Settings (OAuth)¶

Generate Keys in Faraday¶

1. Log in to the Faraday Web UI.
2. Go to Settings > Ticketing Tools > Jira.
3. Open the Connection Settings tab.
4. Click the Edit button to open the configuration fields.
5. Enter your Jira Instance URL (e.g., https://faraday.atlassian.net).
6. Enter a Consumer Key Name (e.g., faraday-key).
7. Click Generate Public Key — a public key appears in the field.
8. Copy the public key to your clipboard.
9. Click Save Connection Settings.

Create Application Link in Jira¶

1. In Jira, go to Administration > Applications > Application Links.
2. Create a new Application Link:

For Jira Cloud, the Application Link setup may differ slightly. Refer to Atlassian's Application Links documentation.

Authorize the Connection¶

1. Return to Faraday's Connection Settings tab.
2. Click the Authorize button.
3. If the connection fails, you will see an error message — verify your URL, consumer key, and public key match between Faraday and Jira.
4. If successful, you will be prompted to allow Faraday access to read and write Jira data.
5. After confirming access, the Connection Settings tab gear icon turns green.

Step 2: Configure Projects¶

Navigate to the Projects tab in the Jira configuration.

2.1 Fetch Projects¶

Click Fetch Projects to retrieve all available projects from your Jira instance. This populates the project dropdown. The button remains disabled while projects are loading.

2.2 Add Projects¶

Select projects from the dropdown to add them to the configuration table. You can add multiple projects.

2.3 Configure Issue Types and Fields¶

For each project:

1. Click the red gear icon in the Issue Type column.
2. Select an issue type from the list (e.g., Bug, Task, Story).
3. Configure mandatory fields (marked with a red asterisk):
4. Summary — supports Jinja2 templates using vulnerability data
5. Description — supports Jinja2 templates using vulnerability data
6. Other mandatory fields depend on the selected issue type
7. Optionally add optional fields using the + button:
8. Click to add from a list of available fields for the issue type

Supported Field Types¶

Note: Only the Summary and Description fields support Jinja2 template syntax. All other fields accept fixed values.

2.4 Configure Bidirectional Status Mapping (Optional)¶

Click the red gear icon in the Attribute Mapping column to configure bidirectional status synchronization.

Outgoing (Faraday → Jira)¶

Maps Faraday vulnerability status changes to Jira issue transitions. When a vulnerability status changes in Faraday, the linked Jira issue automatically transitions to the mapped status.

Note: If the transition is not valid in Jira (due to workflow constraints), the synchronization will fail and the Jira issue will not update.

Incoming (Jira → Faraday)¶

Maps Jira issue status transitions to Faraday vulnerability status changes. When a linked Jira issue changes status, the webhook triggers and Faraday updates the vulnerability status per this mapping.

Note: Status updates triggered by incoming webhooks are not considered manual updates. This prevents infinite update loops.

2.5 Activate Projects¶

Once the issue type is configured (gear icon turns green):

1. Click the checkbox to the left of each project row to activate it.
2. Multiple projects can be active simultaneously.
3. The trash can icon at the right of each row permanently deletes the project configuration (this cannot be undone).

2.6 Activate the Integration¶

If both the Connection Settings and Projects tabs show green gear icons, the integration slider at the top-left of the configuration panel becomes available. The integration activates automatically when you activate the first configured project.

Step 3: Set Up Bidirectional Sync (Jira Automation)¶

To enable Jira → Faraday status sync, create a Jira Automation rule:

Create Jira Automation Rule¶

1. In Jira, go to Settings > System > Automation rules (or Project Settings > Automation for project-level rules).
2. Create a new rule.

Trigger ("When")¶

Action ("Then")¶

Webhook payload:

{
  "title": "{{issue.key}}",
  "desc": "{{issue.description.jsonEncode()}}",
  "priority": "{{issue.priority.name.jsonEncode()}}",
  "status": "{{issue.status.name.jsonEncode()}}"
}

Headers¶

Create a Faraday User Token (Jira Scope)¶

1. In Faraday, go to Preferences > Access Tokens.
2. Click Add Token.
3. Set the scope to Jira and choose an alias.
4. Copy the token immediately — it is displayed only once.
5. Paste this token as the X-Jira-Token header value in the Jira Automation rule.

Enable the Rule¶

Activate the automation rule in Jira. Once enabled, any status change on a Jira issue that has a linked Faraday vulnerability will trigger a webhook to Faraday.

Step 4: Export Vulnerabilities to Jira¶

1. In the Faraday Web UI, go to Manage > Vulns.
2. Select one or more confirmed vulnerabilities.
3. Click Tools (context menu) and select Jira.
4. If multiple projects are active, select the target project.
5. Vulnerabilities are created as issues in the selected Jira project using the configured field mappings.

Tracking Exported Vulnerabilities¶

• Add the issuetracker column to the vulnerability table to see linked Jira issue keys.
• Click the Jira issue key in the column to open the issue directly in Jira.
• The issuetracker_json field provides structured details (issue URL, ID) and can be used in Executive Reports.

Vulnerability Model Fields¶

Jira Configuration Data Structure¶

The integration configuration is stored in the configuration database table under the key jira_integration as JSON:

{
  "url": "https://your-jira-instance.atlassian.net",
  "consumer_key": "faraday-key",
  "rsa_public_key": "-----BEGIN PUBLIC KEY-----...",
  "authorization_state": "authorized",
  "enabled": true,
  "projects": {
    "PROJECT_KEY": {
      "ticket_config": {
        "issue_types": {
          "Bug": {
            "fields": {
              "Summary": {"schema": {"type": "string"}, "value": "JINJA_TEMPLATE"},
              "Description": {"schema": {"type": "string"}, "value": "JINJA_TEMPLATE"},
              "Priority": {"schema": {"type": "priority"}, "value": "High"}
            }
          }
        }
      },
      "attribute_mapping": {
        "incoming": {},
        "outgoing": {}
      }
    }
  }
}

Permissions¶

The ticketing.jira extra permission controls access to the Jira ticketing feature in the vulnerability context menu.

Data Model¶

UserToken Model¶

Tokens for Jira webhook authentication:

Configuration Storage¶

Integration settings are stored in the configuration database table:

CREATE TABLE configuration (
    id        INTEGER PRIMARY KEY,
    key       VARCHAR UNIQUE NOT NULL,
    value     JSONB NOT NULL,
    create_date  TIMESTAMP,
    update_date  TIMESTAMP,
    creator_id   INTEGER,
    update_user_id INTEGER
);

Jira integration configuration is stored under the key jira_integration.

Troubleshooting¶

Checking Integration Status¶

• Connection Settings tab: Green gear = authorized, red gear = not connected.
• Projects tab: Green gear = at least one project activated.
• Issuetracker column: Add to vulnerability table to see linked issues.
• Access Tokens: Navigate to Preferences > Access Tokens to verify token status, scope, and expiration.
• Server logs: Check Faraday Server logs for webhook processing errors.

Changelog¶

Source References¶

• Wiki source: repos/faraday-wiki/docs/integration-jira.md
• Permission definitions: faraday/server/utils/permissions.py — UNIT_JIRA
• UserToken model: faraday/server/models.py (line ~2636) — JIRA_SCOPE
• VulnerabilityGeneric model: faraday/server/models.py (line ~1431) — issuetracker, association_date, disassociated_manually
• Configuration model: faraday/server/models.py (line ~3641)
• Extra permissions: faraday/server/api/base.py (line ~2092) — ticketing.jira
• Migration (Jira scope): faraday/migrations/versions/000918b77c25_add_jira_scope.py
• Migration (config table): faraday/migrations/versions/b49d8efbd0c2_add_configuration_table.py
• Migration (field reformat): faraday/migrations/versions/06c48492f587_reformat_jira_issue_fields_value.py
• Atlassian docs: Application Links