Aegis/docs/JIRA_TEMPO_SERVICE_ACCOUNT_REQUIREMENTS.md

Aegis Platform — Jira & Tempo Service Account

Requirements and Use Cases

Document type: Security Architecture Request — Requirements & Use Cases System: Aegis (Purple Team MITRE ATT&CK Coverage Platform) Version: 1.0 Date: 2026-07-08 Requested by: Aegis Platform Owner / Administrator Purpose: Justify and specify a dedicated Jira/Tempo service account for the Purple Team project, to be used exclusively by the Aegis backend for automated ticket management and time tracking.

---

1. Purpose and Background

Aegis is an internal platform used by the Red Team and Blue Team to plan, execute, and validate MITRE ATT&CK coverage tests. Every test and campaign tracked in Aegis is mirrored as a Jira issue in the Purple Team project, and the time operators spend executing/evaluating tests is logged in Tempo against those issues.

Current architectural model (already implemented): Aegis centralizes all Jira and Tempo interaction behind a single set of administrator-configured credentials. Individual Red/Blue Team members (red_tech, blue_tech, red_lead, blue_lead) do not authenticate to Jira or Tempo themselves, do not need personal API tokens, and do not need individual Tempo licenses. All ticket creation, status transitions, field updates, comments, attachments, and time-log entries are performed by the Aegis backend on their behalf, using one integration identity.

The problem this document addresses: that single integration identity is currently configured using the credentials of a real, individual employee's Atlassian account (email + personal API token), entered by the platform administrator into Aegis's Settings page. This is not appropriate for a production automation integration:

• The integration breaks if that employee's password/token is rotated, their account is deprovisioned, or they leave the team.
• Actions performed by Aegis in Jira's audit trail are attributed to a named individual rather than to "the Aegis system," which is misleading during incident review or access audits.
• It requires a human's ongoing personal credential to remain valid for an unrelated automated system, which is a standing access-management risk (the account holder's other permissions, MFA state, and offboarding become entangled with the integration's uptime).

Request: Provision a dedicated, non-human Jira/Tempo service account (e.g. svc-aegis-integration@<domain>) scoped to the Purple Team project, for the Aegis backend to use as its sole Jira/Tempo identity, replacing the current personal-account configuration.

---

2. Actors

Actor	Type	Description
Aegis Backend	System / automated	The FastAPI service that performs all Jira/Tempo API calls. Authenticates once, centrally, using the requested service account's credentials (email + API token).
Aegis Administrator	Human, admin role	Configures the service account's credentials into Aegis (Settings → Jira), and the Purple Team project's parent ticket structure. Does not use the service account interactively.
Red/Blue Team Operator	Human, red_tech/blue_tech role	Executes tests / evaluates detections in Aegis. Never touches Jira or Tempo directly; their actions in Aegis trigger the backend to act in Jira/Tempo on their behalf.
Red/Blue Team Lead	Human, red_lead/blue_lead role	Reviews and validates tests in Aegis; also has no direct Jira/Tempo interaction.
Jira / Tempo (Atlassian Cloud)	External system	The target systems the service account authenticates against.

---

3. Use Cases

Each use case below is a real, already-implemented workflow in Aegis. They collectively define the operations the requested service account must be able to perform.

UC-01 — Create a Jira Epic for a new Campaign

• Trigger: A manager approves a Campaign (or an admin activates one).
• Actor: Aegis Backend (on behalf of the approving manager/admin).
• Preconditions: Jira integration is enabled and configured; the campaign has no existing Jira link.
• Flow: Aegis creates a Jira issue of type Epic in the Purple Team project, under the configured parent Initiative ticket, with a summary, description, an Epic Name field, and a start-date field populated from the campaign's scheduled start date.
• Postcondition: A new Epic exists in Jira; its key is stored in Aegis and used as the parent for all tests belonging to that campaign.

UC-02 — Create a Jira Task for a Test

