Governance - Azure/az-prototype GitHub Wiki
Governance
Overview
The governance system consists of three independent subsystems that work together to ensure generated code meets quality, security, and architectural standards:
| System | Purpose | When Applied | User Action |
|---|---|---|---|
| Policies | Guide agents during generation | Injected into agent system prompts before AI calls | Automatic (agents follow rules) |
| Anti-Patterns | Detect issues in generated output | Scanned after code generation | Accept / Override / Regenerate |
| Standards | Prescriptive design principles | Injected into agent system prompts | Automatic (agents follow principles) |
Total governance assets: 428 rules + 40 anti-pattern checks + 38 design standards = 506 governance items
Policies
Policies are YAML documents (*.policy.yaml) that describe governance rules, implementation patterns (Terraform + Bicep), prohibitions, and references. They are injected into agent system prompts so the AI follows them during code generation. Required rules use "MUST" language; recommended rules use "SHOULD".
Azure Service Policies (321 rules)
| Category | Services | Rules | Details |
|---|---|---|---|
| AI Services | Azure OpenAI, Cognitive Services, AI Search, Bot Service, Machine Learning | 16 | Managed identity, API key auth disabled, CMK, private endpoints |
| Compute | AKS, VMs, VMSS, Batch, Container Instances, Disk Encryption | 33 | Trusted Launch, SSH auth, encryption at host, VNet integration |
| Data Services | SQL, Cosmos DB, Redis, Service Bus, Event Hubs, Data Factory, Databricks, PostgreSQL, and more | 87 | Entra authentication, TLS 1.2, CMK, private endpoints, diagnostics |
| Identity | Managed Identity, Resource Groups | 11 | RBAC, role definitions, resource locks |
| Management | Automation, Logic Apps, Communication Services, Managed Grafana | 18 | Managed identity, diagnostics |
| Messaging | SignalR, Notification Hubs | 7 | TLS, auth configuration |
| Monitoring | Log Analytics, Application Insights, Action Groups | 20 | Retention, diagnostics, alerting |
| Networking | VNet, NSGs, Firewall, Application Gateway, Load Balancer, Bastion, VPN, ExpressRoute, DNS, CDN, DDoS, and more | 92 | Network isolation, NSG rules, route config, WAF |
| Security | Key Vault, Managed HSM, Defender, Sentinel | 12 | RBAC, purge protection, threat detection |
| Storage | Storage Accounts | 8 | Shared key disabled, versioning, lifecycle |
| Web & Apps | Container Registry, App Service, Container Apps, Functions, APIM, Front Door, Static Web Apps | 62 | HTTPS, TLS 1.2, managed identity, VNet integration |
Well-Architected Framework Policies
| Category | Prefix | Rules | Details |
|---|---|---|---|
| Cost Optimization | WAF-COST- |
20 | SKU selection, auto-scaling, reserved instances, lifecycle management |
| Performance | WAF-PERF- |
25 | Caching, database optimization, network performance, observability |
| Reliability | WAF-REL- |
20 | High availability, fault tolerance, backup/recovery, deployment safety |
| Security | WAF-SEC- |
16 | Authentication, data protection, managed identity, network isolation |
Cross-Cutting Policies
| Category | Prefix | Rules | Details |
|---|---|---|---|
| Integration Patterns | CC-INT- |
26 | API design, event-driven, microservices, data pipelines |
Policy ID Prefixes
| Prefix | Scope | Example |
|---|---|---|
AZ- |
Azure service-specific rules | AZ-SQL-001, AZ-KV-001, AZ-VNET-001 |
WAF-COST- |
Well-Architected: Cost Optimization | WAF-COST-SKU-001 |
WAF-PERF- |
Well-Architected: Performance | WAF-PERF-CACHE-001 |
WAF-REL- |
Well-Architected: Reliability | WAF-REL-HA-001 |
WAF-SEC- |
Well-Architected: Security | WAF-SEC-MI-001 |
CC-INT- |
Cross-Cutting: Integration | CC-INT-ED-001 |
ANTI- |
Anti-pattern detection | ANTI-AUTH-001 |
STAN- |
Design standards | STAN-DES-001 |
Policy Structure
Each policy file follows a schema (policy.schema.json) with:
- metadata -- name, category, services list, last reviewed date
- rules -- id, severity (required/recommended), description, rationale, applies_to (agent list), terraform_pattern, bicep_pattern, prohibitions
- patterns -- named implementation patterns with Terraform + Bicep examples
- anti_patterns -- things to avoid with "instead" alternatives
- references -- links to Microsoft Learn documentation
Custom Policies
Users can extend or override built-in policies by placing *.policy.yaml files in .prototype/policies/ in their project directory. Custom policies are loaded alongside built-in policies, with custom rules taking precedence when IDs conflict.
Anti-Patterns
Anti-patterns are automatically scanned in AI-generated output after each stage. When a pattern matches and no safe pattern exempts it, a warning is surfaced for user review.
There are 10 domain YAML files containing 40 checks total:
| Domain | File | Focus |
|---|---|---|
| Security | security.yaml |
Hardcoded secrets, overly permissive access |
| Networking | networking.yaml |
Public endpoints, missing firewalls |
| Authentication | authentication.yaml |
Connection strings, missing managed identity |
| Storage | storage.yaml |
Public blob access, missing encryption |
| Containers | containers.yaml |
Privileged containers, exposed ports |
| Encryption | encryption.yaml |
Missing TLS, unencrypted data at rest |
| Monitoring | monitoring.yaml |
Missing diagnostics, no alerting |
| Cost | cost.yaml |
Over-provisioned SKUs, missing autoscale |
| Completeness | completeness.yaml |
Missing outputs, incomplete modules, hardcoded upstream names |
| Terraform Structure | terraform_structure.yaml |
Unused providers, v1.x versions, non-deterministic uuid(), azurerm resources |
Detection Mechanism
Each anti-pattern check consists of:
- search_patterns -- Substrings to look for (case-insensitive)
- safe_patterns -- Substrings that exempt the match (if present, the check passes)
- warning_message -- Human-readable warning displayed to the user
The scanner tests each search_pattern against the generated text. If a match is found and no safe_pattern is present, the warning is emitted. Documentation stages (category "docs") are exempt from scanning to prevent false positives.
Standards
Design standards are prescriptive principles loaded from YAML files and injected into agent system messages. They cover:
- Design Principles (5) -- Single Responsibility, DRY, Open/Closed, Least Privilege, Explicit Over Implicit
- Coding Standards (5) -- Meaningful Names, Small Functions, Error Handling, Module Structure, Parameterization
- Terraform Module Standards (10) -- Module structure, validation, outputs, state management, naming, testing
- Bicep Module Standards (8) -- Module organization, parameters, outputs, deployment patterns
- Python Application Standards (5) -- Application code quality
- .NET Application Standards (5) -- Application code quality
Standards are filtered by agent name -- infrastructure agents receive IaC standards, application agents receive language-specific standards.
Governor Agent
The governor agent uses embedding-based semantic search to retrieve the most relevant policy rules for each stage's generation context. Rather than injecting all 428 rules (~170KB) into every prompt, the governor retrieves the top-K most relevant rules (~1-2KB brief) and injects them as ## MANDATORY GOVERNANCE RULES.
Pre-computed neural embeddings (sentence-transformers, all-MiniLM-L6-v2) are shipped inside the wheel as policy_vectors.json. No PyTorch is needed at runtime.