Jira
Proofroom reads three kinds of evidence from Jira Cloud or Jira Data Center (8.14 or later), each filed once per period as one evidence item with a summary and the full records as JSON.
| Collector | Every | What it shows | Suggested controls |
|---|---|---|---|
| Change tickets | month | Issues matching your change query that were resolved in the period (or moved to a Done status in it, when the workflow sets no resolution): reporter, assignee, created, resolved, every status change (who, when, from, to) and, when you name an approval status, who approved each and whether that was someone other than the reporter or assignee. | PCI DSS 6.5.1, 6.5.2; SOC 2 CC8.1 |
| Security issues | month | Issues with your security label created or closed in the period (resolved, or moved to a Done status with no resolution, as change tickets are): type, priority, status, days open, and counts of created, resolved, open at the end and the median days to resolve. | PCI DSS 12.10.1; SOC 2 CC7.3, CC7.4 (or 6.3.1; CC7.4 when the tickets are vulnerabilities) |
| Access review | quarter | Project administrators of every project the account can administer (users and groups), and, with the Atlassian organization admin API key, site and organization admins with their last-active dates. Projects the account may not administer are named as skipped. | PCI DSS 7.2.4; SOC 2 CC6.2, CC6.3 |
Proofroom keeps the issue key, the first 120 characters of the summary, type, status, priority, labels, dates and people’s display names with their Jira ids. It never stores descriptions, comments, attachments or email addresses.
1. Create a read-only account
Use a dedicated account (for example proofroom@your-domain) rather than a person’s.
- Give it Browse projects on the projects your change tickets and security issues live in, and nothing else. It never creates or edits issues.
- If an issue is hidden by issue-level security, the account cannot see it and it is missing from the evidence: grant the account the security level, or keep change and security issues outside restricted levels.
2. Create the credential
- Jira Cloud: sign in as the account, open https://id.atlassian.com/manage-profile/security/api-tokens and create an API token. Proofroom signs in with the account’s email and this token.
- Jira Data Center: sign in as the account, open Profile → Personal Access Tokens and create a token. Set an expiry that matches your rotation policy and put a reminder in your calendar: an expired token fails every run.
3. Add the integration
Integrations → Catalogue → Jira → Connect:
| Field | Value |
|---|---|
| Flavour | cloud or data-center |
| Base URL | https://<site>.atlassian.net, or your Data Center address (with its context path, if any); must be https (plain http only for localhost) |
| Cloud only: the account’s email | |
| API token | The API token (Cloud) or personal access token (Data Center) |
| Change JQL | The JQL that finds change tickets, for example project = CHG or issuetype = Change. A trailing ORDER BY is ignored. |
| Approval status | Optional. The workflow status that means a change was approved, for example Approved. Leave it blank if your workflow has none: the evidence then lists the status history without judging approvals. |
| Security label | The label on security issues (default security). |
What these tickets are (securityTickets) |
incidents files the security issues against PCI DSS 12.10.1 and SOC 2 CC7.3, CC7.4; vulnerabilities (security bugs) against PCI DSS 6.3.1 and SOC 2 CC7.4 (default incidents). Changing it moves the collector’s mapping too, unless the mapping was changed by hand. |
Press Test connection: it signs in, runs your change query once and checks that at least one issue the account can see carries the security label, so a typo in the JQL or the label shows here rather than at the first run. A label no issue carries is a warning, not a failure: change tickets and the access review still work, and the Security issues run fails until an issue carries it. Then map the suggested controls on each collector card.
How the evidence is judged
- Approved by someone else: the last move into the approval status, at or before resolution, was made by someone who is neither the reporter nor the assignee.
- Self-approved: that move was made by the reporter or the assignee.
- No approval: the issue never reached the approval status before it was resolved, or only automation moved it there (a change with no author).
- Done without a resolution: some workflows move a ticket to Done without setting a resolution. Such a ticket counts in the period it reached a Done status (on Cloud, Jira’s status category change date; on Data Center, its last move into its current status). A ticket with a resolution is always counted by its resolution date, so no ticket is counted twice. Its Resolved column reads “(Done, no resolution)”.
- Jira reads JQL dates in the account’s time zone, so Proofroom asks for a day either side of the period and keeps only issues resolved (or, for security issues, created or resolved) inside it.
Jira Service Management approvals and the access review
Approvals. On Jira Cloud, change tickets in a Jira Service Management project are judged by their approvals: a request is approved when an approval was decided “approved” by someone other than its reporter or assignee. A request with no approval step, and other tickets, use the approval status you configure, if any. Tickets in a Service Management project that are not customer requests are named as unread. The account needs agent access to the service projects: if Jira refuses it the service desk list or a request’s approvals (HTTP 403), the run fails rather than judge those requests by their status alone. A site without Service Management (HTTP 404) is judged by the approval status.
Access review permissions. Listing a project’s administrators needs Administer Projects on that project, or Administer Jira for every project; there is no read-only role for this. Projects the account may not administer are skipped and named. Proofroom reads the Administrators role from the projects themselves, so a per-project admin is enough. Proofroom only reads.
Site and organization admins (Cloud): an organization admin creates an API key in Atlassian Administration →
Settings → API keys with read:directories:admin, and enters the organization ID and key in the integration. Without
them, the access review lists project administrators only. Last-active dates are for Jira only.
When a run fails
A run either collects everything or fails and is retried at the next tick; nothing partial is filed. The run history names the cause:
changeJql was refusedorsecurityLabel was refused: Jira rejected the query (HTTP 400). Fix the field and run again.credentials refused: the token is wrong, expired or revoked, or the account lost access (HTTP 401 or 403).no issue the account can see carries the label: no issue the account can see has the security label, so the evidence would wrongly say there were no security issues. Check the label’s spelling, or the account’s access.may not read Jira Service Managementormay not read this request's approvals: give the account agent access to the service projects, or leave them out of the change JQL.Run time budget exhausted: the period holds more issues than one ten-minute run can read. Narrow the change JQL.