[design-spec] azure-network-security-activity-audit

[rw-codebundle-agent]

CodeBundle Design Spec — azure-network-security-activity-audit

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

codebundle_name: "azure-network-security-activity-audit"
target_collection: "rw-cli-codecollection"
display_name: "Azure NSG and Firewall Change Activity Audit"
author: "rw-codebundle-agent"

purpose: |
Query Azure Activity Log for create/update/delete operations on NSGs, Azure
Firewall, and related resources. Classify whether changes likely originated from
approved automation (CI/CD service principals, managed identities) versus
interactive users, to support governance and incident review.

tasks:

• name: "Query Activity Log for NSG Mutations"
  description: "List write operations on Network Security Groups and NSG rules in the time window; capture caller, appId, principalId, and HTTP status."
  script_name: "activity-log-nsg-writes.sh"
  expected_issue_severity: [2, 3]
  access_level: "read-only"
  data_type: "logs-bulk"

• name: "Query Activity Log for Azure Firewall and Policy Mutations"
  description: "Include Microsoft.Network/azureFirewalls, firewallPolicies, and rule collection changes where applicable."
  script_name: "activity-log-firewall-writes.sh"
  expected_issue_severity: [2, 3]
  access_level: "read-only"
  data_type: "logs-bulk"

• name: "Classify Callers Against Allowlist"
  description: "Compare operation caller identity to env-provided list of CI/CD app IDs and managed identity object IDs; tag events as automated vs manual/suspect."
  script_name: "activity-classify-callers.sh"
  expected_issue_severity: [3, 4]
  access_level: "read-only"
  data_type: "logs-bulk"

• name: "Flag Manual or Out-of-Band Changes"
  description: "Raise issues for mutations not matching allowlist or occurring outside maintenance windows (optional schedule parameters)."
  script_name: "activity-flag-manual-changes.sh"
  expected_issue_severity: [3, 4]
  access_level: "read-only"
  data_type: "logs-bulk"

• name: "Summarize Change Timeline and Top Actors"
  description: "Aggregate counts by actor and resource; link to portal activity log filtered views."
  script_name: "activity-summary-report.sh"
  expected_issue_severity: [1, 2]
  access_level: "read-only"
  data_type: "logs-bulk"

scope:
level: "Subscription"
qualifiers:
- AZURE_SUBSCRIPTION_ID
- AZURE_RESOURCE_GROUP
iteration_pattern: |
Optional: one SLX per subscription or per resource group. Time-bounded queries
using configurable lookback hours.

resource_types:

• "microsoft_network_network_security_groups"
• "microsoft_network_azure_firewalls"
  generation_strategy: |
  platform azure; generation at subscription or resource-group scope for network
  security resources. Activity queries use subscription-scoped filters.

env_vars:

• name: AZURE_SUBSCRIPTION_ID
  description: "Subscription to audit"
  required: true

• name: AZURE_RESOURCE_GROUP
  description: "Limit to resource group (optional; empty = entire subscription)"
  required: false
  default: ""

• name: ACTIVITY_LOOKBACK_HOURS
  description: "Hours of activity log to analyze"
  required: false
  default: "168"

• name: CICD_APP_IDS
  description: "Comma-separated Azure AD application (client) IDs approved for automation"
  required: false
  default: ""

• name: CICD_OBJECT_IDS
  description: "Comma-separated object IDs for additional managed identities or SPNs"
  required: false
  default: ""

secrets:

• name: azure_credentials
  description: "Reader on subscription; Activity Log read typically included with Reader"
  format: |
  JSON: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET, AZURE_SUBSCRIPTION_ID

platform:
name: "azure"
cli_tools:
- "az monitor activity-log list"
- "jq"
auth_methods:
- "Service Principal (azure_credentials)"
api_docs: "https://learn.microsoft.com/en-us/azure/azure-monitor/platform/activity-log"

related_bundles:

• name: "azure-loadbalancer-triage"
  relationship: "complements"
  notes: "Pattern reference for activity-log queries scoped to a resource; this bundle generalizes to NSG/Firewall resource types and caller classification."

• name: "azure-nsg-desired-state-drift"
  relationship: "complements"
  notes: "Drift shows what changed relative to desired state; activity audit shows who/when for those mutations."

test_scenarios:

• name: "only_cicd_changes"
  description: "All mutations in window match CICD_APP_IDS"
  expected_issues: 0

• name: "portal_user_rule_change"
  description: "User principal modified NSG rule"
  expected_issues: 1
  expected_severities: [4]

notes: |
Activity Log retention and latency: default retention may be 90 days at
subscription level; document limits. Some callers appear as "Unknown" or
pipeline agents—customers should maintain allowlists. Correlation with Azure
DevOps or GitHub OIDC requires mapping known pipeline SPNs into CICD_APP_IDS.
For Azure Firewall Policy at scale, filter resource provider operations to avoid
noise. Read-only access only.

[rw-codebundle-agent]

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

[rw-codebundle-agent]

✅ Creator agent completed. Scores: azure-network-security-activity-audit: 96/96.
PR: runwhen-contrib/rw-cli-codecollection#635

[rw-codebundle-agent]

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