Jira Destination Setup

Create Jira issues for detection alerts using the Jira REST API.

Prerequisites

• Jira instance (Cloud or Server)
• Jira user with issue creation permissions
• API token (for Jira Cloud) or password (for Jira Server)

Setup Steps

1. Create Jira API Token (Cloud)

For Jira Cloud:

1. Log into Atlassian Account
2. Navigate to Security → API tokens
3. Click Create API token
4. Enter label (e.g., "Query.ai Security Detections")
5. Click Create
6. Copy the API token - you won't see it again

For Jira Server/Data Center:

• Use your Jira password instead of API token

2. Verify Permissions

Ensure the Jira user has:

• Browse Projects permission
• Create Issues permission
• Access to the target project

3. Get Project Key

1. Navigate to your Jira project
2. Check the URL or project settings
3. Note the Project Key (e.g., "SEC", "IT", "PROJ")

4. Configure in Query.ai

Contact your Query.ai administrator to configure the Jira destination with:

Required Configuration:

• Instance URL (e.g., https://your-domain.atlassian.net)
• Email address
• API token (stored securely)
• Project key

Optional Configuration:

• Issue type (default: "Task")
• Priority
• Labels
• Timeout in seconds (default: 30)

Issue Fields

Jira issues are created with the following fields:

Priority Mapping

If priority is configured, detection severity maps to Jira priority:

Note: Priority mapping depends on your Jira configuration. Not all Jira instances use the same priority names.

Description Field Contents

The description includes:

• Detection name and description
• Severity, outcome, and match count
• Run type (SCHEDULED or MANUAL)
• Threshold configuration (operator, value, eagerness)
• Execution metadata (exhaustiveness, search ID, trace ID if available)
• Timestamps (ran at, time range)
• Replay link for investigation
• Error messages (if any)

Testing

Test credentials with curl:

curl -X POST \
  "https://your-domain.atlassian.net/rest/api/3/issue" \
  -u "[email protected]:your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "project": {"key": "SEC"},
      "summary": "Test Issue from Query.ai",
      "description": "This is a test issue created via API",
      "issuetype": {"name": "Task"}
    }
  }'

Expected Response: JSON object with issue key and ID

Troubleshooting

Configuration Options

Required

instance_url

• Jira instance URL
• Cloud: https://your-domain.atlassian.net
• Server: https://jira.your-company.com
• Do not include trailing slash

email

• Jira user email address
• Used for authentication with API token

api_token (secret)

• API token (Jira Cloud) or password (Jira Server)
• Stored securely in AWS Secrets Manager

project_key

• Jira project key
• Format: Uppercase letters (e.g., "SEC", "IT")
• Case-sensitive

Optional

issue_type

• Jira issue type name
• Default: "Task"
• Common values: "Task", "Bug", "Story", "Epic"
• Must exist in the project

priority

• Jira priority name
• Examples: "Highest", "High", "Medium", "Low", "Lowest"
• If not specified, uses project default
• Must exist in Jira configuration

labels

• Array of label strings
• Automatically includes "security-detection"
• Additional labels can be specified
• Format: Array of strings

timeout

• Request timeout in seconds
• Default: 30
• Maximum: 300 (5 minutes)

Jira Workflow Integration

Automation Rules

Create Jira automation rules to process detection issues:

1. Navigate to Project settings → Automation
2. Click Create rule
3. Set trigger: Issue created
4. Add condition: Labels contains "security-detection"
5. Add actions:
   • Assign to user/group
   • Add comment
   • Transition issue
   • Send notification

Custom Fields

Add custom fields to capture detection metadata:

1. Navigate to Settings → Issues → Custom fields
2. Create custom fields:
   • Detection ID (Number)
   • Severity (Select List)
   • Match Count (Number)
3. Add fields to issue screen
4. Fields will be populated if configured

Issue Links

Link detection issues to related issues:

• Parent/child relationships
• Blocks/is blocked by
• Relates to
• Duplicates

Issue Investigation

When Jira issue is created:

1. Open issue in Jira
2. Review issue description
3. Click replay link to investigate in Query.ai
4. Document findings in comments
5. Update issue status as investigation progresses
6. Link to related issues if needed

Security Best Practices

1. Never Commit Credentials: Always store API tokens in Secrets Manager
2. Use Dedicated Account: Create service account for automation
3. Rotate Tokens: Rotate API tokens every 90 days
4. Least Privilege: Grant only required project permissions
5. Monitor Usage: Review API usage in Jira audit logs

API Token Rotation

To rotate API token:

1. Create new API token in Atlassian Account
2. Update token in Query.ai configuration
3. Test with a manual detection run
4. Revoke old API token after verification

Multiple Projects

Create separate destinations for different Jira projects:

Example Use Cases:

• Critical alerts → Security project
• Infrastructure alerts → IT project
• Application alerts → Development project

Each destination uses different project keys.

Jira Cloud vs Server

Jira Cloud

• Uses API tokens for authentication
• URL format: https://your-domain.atlassian.net
• REST API v3: /rest/api/3/issue

Jira Server/Data Center

• Uses passwords for authentication
• URL format: https://jira.your-company.com
• REST API v2: /rest/api/2/issue

The destination automatically detects and uses the appropriate API version.

Resources

• Jira REST API Documentation
• Jira API Tokens
• Jira Automation
• Jira Custom Fields