• Trigger: A test is created (either inside an already-ticketed campaign, or as a standalone test).
• Actor: Aegis Backend.
• Flow: Aegis creates a Jira issue of type Task, parented either under the campaign's own Epic (UC-01) or under a fixed "standalone tests" parent Epic. The issue includes a summary, a proof-of-concept/description field, the MITRE technique ID, severity, an initial data-sensitivity classification, and a start-date field.
• Postcondition: A new Task exists in Jira, linked 1:1 to the Aegis test record.

UC-03 — Synchronize Red Team execution lifecycle

• Trigger: The assigned operator starts execution, and later submits their work for review.
• Actor: Aegis Backend.
• Flow: On start, Aegis sets the Jira issue's Red Team start-date field and transitions its status to "In Progress", and assigns the issue to the operator's Atlassian account. On submission, Aegis sets the Red Team end-date field, the Attack Success outcome, and posts a status comment.
• Postcondition: The Jira issue reflects the Red Team phase's timing and outcome without any manual data entry by the operator.

UC-04 — Synchronize Blue Team evaluation lifecycle

• Trigger: The assigned Blue Team operator starts evaluating detection, and later submits their findings.
• Actor: Aegis Backend.
• Flow: Mirrors UC-03 for the Blue Team phase — sets Blue Team start/end-date fields, the Attack Detected and Attack Contained outcomes, and computed time-to-detect / time-to-contain metrics (in hours) on the Jira issue.
• Postcondition: The Jira issue carries a complete, timestamped record of both teams' work and outcomes.

UC-05 — Reflect a Hold or Pause on the Jira issue

• Trigger: A test is put on hold (blocked externally) or paused (operator-initiated pause) in Aegis, and later resumed.
• Actor: Aegis Backend.
• Flow: Aegis transitions the Jira issue's status to "Blocked" (hold) or "On Hold" (pause), with an explanatory comment naming the acting operator, and transitions back to "In Progress" on resume.
• Postcondition: Jira's status always reflects the real operational state of the test, visible to anyone watching the ticket without needing access to Aegis.

UC-06 — Attach evidence to the Jira issue

• Trigger: An operator uploads evidence (screenshots, logs, PCAPs) to a test in Aegis.
• Actor: Aegis Backend.
• Flow: Aegis uploads the same evidence file as an attachment on the linked Jira issue.
• Postcondition: Evidence is available directly on the Jira ticket for anyone reviewing it, without needing Aegis access.

UC-07 — Log time spent in Tempo, attributed to the operator

• Trigger: An operator completes a timed phase (Red Team execution or Blue Team evaluation).
• Actor: Aegis Backend, acting on behalf of the operator.
• Preconditions: Tempo integration is configured; the operator's Atlassian account ID is known to Aegis (see UC-08).
• Flow: Aegis computes the elapsed duration (rounded up to the nearest minute, minimum 1 minute), and creates a Tempo worklog against the relevant Jira issue, attributed to the operator's Atlassian account (accountId) even though the API call itself is authenticated by the service account.
• Postcondition: Tempo shows accurate, per-person time tracking for every test phase, without operators ever opening Tempo or holding a personal Tempo API token.
• Key requirement: this is the primary justification for the service account — Tempo's API must allow one authenticated identity (the service account) to create worklogs on behalf of other named users, not just for itself.

UC-08 — Auto-discover an operator's Atlassian account ID

• Trigger: A user logs into Aegis.
• Actor: Aegis Backend.
• Flow: Aegis looks up the user's Atlassian account ID by searching Jira's user directory using the operator's email address, and stores it against their Aegis profile for use in UC-03/UC-04 (assignment) and UC-07 (worklog attribution).
• Postcondition: The operator never has to manually supply or configure any Jira/Tempo identifier themselves.

UC-09 — Assign the Jira issue to the responsible operator or reviewer

• Trigger: A test moves to an execution or review stage with a specific person responsible.
• Actor: Aegis Backend.
• Flow: Aegis assigns the Jira issue to the relevant operator's or reviewer's Atlassian account (resolved in UC-08).
• Postcondition: Jira's "Assignee" field always matches who is actually responsible for the work in Aegis.

---

4. Functional Requirements

Derived directly from the use cases above.

