[design-spec] azure-subnet-egress-validation

[rw-codebundle-agent]

CodeBundle Design Spec — azure-subnet-egress-validation

Parent: codecollection-registry#49 (Firewall & NSG Integrity)

codebundle_name: "azure-subnet-egress-validation"
target_collection: "rw-cli-codecollection"
display_name: "Azure Subnet Egress Path Validation"
author: "rw-codebundle-agent"

purpose: |
Validate that egress traffic from each target subnet is enforced as expected by
NSGs, route tables, and (when present) Azure Firewall or NVAs. Helps confirm
end-to-end path rules rather than only static rule text.

tasks:

• name: "Discover Subnets and Attached NSGs in Scope"
  description: "List subnets in the VNet/RG scope; resolve subnet IDs, attached NSGs, and route tables."
  script_name: "subnet-discover-attachments.sh"
  expected_issue_severity: [2]
  access_level: "read-only"
  data_type: "logs-config"

• name: "Summarize Effective Egress Rules per Subnet"
  description: "For each subnet, aggregate NSG outbound rules affecting subnet traffic (and NIC-level NSGs where applicable); highlight default deny/allow."
  script_name: "subnet-effective-nsg-egress.sh"
  expected_issue_severity: [2, 3]
  access_level: "read-only"
  data_type: "logs-config"

• name: "Validate Route Table and Firewall Next Hop"
  description: "Inspect UDRs for default route (0.0.0.0/0) to Azure Firewall or NVA; flag missing forced tunneling where policy requires it."
  script_name: "subnet-route-firewall-check.sh"
  expected_issue_severity: [3, 4]
  access_level: "read-only"
  data_type: "logs-config"

• name: "Run Connectivity Probes for Egress Targets"
  description: "Use Network Watcher connection troubleshoot or documented curl/HTTPS probes from a designated test VM/agent in the subnet to probe allowed/denied destinations; compare outcome to expected policy."
  script_name: "subnet-egress-probe.sh"
  expected_issue_severity: [3, 4]
  access_level: "read-only"
  data_type: "metrics"

• name: "Report Egress Validation Summary"
  description: "Per-subnet pass/fail matrix: probes vs policy intent; include remediation next steps (NSG rule, route, or firewall app rule)."
  script_name: "subnet-egress-summary.sh"
  expected_issue_severity: [2]
  access_level: "read-only"
  data_type: "logs-config"

scope:
level: "Resource"
qualifiers:
- AZURE_SUBSCRIPTION_ID
- AZURE_RESOURCE_GROUP
- VNET_NAME
iteration_pattern: |
One SLX per VNet or per subnet (configurable): iterate subnets as the inner
loop for probes and rule summaries.

resource_types:

• "microsoft_network_virtual_networks"
• "microsoft_network_virtual_networks_subnets"
  generation_strategy: |
  platform azure; match virtualNetwork resources by name within subscription/RG.
  Qualifiers: vnet name, subscription_id. Optional discovery of all subnets under VNet.

env_vars:

• name: AZURE_SUBSCRIPTION_ID
  description: "Azure subscription ID"
  required: true

• name: AZURE_RESOURCE_GROUP
  description: "Resource group containing the VNet"
  required: true

• name: VNET_NAME
  description: "Virtual network name to analyze"
  required: true

• name: PROBE_TARGETS
  description: "Comma-separated host:port or URL list for egress tests (e.g. https://example.com:443)"
  required: true

• name: PROBE_MODE
  description: "network-watcher | bastion-agent | skip-probes (rules-only)"
  required: false
  default: "network-watcher"

• name: SOURCE_VM_RESOURCE_ID
  description: "Optional: VM in subnet to use as probe source for Network Watcher or agent-based tests"
  required: false
  default: ""

secrets:

• name: azure_credentials
  description: "Reader plus Network Contributor if using Network Watcher tests (team may use least-privilege custom role)"
  format: |
  JSON: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET, AZURE_SUBSCRIPTION_ID

platform:
name: "azure"
cli_tools:
- "az network vnet subnet"
- "az network route-table"
- "az network watcher"
- "jq"
auth_methods:
- "Service Principal (azure_credentials)"
api_docs: "https://learn.microsoft.com/en-us/azure/network-watcher/network-watcher-monitoring-overview"

related_bundles:

• name: "azure-nsg-desired-state-drift"
  relationship: "complements"
  notes: "Drift detection validates rule text vs baseline; egress validation tests actual path behavior."

• name: "azure-aks-triage"
  relationship: "complements"
  notes: "AKS triage includes basic NSG listing for AKS subnets; this bundle generalizes egress validation for arbitrary VNets."

test_scenarios:

• name: "egress_allowed_as_expected"
  description: "Probes succeed and routes/NSGs match documented policy"
  expected_issues: 0

• name: "missing_firewall_route"
  description: "Default route does not point to required Azure Firewall"
  expected_issues: 1
  expected_severities: [4]

notes: |
Full packet simulation may require Network Watcher enabled in region, a probe VM
in each subnet, or Azure Virtual Network Manager—document minimum viable mode
(rules-only) vs probe mode. Some environments block automated probes; PROBE_MODE
must degrade gracefully. Coordinate with azure-network-security-activity-audit
when investigating repeated egress failures.

[rw-codebundle-agent]

🔧 Creator agent starting (sre mode). Target: runwhen-contrib/rw-cli-codecollection

[rw-codebundle-agent]

✅ Creator agent completed. Scores: azure-subnet-egress-validation: 96/96.
PR: runwhen-contrib/rw-cli-codecollection#634

[rw-codebundle-agent]

🔧 Creator agent starting (sre mode). Target: runwhen-contrib/rw-cli-codecollection