cve-dashboard/docs/jira-api-use-cases.md

Jira REST API Use Cases — STEAM Security Dashboard

Overview

The STEAM Security Dashboard is a self-hosted vulnerability management tool used by the NTS-AEO-STEAM and NTS-AEO-ACCESS-ENG teams. It integrates with Jira Data Center to create, track, and sync vulnerability remediation tickets linked to CVE records.

All API calls are made from a single Node.js backend process. The integration uses Basic Auth with a service account and enforces Charter's posted rate limits client-side.

---

Charter Compliance Summary

Requirement	Implementation
Authentication	Basic Auth with service account (JIRA_API_USER + JIRA_API_TOKEN)
Rate limit — daily	Client-side enforced: 1 440 requests/day max
Rate limit — burst	Client-side enforced: 60 requests/minute max
Inter-request delay — GETs	1 second minimum between GET requests
Inter-request delay — writes	2 seconds minimum between PUT/POST/DELETE requests
Explicit field lists	Every GET includes ?fields= parameter; /rest/api/2/field is blocked
No bulk updates	Issues are updated one at a time; /rest/api/2/issue/bulk is blocked
Bulk reads via JQL	Multi-ticket sync uses a single GET /rest/api/2/search with JQL query parameters, not per-issue GETs
Single-issue fetch via JQL	GET /rest/api/2/search?jql=key="KEY" AND project=<KEY>&fields=...&maxResults=1
JQL scoping	All recurring JQL queries include updated >= -Xh clause and project = <KEY> scoping
maxResults cap	Search queries capped at 1 000 results per page

---

Use Cases

1. Connection Test

Endpoint	GET /rest/api/2/myself
Trigger	Admin clicks "Test Connection" on the Jira settings panel
Frequency	Manual, infrequent (a few times per day at most)
Purpose	Verify service account credentials and connectivity
Fields requested	Default (myself endpoint returns user profile)

2. Create Issue

Endpoint	POST /rest/api/2/issue
Trigger	User clicks "Create in Jira" from a CVE detail panel
Frequency	Manual, estimated 5–20 per day
Purpose	Create a vulnerability remediation ticket linked to a CVE/vendor pair
Fields sent	project.key, summary, issuetype.name, description
Notes	A local record is also created in the dashboard database linking the Jira key to the CVE

3. Get Single Issue

Endpoint	GET /rest/api/2/search?jql=key="ISSUE-KEY" AND project=<KEY>&fields=summary,status,assignee,created,updated,priority,issuetype,project,resolution&maxResults=1
Trigger	User clicks "Sync" on a single Jira ticket row
Frequency	Manual, estimated 10–30 per day
Purpose	Refresh a single ticket's status and summary from Jira via JQL search
Notes	Uses JQL-based lookup instead of single-issue GET per Charter compliance. Fields are always specified explicitly.

4. Update Issue

Endpoint	PUT /rest/api/2/issue/{issueKey}
Trigger	Future feature — local edits synced back to Jira
Frequency	Manual, estimated 5–10 per day when enabled
Purpose	Update issue summary or other fields from the dashboard
Notes	Issues are updated one at a time; bulk PUT is not used

5. Add Comment

Endpoint	POST /rest/api/2/issue/{issueKey}/comment
Trigger	Dashboard adds audit trail comments to linked tickets
Frequency	Automated on certain actions, estimated 5–15 per day
Purpose	Maintain an audit trail on the Jira ticket for compliance visibility

6. Get Transitions

Endpoint	GET /rest/api/2/issue/{issueKey}/transitions
Trigger	Dashboard checks available workflow transitions before moving a ticket
Frequency	Manual, paired with transition calls, estimated 5–10 per day
Purpose	Discover valid status transitions for the issue's current workflow state

7. Transition Issue

Endpoint	POST /rest/api/2/issue/{issueKey}/transitions
Trigger	User moves a ticket to a new status from the dashboard
Frequency	Manual, estimated 5–10 per day
Purpose	Move ticket through workflow states (e.g., Open to In Progress to Closed)

8. JQL Search (Bulk Sync)

Endpoint	GET /rest/api/2/search?jql=...&fields=...&maxResults=...&startAt=...
Trigger	Admin clicks "Sync All" on the Jira tickets panel
Frequency	Manual, estimated 1–3 times per day
Purpose	Bulk-refresh all tracked tickets in a single request instead of per-issue GETs
JQL pattern	key in ("KEY-1", "KEY-2", ...) AND updated >= -24h AND project = <KEY>
Fields requested	summary, status, assignee, created, updated, priority, issuetype, project, resolution
Batch size	100 keys per JQL query; multiple batches if needed
Notes	Uses GET with URL-encoded query parameters per Charter compliance. Stops early if rate limit budget is running low (burst remaining <= 5 or daily remaining <= 10)

9. Issue Lookup

Endpoint	GET /rest/api/2/search?jql=key="ISSUE-KEY" AND project=<KEY>&fields=...&maxResults=1
Trigger	User looks up a Jira issue by key from the dashboard search
Frequency	Manual, estimated 5–15 per day
Purpose	Quick lookup of any Jira issue to view its current state via JQL search

---

Estimated Daily API Usage

Operation	Estimated calls/day	Method	Delay enforced
Connection test	2–5	GET	1s
Create issue	5–20	POST	2s
Get single issue	10–30	GET	1s
Update issue	5–10	PUT	2s
Add comment	5–15	POST	2s
Get transitions	5–10	GET	1s
Transition issue	5–10	POST	2s
JQL search (sync)	1–5	GET	1s
Issue lookup	5–15	GET	1s
Total estimated	43–120

Well within the 1 440/day limit. Burst usage stays under 60/minute due to enforced inter-request delays.

---

Blocked Endpoints

The integration explicitly blocks these endpoints to comply with Charter policy:

• /rest/api/2/field — field metadata is never queried; fields are specified in code
• /rest/api/2/issue/bulk — bulk updates are not used; issues are updated individually

---

Error Handling

• 429 responses: Surfaced to the user as "Rate limit exceeded. Try again later." No automatic retry.
• 5xx responses: Surfaced as "Jira API error" with the response body for debugging.
• Network failures: Caught and surfaced with the error message.
• Timeout: 15 second timeout per request; surfaced as a timeout error.

---

UAT Test Evidence

The UAT test script (backend/scripts/jira-uat-test.js) exercises all use cases listed above and produces a log file at backend/scripts/jira-uat-test.log. This log can be attached to or referenced in the ATLSUP approval ticket.

To run:

cd backend
node scripts/jira-uat-test.js