ID	Requirement
FR-01	The service account MUST be able to create issues of type Epic and Task in the Purple Team project.
FR-02	The service account MUST be able to set/edit the following fields on issues it creates or manages: summary, description, Epic Name, start date, MITRE technique ID (custom field), severity (custom field), data sensitivity/classification (custom field), Attack Success / Attack Detected / Attack Contained outcomes (custom fields), time-to-detect and time-to-contain (custom fields), Red/Blue Team start and end dates (custom fields).
FR-03	The service account MUST be able to transition issues through the workflow statuses used by the Purple Team process, at minimum: In Progress, On Hold, Blocked, plus whatever "resolved/done" statuses close out a Task/Epic.
FR-04	The service account MUST be able to add comments to issues.
FR-05	The service account MUST be able to add attachments to issues.
FR-06	The service account MUST be able to assign issues to other named users in the project (not only to itself).
FR-07	The service account MUST be able to search/resolve a user's Atlassian account ID from their email address (directory lookup), scoped to users who are members of the organization.
FR-08	The service account MUST be able to create Tempo worklogs against Purple Team project issues on behalf of other named users (i.e., the worklog's author/account attribution is a different person than the account authenticating the API call).
FR-09	The service account MUST have a valid Jira Cloud license/seat, since Tempo worklog creation requires the underlying Jira account to be licensed.
FR-10	The service account MUST support generation of a long-lived API token (or OAuth 2.0 app credential, if the organization's Atlassian plan supports scoped app access instead of personal API tokens) for non-interactive, server-to-server authentication — it will never be used for interactive human login.

---

5. Non-Functional / Security Requirements

ID	Requirement	Rationale
NFR-01	Least privilege — project-scoped. The service account's permissions MUST be scoped to the Purple Team project only. It MUST NOT hold Jira site-admin, organization-admin, or Tempo global-administrator rights beyond what FR-01–FR-08 require.	Limits blast radius if the credential is ever compromised or misused.
NFR-02	Not tied to an individual. The account MUST be a dedicated, non-human identity (e.g. svc-aegis-integration@<domain>), not a repurposed personal employee account.	Removes the coupling between an employee's lifecycle/credentials and the integration's availability; makes Jira audit-log attribution accurate ("Aegis" acted, not a specific person).
NFR-03	No interactive login / no MFA-interactive flow required. The account is used exclusively via API token (or OAuth app credential) from a server process; it does not need to pass through browser-based SSO/MFA prompts.	It is a machine identity, not a human one; interactive login should be disabled or unnecessary for this account where the platform supports that distinction.
NFR-04	Credential storage. The API token/secret MUST be stored only in the Aegis backend's system configuration store (server-side; not exposed to any frontend, and redacted from the platform's own configuration-backup export feature — see fix note below).	Prevents accidental disclosure via UI, logs, or backup files.
NFR-05	Rotation support. The credential MUST be rotatable (token regenerated / reissued) without requiring a code change — Aegis re-reads it from configuration at call time.	Standard credential-hygiene requirement; supports periodic rotation and immediate revocation if needed.
NFR-06	Auditability. All actions the service account performs in Jira/Tempo are already accompanied, on the Aegis side, by an audit trail of which human user's action triggered them (stored in Aegis, not in Jira). Jira/Tempo's own logs will show the service account as the acting principal; Aegis's logs supply the human attribution. Both MUST remain available for incident/compliance review.	Preserves non-repudiation even though Jira sees a single technical actor.
NFR-07	No secret sharing with human users. The service account's credentials MUST NOT be distributed to, or usable interactively by, Red/Blue Team operators or leads — only the Aegis backend process holds them.	Consistent with the "transparent to end users" design goal; operators should never need or be able to authenticate as this account.

Note on NFR-04: during preparation of this document, a related defect was found and has already been fixed — Aegis's own admin configuration export/backup feature had a stale redaction rule that would have exported the live Jira/Tempo admin API tokens in plaintext inside the backup JSON file. This has been corrected and covered by a regression test as of this document's date, independent of which account (personal or service) holds the credential.

---

6. Requested Access / Permission Scope Summary

System	Scope	Permissions needed
Jira	Purple Team project only	Browse Project; Create Issues (Epic, Task); Edit Issues; Transition Issues (all statuses used by the Purple Team workflow); Add Comments; Create Attachments; Assign Issues (including assigning to other users, which typically also requires those users to be "assignable" in the project).
Jira (org-level, minimal)	Directory read only	Ability to search/resolve users by email via the user-search API, for account-ID auto-discovery (UC-08). No other org-admin capability.
Tempo	Purple Team project's issues	Ability to create/manage worklogs attributed to other named users (not just the account's own worklogs). In Tempo's permission model this typically requires a Team Lead or Administrator-level role scoped to the relevant team(s)/project — please map this functional need to the least-privileged Tempo role that satisfies it.
License	1 seat	Standard Jira Cloud license (required for the account to be a valid worklog author in Tempo).

