Add complete OSI Data Link Layer assurance and ExpressRoute MACsec checks

[ritiksah141]

Problem

OpenShield currently has no genuine OSI Layer 2 coverage. Existing NIC, NSG, routing, firewall, and peering rules operate at Layer 3 or above and must not be counted as Data Link controls.

Azure Virtual Networks are Layer 3 overlays and do not expose tenant-controlled VLAN, switching, bridging, broadcast, multicast, spanning tree, or forwarding-table configuration. Most Azure fabric Layer 2 behavior therefore requires provider assurance rather than false automated findings.

ExpressRoute Direct is the main customer-visible Layer 2 boundary. Azure exposes its Ethernet links, encapsulation, MTU, administrative state, MACsec configuration, cipher, SCI state, and Key Vault secret references through the management API.

Required implementation

Build a backend-only Data Link assurance feature after #240 is merged. Reuse and generalize the assurance foundation introduced by that PR instead of duplicating its validation and reporting logic.

Sublayers

Cover both canonical IEEE 802 Data Link sublayers:

• Logical Link Control, LLC
• Media Access Control, MAC

Functional coverage

The closed catalog must represent all of these domains:

1. Frame construction and delimiting
2. Source and destination MAC addressing
3. Media access control
4. Frame check sequence and error detection
5. Link-level flow control
6. Link establishment and teardown
7. MTU, frame size, and jumbo-frame behavior
8. VLAN tagging, 802.1Q, and QinQ encapsulation
9. Switching, bridging, filtering, and forwarding tables
10. Loop prevention and spanning-tree behavior
11. Link aggregation and LACP
12. Neighbor and link discovery such as LLDP
13. ARP and neighbor-discovery boundary protection
14. Broadcast and multicast handling
15. MACsec and port-access security
16. Layer 2 quality of service and priority handling
17. Operations, administration, monitoring, and packet visibility
18. Virtual switching, SR-IOV, and overlay adaptation
19. Link redundancy and failover

Every domain must declare its Azure applicability, responsibility owner, observability method, evidence sources, and whether it is provider-attested, platform-enforced, automatically checked, manually verifiable, unsupported, or not applicable.

Automated checks

Add customer-actionable checks only where Azure exposes authoritative management-plane state:

• Detect enabled ExpressRoute Direct links without MACsec configuration.
• Detect ExpressRoute Direct links of 40 Gbps or greater using a non-XPN MACsec cipher.
• Treat subscriptions without ExpressRoute Direct as not applicable.
• Preserve an indeterminate state on Azure API or permission failures and never create false findings.
• Do not expose CAK or CKN secret values in findings, metadata, logs, or tests.

Each rule must include offline regression tests, a safe remediation playbook, and mappings for the compliance frameworks required by repository policy.

API and catalog

Add an authenticated GET /api/assurance/data-link-layer endpoint returning:

• Layer number, name, scope, catalog version, and responsibility boundary
• Domain and sublayer coverage
• Provider-assurance and platform-enforcement states
• Automated-control applicability
• Catalog coverage and evidence freshness as separate measurements
• Evidence review dates and source links
• Explicit limitations preventing assurance from being interpreted as live Azure fabric inspection

The catalog must fail validation when any required domain, sublayer, responsibility, applicability decision, evidence source, or cross-reference is missing.

Acceptance criteria

• LLC and MAC are both covered
• All 19 domains are represented and validated
• Existing Layer 3 and Layer 4 rules are not relabeled as Layer 2
• ExpressRoute Direct inventory uses the existing AzureClient abstraction
• MACsec absence and high-speed non-XPN cipher checks behave correctly
• Empty inventory and API failure paths do not create findings
• Layer 2 assurance does not alter the tenant security score for provider-owned controls
• No frontend changes are included
• No paid OpenShield service or external runtime API is required
• Documentation explains the Azure Layer 2 responsibility boundary
• Ruff, DCO, backend tests, rule validation, CodeQL, Semgrep, Bandit, Gitleaks, pip-audit, dependency review, SBOM, Trivy, and the CI summary pass

Non-goals

• Frontend or dashboard work
• On-premises switch discovery
• SNMP, LLDP, DCIM, or packet-broker integrations
• Claiming visibility into Microsoft forwarding tables, physical switches, or tenant-isolated fabric internals
• Treating accelerated networking as a universal security requirement

Dependency

Blocked by #240 because the implementation must build on the shared assurance API and validation model introduced there.