Create Jira issues from alerts
With Jira connected, an operator turns an alert or a security finding into a Jira issue with one click. The issue is prefilled with everything Excubius knows, its key is stored on the alert, and its status is followed until it is done. This guide shows how to connect Jira Cloud, how to send each client to its own project, and what the issue contains.
Before you begin
- A Jira Cloud site. Jira Server and Data Center are not supported.
- An Atlassian account for Excubius with these permissions in the target projects: Browse projects, Create issues, Add comments and Link issues. No administration right is needed: Excubius never transitions, edits or deletes issues.
- The feature
collab.jirais on in Settings › Instance. It requirescollab.assign. A super admin switches it. - To set server-wide defaults, you need access to the server configuration. To set an entity's own Jira settings, you need the Entity admin role on it.
There is no Jira settings screen in the console in this release: you set the defaults in the server configuration and per-entity settings through the API.
Choose how Excubius signs in to Jira
auth | Credentials | Use it when |
|---|---|---|
token (default) | The account's e-mail address and an API token | The usual case: a dedicated Atlassian account with an API token |
oauth | The client ID and client secret of an Atlassian service account, plus the site's cloud ID | Your organisation uses Atlassian service accounts with OAuth 2.0 client credentials. The API is then reached at https://api.atlassian.com/ex/jira/<cloud_id> |
bearer | A token sent as is | A personal access token behind a gateway |
Find the cloud ID of a site at https://<site>.atlassian.net/_edge/tenant_info.
Set the defaults on the server
The defaults apply to every entity that does not set its own.
-
Connect to the server and become the service account with
sudo -iu excubius. -
Add the settings to
/opt/excubius/.env. For the defaulttokenauthentication:JIRA_BASE_URL=https://areito.atlassian.netJIRA_EMAIL=monitoring@areito.exampleJIRA_API_TOKEN=<API token>JIRA_DEFAULT_PROJECT=OPSJIRA_ISSUE_TYPE=TaskFor
oauth, setJIRA_AUTH=oauth,JIRA_OAUTH_CLIENT_ID,JIRA_OAUTH_CLIENT_SECRETandJIRA_CLOUD_IDinstead of the e-mail and API token. -
Restart the platform:
export XDG_RUNTIME_DIR=/run/user/$(id -u)systemctl --user restart excubius.service
Send a client to its own project
Each entity can set any of the Jira keys for itself. The setting is inherited down the tree key by key: the nearest entity that sets a key wins. So one Jira site can serve every client, each with its own project and credential.
-
Store the Jira credential on the entity: open Settings › Credentials, choose the entity, for example Ciguapa Inc., and add a credential of kind HTTP user and password (the e-mail and API token, or the OAuth client ID and secret) or Bearer token. The secret is stored encrypted and never shown again.
-
Set the entity's keys through the API.
$BASEishttps://<your server>/api/v1andHholds your token, as in Quickstart: add a SQL Server instance with the API:curl -s "${H[@]}" -X PUT "$BASE/entities/$CIGUAPA/jira" -d '{"project_key": "CIG", "issue_type": "Task","credential_id": "'"$JIRA_CRED"'", "labels": ["monitoring"]}' -
Check what applies and where each key comes from. The answer says whether the entity is
configuredand, if not, what is missing inproblem:curl -s "${H[@]}" "$BASE/entities/$CIGUAPA/jira" | jq '{configured, problem, effective, sources}' -
Test the connection. The test only reads: who the credential is in Jira, the project and its issue types.
curl -s "${H[@]}" -X POST "$BASE/entities/$CIGUAPA/jira/test"
To put a key back to the inherited value, send it as null. DELETE /entities/{id}/jira removes all of the entity's own keys.
| Key | Default | Meaning |
|---|---|---|
base_url | JIRA_BASE_URL | https://<site>.atlassian.net |
auth | JIRA_AUTH, token when not set | token, oauth or bearer |
credential_id | The e-mail and token, or OAuth client, from the server configuration | A credential of this entity or an ancestor: HTTP user and password for token and oauth, Bearer token for bearer |
cloud_id | JIRA_CLOUD_ID | For oauth only |
project_key | JIRA_DEFAULT_PROJECT | Where issues go, such as OPS |
issue_type | JIRA_ISSUE_TYPE, Task when not set | The issue type's name in that project |
priority_map | critical → High, warning → Medium, info → Low | Severity to Jira priority name |
labels | None | Extra labels, without spaces |
summary_prefix | The product name in brackets | Text before the summary; an empty text for none |
sync | true | Follow the issue's status |
done_comment | true | Comment on the issue when it is done, saying whether the condition is still detected |
resolve_events_on_done | true | Resolve event alerts, such as a change in privileged group members, when their issue is done |
Create an issue
- In the Alert inbox, select the alert. For a security finding, open it on the Security posture page.
- Select Create Jira ticket. You need the Operator role or higher.
Excubius confirms Jira ticket OPS-123 created and stores the key on the alert, where everyone sees it. An alert gets at most one issue: asking again returns the existing key.
The issue contains:
- Summary: the prefix, the alert's title and the resource.
- Description: severity, category and status; first and last seen; the resource with its entity path, criticality, tags and identifying details such as host, version and availability group; the check's value against the threshold and where that threshold is set; for a finding, its evidence; the baseline reference; the last ten timeline events; the suggested action, marked as a suggestion; and links back to the alert and the resource.
- Labels: the product name, the category (
alert,finding,advisory), the severity and your extra labels. - Priority: from the severity through
priority_map. When the project does not accept a priority, the issue is created without one. - A link on the issue back to the alert.
Follow the issue's status
Every 10 minutes Excubius reads the status of up to 100 open issues, least recently checked first. JIRA_SYNC_MINUTES changes the interval. When an issue reaches a status of the Done category:
- The alert's timeline records it.
- An event alert, such as a change in
sysadminmembers, is resolved: the change was reviewed. - Other alerts are not resolved by the issue. They resolve when the next check no longer detects the condition, and the comment on the issue says whether it is still detected.
An expired token or a deleted issue is recorded and retried at the next sync. The issue is not followed after it is done.
Limitations
- The status is polled; Jira webhooks back to Excubius are not used yet.
- OAuth 2.0 is the client-credentials flow of an Atlassian service account. Per-user OAuth is not supported.
- Jira Server and Data Center are not supported.