From ccc99439d5faf63b9d8cb7520cc9e8adfaa3b89a Mon Sep 17 00:00:00 2001 From: kitos Date: Wed, 8 Jul 2026 11:30:33 +0200 Subject: [PATCH] docs: add Jira/Tempo service account requirements and use cases Requirements + use-case document to support requesting a dedicated Jira/Tempo service account for the Purple Team project, to replace the personal-employee-account credentials currently configured as Aegis's Jira integration identity. Grounded in the actual implemented integration (ticket lifecycle sync, Tempo worklog attribution, account auto-discovery) rather than the aspirational design. --- ...JIRA_TEMPO_SERVICE_ACCOUNT_REQUIREMENTS.md | 219 ++++++++++++++++++ 1 file changed, 219 insertions(+) create mode 100644 docs/JIRA_TEMPO_SERVICE_ACCOUNT_REQUIREMENTS.md diff --git a/docs/JIRA_TEMPO_SERVICE_ACCOUNT_REQUIREMENTS.md b/docs/JIRA_TEMPO_SERVICE_ACCOUNT_REQUIREMENTS.md new file mode 100644 index 0000000..fecb03e --- /dev/null +++ b/docs/JIRA_TEMPO_SERVICE_ACCOUNT_REQUIREMENTS.md @@ -0,0 +1,219 @@ +# 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@`) 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@`), 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 |