# 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 |