microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/agents/security/phase-reference.md
230lines · modecode
| 1 | --- |
| 2 | title: Phase Reference |
| 3 | description: Detailed reference for each of the Security Planner's six phases, including inputs, outputs, artifacts, and state transitions |
| 4 | sidebar_position: 5 |
| 5 | sidebar_label: Phase Reference |
| 6 | keywords: |
| 7 | - security planner |
| 8 | - phases |
| 9 | - threat modeling |
| 10 | - STRIDE |
| 11 | - standards mapping |
| 12 | tags: |
| 13 | - agents |
| 14 | - security |
| 15 | author: Microsoft |
| 16 | ms.date: 2026-03-11 |
| 17 | ms.topic: reference |
| 18 | estimated_reading_time: 8 |
| 19 | --- |
| 20 | |
| 21 | Each of the Security Planner's six phases has defined inputs, outputs, state transitions, and artifacts. This reference documents the details that govern how the agent moves through a complete security analysis. |
| 22 | |
| 23 | ## Phase Summary |
| 24 | |
| 25 | | Phase | Name | Key output | State fields updated | |
| 26 | |-------|--------------------|--------------------------|-------------------------------------------| |
| 27 | | 1 | Project Scoping | Scope definition | `entryMode`, `raiEnabled`, `aiComponents` | |
| 28 | | 2 | Bucket Analysis | Bucket classification | `bucketsCompleted` | |
| 29 | | 3 | Standards Mapping | Controls per bucket | `standardsMapped` | |
| 30 | | 4 | Security Model | Threat catalog | `riskSurfaceStarted` | |
| 31 | | 5 | Backlog Generation | Work items | `handoffGenerated` | |
| 32 | | 6 | Review & Handoff | Summary and RAI dispatch | `raiPlannerDispatched` | |
| 33 | |
| 34 | ## Phase 1: Project Scoping |
| 35 | |
| 36 | ### Purpose |
| 37 | |
| 38 | Capture the project's purpose, technology stack, deployment model, data classification, and compliance requirements. Detect AI/ML components that trigger downstream RAI assessment. |
| 39 | |
| 40 | ### Inputs |
| 41 | |
| 42 | * User responses to scoping questions (capture mode). |
| 43 | * PRD/BRD artifacts from `.copilot-tracking/` (From-PRD mode). |
| 44 | |
| 45 | ### Process |
| 46 | |
| 47 | The agent asks 3-5 questions per turn covering: |
| 48 | |
| 49 | * Project purpose and business context. |
| 50 | * Technology stack and programming languages. |
| 51 | * Deployment model (cloud, on-premises, hybrid). |
| 52 | * Data classification and sensitivity levels. |
| 53 | * Compliance and regulatory requirements. |
| 54 | * AI/ML component identification. |
| 55 | |
| 56 | ### Outputs |
| 57 | |
| 58 | * Completed scope definition in the plan file. |
| 59 | * AI/ML detection results stored in state (`raiEnabled`, `raiScope`, `raiTier`, `aiComponents`). |
| 60 | |
| 61 | ### State Transitions |
| 62 | |
| 63 | | Field | Before | After | |
| 64 | |----------------|--------|----------------------------------| |
| 65 | | `currentPhase` | 1 | 2 (on user confirmation) | |
| 66 | | `entryMode` | unset | `from-prd` or `capture` | |
| 67 | | `raiEnabled` | unset | `true` or `false` | |
| 68 | | `raiScope` | unset | `none`, `lightweight`, or `full` | |
| 69 | | `raiTier` | unset | `none` through `comprehensive` | |
| 70 | |
| 71 | ## Phase 2: Bucket Analysis |
| 72 | |
| 73 | ### Purpose |
| 74 | |
| 75 | Classify all application components into seven operational buckets with a cross-cutting overlay. |
| 76 | |
| 77 | ### The Seven Buckets |
| 78 | |
| 79 | | Bucket | Covers | |
| 80 | |-----------------------|--------------------------------------------------------| |
| 81 | | Infrastructure | Networking, compute, storage, cloud resources | |
| 82 | | DevOps / Platform-ops | CI/CD pipelines, deployment, monitoring | |
| 83 | | Build | Build systems, dependency management, artifact signing | |
| 84 | | Messaging | Queues, event buses, pub/sub, webhooks | |
| 85 | | Data | Databases, caches, data lakes, ETL pipelines | |
| 86 | | Web / UI / Reporting | Frontend apps, APIs, dashboards, reporting | |
| 87 | | Identity / Auth | Authentication, authorization, secrets management | |
| 88 | |
| 89 | The **GS (cross-cutting)** overlay captures concerns that span multiple buckets, such as logging, encryption at rest, and network segmentation. |
| 90 | |
| 91 | ### Process |
| 92 | |
| 93 | The agent walks through each bucket, asking which components belong to it, and identifies cross-cutting concerns. Components can belong to multiple buckets. |
| 94 | |
| 95 | ### State Transitions |
| 96 | |
| 97 | | Field | Before | After | |
| 98 | |--------------------|--------|----------------------------------| |
| 99 | | `currentPhase` | 2 | 3 (on user confirmation) | |
| 100 | | `bucketsCompleted` | `[]` | Populated with completed buckets | |
| 101 | |
| 102 | ## Phase 3: Standards Mapping |
| 103 | |
| 104 | ### Purpose |
| 105 | |
| 106 | Map each operational bucket to the relevant controls from OWASP Top 10, NIST 800-53, and CIS Benchmarks. |
| 107 | |
| 108 | ### Frameworks |
| 109 | |
| 110 | | Framework | Scope | Usage | |
| 111 | |----------------|---------------------------------|------------------------------------| |
| 112 | | OWASP Top 10 | Web application risks | Mapped to Web/UI and Data buckets | |
| 113 | | NIST 800-53 | Comprehensive security controls | Mapped across all buckets | |
| 114 | | CIS Benchmarks | Configuration baselines | Mapped to Infrastructure and Build | |
| 115 | |
| 116 | The agent dispatches the Researcher Subagent to perform WAF (Well-Architected Framework) and CAF (Cloud Adoption Framework) runtime lookups when cloud-hosted components are in scope. |
| 117 | |
| 118 | ### State Transitions |
| 119 | |
| 120 | | Field | Before | After | |
| 121 | |-------------------|--------|-------------------------------| |
| 122 | | `currentPhase` | 3 | 4 (on user confirmation) | |
| 123 | | `standardsMapped` | `[]` | Populated with mapped buckets | |
| 124 | |
| 125 | ## Phase 4: Security Model Analysis |
| 126 | |
| 127 | ### Purpose |
| 128 | |
| 129 | Perform STRIDE-based threat modeling per bucket, generating a structured threat catalog. |
| 130 | |
| 131 | ### STRIDE Categories |
| 132 | |
| 133 | <!-- cspell:disable --> |
| 134 | | Category | Question the threat answers | |
| 135 | |----------------------------|----------------------------------------------------------| |
| 136 | | **S**poofing | Can an attacker impersonate a legitimate user or system? | |
| 137 | | **T**ampering | Can data or code be modified without detection? | |
| 138 | | **R**epudiation | Can actions be denied or hidden? | |
| 139 | | **I**nformation Disclosure | Can sensitive data be exposed? | |
| 140 | | **D**enial of Service | Can the system be made unavailable? | |
| 141 | | **E**levation of Privilege | Can an attacker gain unauthorized access? | |
| 142 | <!-- cspell:enable --> |
| 143 | |
| 144 | ### Threat Identification Format |
| 145 | |
| 146 | Each threat receives a unique identifier in the format `T-{BUCKET}-{NNN}`, where `BUCKET` is the operational bucket abbreviation and `NNN` is a sequential number. |
| 147 | |
| 148 | ### Severity Rating |
| 149 | |
| 150 | Threats are rated using a likelihood-impact matrix: |
| 151 | |
| 152 | | Likelihood × Impact | Result | |
| 153 | |---------------------|----------| |
| 154 | | High × High | Critical | |
| 155 | | High × Medium | High | |
| 156 | | Medium × High | High | |
| 157 | | Medium × Medium | Medium | |
| 158 | | Low × any | Low | |
| 159 | |
| 160 | ### State Transitions |
| 161 | |
| 162 | | Field | Before | After | |
| 163 | |----------------------|---------|--------| |
| 164 | | `currentPhase` | 4 | 5 | |
| 165 | | `riskSurfaceStarted` | `false` | `true` | |
| 166 | |
| 167 | ## Phase 5: Backlog Generation |
| 168 | |
| 169 | ### Purpose |
| 170 | |
| 171 | Convert identified threats into actionable backlog items with acceptance criteria and autonomy tier assignments. |
| 172 | |
| 173 | ### Work Item Formats |
| 174 | |
| 175 | | Platform | ID format | Example | |
| 176 | |----------|------------------|------------------| |
| 177 | | ADO | `WI-SEC-{NNN}` | `WI-SEC-001` | |
| 178 | | GitHub | `{{SEC-TEMP-N}}` | `{{SEC-TEMP-1}}` | |
| 179 | |
| 180 | ### Autonomy Tiers |
| 181 | |
| 182 | | Tier | Human involvement | Typical use | |
| 183 | |---------|----------------------------|-----------------------------------------| |
| 184 | | Full | None required | Low-risk configuration changes | |
| 185 | | Partial | Review and approve | Default for most security remediations | |
| 186 | | Manual | Human plans and implements | Architectural changes, policy decisions | |
| 187 | |
| 188 | ### State Transitions |
| 189 | |
| 190 | | Field | Before | After | |
| 191 | |--------------------|-------------------------------|--------------------| |
| 192 | | `currentPhase` | 5 | 6 | |
| 193 | | `handoffGenerated` | `{ado: false, github: false}` | Updated per target | |
| 194 | |
| 195 | ## Phase 6: Review and Handoff |
| 196 | |
| 197 | ### Purpose |
| 198 | |
| 199 | Validate the complete analysis, present a summary, and trigger RAI Planner dispatch when AI/ML components are in scope. |
| 200 | |
| 201 | ### Review Checklist |
| 202 | |
| 203 | The agent validates: |
| 204 | |
| 205 | * All operational buckets have been classified. |
| 206 | * Standards are mapped for each bucket. |
| 207 | * Threats exist for each bucket with severity ratings. |
| 208 | * Backlog items are linked to their source threats. |
| 209 | * AI/ML components (if detected) have been flagged for RAI assessment. |
| 210 | |
| 211 | ### RAI Dispatch |
| 212 | |
| 213 | When `raiEnabled` is `true`, the agent: |
| 214 | |
| 215 | 1. Presents the RAI Planner agent path (`.github/agents/rai-planning/rai-planner.agent.md`). |
| 216 | 2. Suggests the `from-security-plan` entry mode. |
| 217 | 3. Identifies the state file and project slug for the RAI Planner to consume. |
| 218 | 4. Sets `raiPlannerDispatched` to `true` in state. |
| 219 | |
| 220 | ### State Transitions |
| 221 | |
| 222 | | Field | Before | After | |
| 223 | |------------------------|---------|--------| |
| 224 | | `currentPhase` | 6 | 6 | |
| 225 | | `raiPlannerDispatched` | `false` | `true` | |
| 226 | |
| 227 | <!-- markdownlint-disable MD036 --> |
| 228 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 229 | then carefully refined by our team of discerning human reviewers.* |
| 230 | <!-- markdownlint-enable MD036 --> |
| 231 | |