|
| 1 | +# Governance and responsible operation |
| 2 | + |
| 3 | +Use this guide to decide what data GPT-RAG may process, who owns each |
| 4 | +control, and what evidence an operator should preserve for security reviews |
| 5 | +and incident investigations. |
| 6 | + |
| 7 | +!!! warning "Audit trail implementation is not released" |
| 8 | + The governance practices on this page can be applied today. The correlated |
| 9 | + [Audit Contract v1](governance_audit_contract_v1.md) is reconciled with |
| 10 | + orchestrator pull request #277, but that implementation is not in a released |
| 11 | + runtime. It is disabled by default and still needs GPT-RAG umbrella |
| 12 | + deployment integration. Do not configure it until the runtime release and |
| 13 | + integration are complete. |
| 14 | + |
| 15 | +## Why this matters |
| 16 | + |
| 17 | +During a review or incident, an operator should be able to answer practical |
| 18 | +questions without searching unrelated logs: |
| 19 | + |
| 20 | +- What route or orchestration strategy handled the request? |
| 21 | +- Which grounding sources and tools were selected? |
| 22 | +- Did each tool call complete, fail, time out, or get cancelled? |
| 23 | +- Was an outcome produced or rejected? |
| 24 | +- What data classes could have entered telemetry? |
| 25 | +- Who configured access, retention, deletion, and export? |
| 26 | + |
| 27 | +GPT-RAG already uses logs, traces, metrics, and source references. Those signals |
| 28 | +are useful, but current releases do not provide the versioned audit contract |
| 29 | +described in issue |
| 30 | +[#571](https://github.com/Azure/GPT-RAG/issues/571). The unreleased contract |
| 31 | +correlates operational metadata while leaving prompts, responses, source |
| 32 | +excerpts, tool arguments, and tool results out of the default event stream. |
| 33 | + |
| 34 | +```mermaid |
| 35 | +flowchart LR |
| 36 | + Request[User request] --> Route[Route and source selection] |
| 37 | + Route --> Tools[Retrieval and tools] |
| 38 | + Tools --> Outcome[Outcome] |
| 39 | + Route -. unreleased audit events .-> Evidence[Correlated operational evidence] |
| 40 | + Tools -. unreleased audit events .-> Evidence |
| 41 | + Outcome -. unreleased audit events .-> Evidence |
| 42 | +``` |
| 43 | + |
| 44 | +## What GPT-RAG can and cannot establish |
| 45 | + |
| 46 | +GPT-RAG cannot determine whether a deployment or use case is legally compliant. |
| 47 | +It does not certify a system, enforce an external governance framework, provide |
| 48 | +a complete legal crosswalk, or replace an adopter's legal, privacy, security, |
| 49 | +risk, records-management, or human-oversight processes. |
| 50 | + |
| 51 | +Clear responsibilities, documented data practices, correlated audit events, |
| 52 | +configurable retention, and reviewable technical evidence can help adopters |
| 53 | +perform their own: |
| 54 | + |
| 55 | +- security and architecture reviews; |
| 56 | +- incident investigations; |
| 57 | +- privacy, risk, and audit assessments; |
| 58 | +- [NIST AI Risk Management Framework](https://www.nist.gov/itl/ai-risk-management-framework) |
| 59 | + activities; and |
| 60 | +- assessments involving the |
| 61 | + [EU AI Act](https://eur-lex.europa.eu/eli/reg/2024/1689/oj). |
| 62 | + |
| 63 | +These are inputs to an adopter-led assessment, not proof of conformance or a |
| 64 | +legal conclusion. Applicability and evidence requirements depend on the |
| 65 | +deployment, data, users, jurisdiction, and intended use. |
| 66 | + |
| 67 | +## Intended use and limitations |
| 68 | + |
| 69 | +The governance baseline is intended for teams that deploy GPT-RAG as a |
| 70 | +retrieval-augmented assistant and need a repeatable way to manage enterprise |
| 71 | +data and operational evidence. |
| 72 | + |
| 73 | +Do not assume that: |
| 74 | + |
| 75 | +- a citation proves that an answer is correct or complete; |
| 76 | +- a recorded event proves that the producer behaved correctly; |
| 77 | +- missing telemetry proves that an action did not occur; |
| 78 | +- an opaque identifier is anonymous in every environment; |
| 79 | +- permission trimming replaces source-system authorization review; |
| 80 | +- a preview grounding capability is production-ready because it has audit |
| 81 | + events; |
| 82 | +- retention in Azure Monitor satisfies a records-management obligation; or |
| 83 | +- technical evidence establishes legal compliance. |
| 84 | + |
| 85 | +The unreleased audit trail is best-effort telemetry. Sampling, exporter failures, |
| 86 | +process termination, asynchronous boundaries, disabled instrumentation, and |
| 87 | +upstream systems can create evidence gaps. Events are asserted by the producing |
| 88 | +GPT-RAG process. They are not independently attested, cryptographically signed, |
| 89 | +tamper-evident, or nonrepudiable. |
| 90 | + |
| 91 | +## Shared responsibility |
| 92 | + |
| 93 | +One organization may perform more than one role. Assign each responsibility |
| 94 | +explicitly before production use. |
| 95 | + |
| 96 | +| Role | Responsibilities | |
| 97 | +| --- | --- | |
| 98 | +| GPT-RAG maintainers | Publish accurate behavior and limitations; provide privacy-conscious defaults; version the audit contract; test schema compatibility, redaction, and bounds; preserve compatibility or publish migration guidance. | |
| 99 | +| Deployer or platform team | Select the deployment topology; configure identities, networking, Key Vault, Azure Monitor, retention, export, and backup; apply least-privilege RBAC; keep secrets out of configuration and telemetry; verify regional and service boundaries. | |
| 100 | +| Runtime operator | Monitor health, cost, sampling, and evidence gaps; review access regularly; investigate incidents; validate deletion and export procedures; canary changes; roll back audit emission if it harms reliability. | |
| 101 | +| Adopter, business owner, or data owner | Define the intended and prohibited uses; assert the right to use each data source; classify data; set minimization and retention policy; determine legal and regulatory obligations; define human oversight, risk acceptance, and user communication. | |
| 102 | + |
| 103 | +## Govern ingested and connected data |
| 104 | + |
| 105 | +Apply these controls to indexed content and to sources queried at request time. |
| 106 | +That includes Blob Storage, Azure AI Search, SharePoint, OneLake, specific Work |
| 107 | +IQ, Fabric IQ, Foundry IQ and web grounding integrations, and remote MCP |
| 108 | +servers. |
| 109 | + |
| 110 | +### Before connecting a source |
| 111 | + |
| 112 | +1. **Record provenance.** Identify the system of record, data owner, ingestion |
| 113 | + or query path, refresh cadence, and applicable permission model. |
| 114 | +2. **Obtain a right-to-use assertion.** The operator or data owner should record |
| 115 | + that the organization is authorized to process the source for the intended |
| 116 | + users and purpose. GPT-RAG cannot make this determination. |
| 117 | +3. **Classify the data.** Apply the organization's classification for personal, |
| 118 | + confidential, regulated, export-controlled, or other sensitive content. |
| 119 | +4. **Minimize scope.** Include only the sites, containers, indexes, tables, |
| 120 | + fields, date ranges, and tools required by the use case. |
| 121 | +5. **Define retention and deletion.** Document how source data, indexes, |
| 122 | + conversation history, caches, and backups are removed. Test the process. |
| 123 | +6. **Review access.** Use source-system permissions, managed identities, |
| 124 | + delegated access, and GPT-RAG retrieval controls as applicable. Test with |
| 125 | + representative allowed and denied users. |
| 126 | +7. **Review data movement.** Confirm region, service, public internet, and |
| 127 | + cross-boundary behavior for every enabled source. |
| 128 | + |
| 129 | +### Sensitive content |
| 130 | + |
| 131 | +Treat retrieved content as sensitive whenever its source classification says |
| 132 | +so. Grounding can copy excerpts into prompts, responses, conversation history, |
| 133 | +dependency telemetry, or troubleshooting logs. Permission trimming reduces |
| 134 | +unauthorized retrieval, but it does not replace classification, minimization, |
| 135 | +access review, or downstream handling controls. |
| 136 | + |
| 137 | +For the concrete capabilities GPT-RAG integrates, see the |
| 138 | +[Grounding sources overview](howto_grounding_overview.md). GPT-RAG integrates |
| 139 | +specific Work IQ, Fabric IQ, Foundry IQ, and web grounding capabilities. It |
| 140 | +does not claim complete Microsoft IQ support or provide a Microsoft IQ |
| 141 | +governance layer. |
| 142 | + |
| 143 | +## Govern generated telemetry |
| 144 | + |
| 145 | +### Data classes |
| 146 | + |
| 147 | +| Class | Examples | Required posture | |
| 148 | +| --- | --- | --- | |
| 149 | +| Operational metadata | Event and correlation IDs, service and version, bounded status and reason codes, durations, tool names, source kinds, opaque source references | Permitted by the unreleased metadata-only contract. Classify and minimize it because identifiers and operational context can still be sensitive. | |
| 150 | +| Sensitive content | Prompts, responses, source excerpts, system instructions, tool arguments, tool results | Off by default. Enable only after an explicit need, privacy review, access design, retention decision, and cost review. | |
| 151 | +| Prohibited data | Access tokens, API keys, authorization headers, cookies, connection strings, credentials, and detected secrets | Never capture or export, including when sensitive-content capture is enabled. Redact before telemetry leaves the producing process and fail closed by omitting unsafe values. | |
| 152 | + |
| 153 | +Actor correlation is disabled by default. If |
| 154 | +`AUDIT_ACTOR_PSEUDONYM_ENABLED=true`, the producer records `actor_id` as |
| 155 | +`hmac_` plus the first 32 hexadecimal characters of an HMAC-SHA256 digest. It |
| 156 | +never places the raw user name, email address, object ID, or token claim in that |
| 157 | +property. Store `AUDIT_HMAC_KEY` in Azure Key Vault, restrict it to the |
| 158 | +producing workload, and rotate it together with `AUDIT_HMAC_KEY_ID`. Rotation |
| 159 | +breaks direct pseudonym correlation across key versions. |
| 160 | + |
| 161 | +Redaction metadata should say that redaction occurred and list omitted field |
| 162 | +names, never the omitted values. A successful redaction flag does not prove that |
| 163 | +all sensitive information was found, so producers must use allowlisted fields |
| 164 | +and bounded enums instead of trying to sanitize arbitrary objects. |
| 165 | + |
| 166 | +## Retention, access, and export |
| 167 | + |
| 168 | +GPT-RAG's current AI Landing Zone template configures the Log Analytics |
| 169 | +workspace for 30 days of retention. A reused workspace or table-level override |
| 170 | +can differ, so inspect the deployed settings rather than assuming the template |
| 171 | +value applies. |
| 172 | + |
| 173 | +Azure Monitor supports up to two years of analytics retention for Analytics |
| 174 | +tables and up to 12 years of total retention with long-term retention. Longer |
| 175 | +retention and additional ingestion can increase cost. The adopter must choose a |
| 176 | +period that matches incident, privacy, records-management, and legal needs. |
| 177 | + |
| 178 | +Use this operational baseline: |
| 179 | + |
| 180 | +- Keep access least-privileged and review role assignments regularly. |
| 181 | +- Separate platform administration from routine telemetry reading where |
| 182 | + practical. |
| 183 | +- The audit implementation stores allowlisted `prompt`, `response`, |
| 184 | + `source_excerpt`, `tool_arguments`, and `tool_result` values in |
| 185 | + `AppEvents.Properties`, not `AppGenAIContent`. If audit sensitive capture is |
| 186 | + approved, restrict `AppEvents`, its query results, alerts, workbooks, and |
| 187 | + exports accordingly. |
| 188 | +- Other generative AI instrumentation can use `AppGenAIContent`. Follow the |
| 189 | + current |
| 190 | + [Application Insights routing guidance](https://learn.microsoft.com/azure/azure-monitor/app/data-model-complete#generative-ai-telemetry) |
| 191 | + and configure it as a |
| 192 | + [protected table](https://learn.microsoft.com/azure/azure-monitor/logs/protected-tables-configure) |
| 193 | + when that separate content capture is enabled. |
| 194 | +- Test retention changes and deletion procedures in a non-production |
| 195 | + environment. |
| 196 | +- Use |
| 197 | + [Log Analytics data export](https://learn.microsoft.com/azure/azure-monitor/logs/logs-data-export) |
| 198 | + when continuous export to Azure Storage or Event Hubs is required. |
| 199 | +- If an organization needs WORM retention, configure |
| 200 | + [immutable Blob Storage](https://learn.microsoft.com/azure/storage/blobs/immutable-storage-overview) |
| 201 | + on the export destination as an operator-owned control. GPT-RAG does not |
| 202 | + configure an immutable evidence store. |
| 203 | + |
| 204 | +Sampling affects evidence. A 100 percent sampling configuration may reduce |
| 205 | +sampling gaps, but it increases ingestion and retention cost and still does not |
| 206 | +guarantee complete evidence. Verify the deployed OpenTelemetry and Azure Monitor |
| 207 | +sampling behavior, exporter health, and throttling before relying on telemetry |
| 208 | +for an investigation. |
| 209 | + |
| 210 | +## Roll out the audit feature after release |
| 211 | + |
| 212 | +Do not begin this procedure until the orchestrator implementation is released |
| 213 | +and GPT-RAG umbrella deployment integration is complete. |
| 214 | + |
| 215 | +1. Upgrade with audit emission disabled. |
| 216 | +2. Enable metadata-only events in a non-production environment. |
| 217 | +3. Keep `AUDIT_ACTOR_PSEUDONYM_ENABLED` and |
| 218 | + `AUDIT_SENSITIVE_CONTENT_ENABLED` disabled. |
| 219 | +4. If actor correlation is approved, create and restrict a Key Vault HMAC key |
| 220 | + before enabling it. |
| 221 | +5. Canary a small production slice and reconstruct representative requests. |
| 222 | +6. Monitor latency, exporter failures, ingestion volume, retention cost, and |
| 223 | + evidence-gap health signals. |
| 224 | +7. Confirm that existing traces, logs, dashboards, and alerts still work. |
| 225 | +8. Roll back by setting `AUDIT_EVENTS_ENABLED=false` and restarting the |
| 226 | + orchestrator. Do not enable sensitive content as a troubleshooting shortcut. |
| 227 | + |
| 228 | +Audit emission should not make the user request fail. If event production or |
| 229 | +the synchronous logging path fails, the runtime continues the request and |
| 230 | +attempts an `audit.emission.failed` event, then a fixed warning if that also |
| 231 | +fails. The Azure Monitor batch exporter does not expose an application callback |
| 232 | +for later delivery failure. The implementation has no separate health event, |
| 233 | +rate limiter, or delivery acknowledgment, so operators must monitor expected |
| 234 | +volume and Azure Monitor ingestion health. |
| 235 | + |
| 236 | +## Related reading |
| 237 | + |
| 238 | +- [Audit Contract v1, unreleased](governance_audit_contract_v1.md) |
| 239 | +- [Authentication and Document-Level Security](howto_authentication.md) |
| 240 | +- [Grounding sources overview](howto_grounding_overview.md) |
| 241 | +- [Azure Monitor Application Insights telemetry data model](https://learn.microsoft.com/azure/azure-monitor/app/data-model-complete) |
| 242 | +- [Manage Log Analytics retention](https://learn.microsoft.com/azure/azure-monitor/logs/data-retention-configure) |
| 243 | +- [Manage access to Log Analytics workspaces](https://learn.microsoft.com/azure/azure-monitor/logs/manage-access) |
0 commit comments