---

7. Data Flow Summary

Aegis Backend  ──(HTTPS, API token auth)──▶  Jira Cloud REST API
     │                                            │
     │  create/edit/transition/comment/attach     │  writes to Purple Team project
     │  issues; resolve user account IDs          │
     │                                            ▼
     │                                       Jira Issue (Epic/Task)
     │
     └──(HTTPS, API token auth)──▶  Tempo REST API
                                          │
                                          │  create worklog, accountId = operator
                                          ▼
                                    Tempo Worklog (attributed to operator,
                                    authenticated by service account)

No human user ever authenticates directly to Jira or Tempo as part of this flow; all traffic originates from the Aegis backend server.

---

8. Risks and Mitigations

Risk	Mitigation
Service account credential leaked (e.g. via logs, backup export, or code)	Stored only in server-side configuration; redacted from Aegis's own config-export feature (fixed); never returned by any Aegis API response; rotate on suspicion of exposure (NFR-05).
Service account granted excessive project/org rights over time ("permission creep")	Scope request explicitly to the Purple Team project (Section 6); periodic access review recommended alongside other service accounts.
Loss of accountability for actions taken "as" the service account	Mitigated by NFR-06 — Aegis retains its own audit log mapping every Jira/Tempo action back to the human user whose action in Aegis triggered it.
Account accidentally used for interactive human login	Request the account be provisioned as a non-interactive/service identity if the organization's Atlassian plan distinguishes these; otherwise, do not distribute its password to any individual and enforce API-token-only usage by policy.

---

Appendix A — Custom Field Reference

Fields written by Aegis onto Jira issues in the Purple Team project (for the security/Jira administrator's reference when granting Edit-Issue field-level permissions, if field-level security is in use):

Field	Purpose
Epic Name	Required field when creating an Epic (Campaign).
Start Date	Campaign/Test scheduled start.
MITRE Technique ID (TTP)	The ATT&CK technique the test targets.
Severity	Test severity rating.
Data Sensitivity	Initial data-classification of the test's content.
Red Team Start Date / End Date	Timestamps for the offensive execution phase.
Blue Team Start Date / End Date	Timestamps for the defensive evaluation phase.
Attack Success	Outcome of the Red Team's attempt (Yes/No/Partial).
Attack Detected	Whether the Blue Team detected the attack (Yes/No/Partial).
Attack Contained	Whether the attack was contained (Yes/No/Partial).
Time to Detect / Time to Contain	Computed duration metrics, in hours.
Proof of Concept / Description	Free-text procedure/evidence summary.

Appendix B — Current vs. Requested State

	Current state	Requested state
Identity used by Aegis	A real employee's personal Atlassian account, entered as admin/API-token in Aegis Settings	Dedicated non-human service account
Continuity risk	Breaks on password change, token expiry, or employee offboarding	Independent of any individual's employment/credential lifecycle
Audit trail in Jira	Shows a named individual performing thousands of automated actions	Shows the service account clearly identifiable as "the Aegis integration"
End-user experience	Unchanged — already transparent, operators need no personal Jira/Tempo access	Unchanged
Permissions held	Whatever that individual's account happens to have (potentially broader than needed)	Explicitly scoped to Section 6