feat(scanner): add Azure Resource Graph inventory foundation

[TFT444]

Summary

Introduces Azure Resource Graph inventory as Phase 1 of the proposed OpenShield Evidence Graph.

• Adds paginated multi-subscription ARG collection.
• Produces normalised, tenant-scoped resource snapshots.
• Preserves complete, partial, and failed collection states.
• Handles throttling with bounded retries and detects repeated pagination tokens.
• Records snapshot identity, collection duration, page count, resources, and safe errors.
• Adds the Evidence Graph and Customer Trust Layer architecture document.
• Keeps existing SDK rule execution unchanged while ARG completeness is evaluated.

Security boundaries

• ARG collection is read-only.
• Every resource is bound to a tenant, authorised subscription, and snapshot.
• Cross-tenant and unauthorised-subscription rows are rejected.
• Phase 1 does not persist snapshots or send them to an LLM or external service.
• No remediation or production write access is introduced.

Verification

• ARG regression suite: 10 passed, 92% module coverage.
• Broader scanner/API suite: 536 passed, 3 skipped.
• Ruff check and format pass.
• Python compilation passes.
• Bandit reports no medium or high findings.
• Installed-environment dependency audit reports no known vulnerabilities.
• Detects resultTruncated responses without a continuation token and marks the snapshot partial.
• GitHub CI: all 20 checks pass on the final fix revision.

The unrelated ChromaDB dependency test was excluded from the local Windows run because that dependency could not be installed cleanly in the isolated environment. GitHub CI ran the repository's complete Linux suite successfully.

Live Azure validation

Validated on 11 August 2026 in Azure Resource Graph Explorer using an active Azure for Students subscription containing five resources. The scope was restricted to that student subscription; two unrelated university production subscriptions were not selected.

The OpenShield inventory projection was executed as a read-only query:

Resources
Resources
| project id, name, type, location, subscriptionId, resourceGroup, tenantId, tags, properties
| summarize resourceCount = count()
| extend validation = "OpenShield PR #250 ARG inventory"

Results:

• Aggregate resource count: 5 resources in 0.442 seconds.
• Full OpenShield inventory projection: 5 of 5 resources in 0.575 seconds.
• No Azure resources, configuration, or permissions were changed.
• A privacy-safe proof query labelled the result OpenShield PR #250 ARG inventory without exposing resource identifiers in shared evidence.

This proves the KQL projection and real Azure ARG execution path. It does not yet prove the local Python client against live university credentials because the local Azure CLI remains authenticated to a different tenant.

Remaining benchmark gates

• Run ArgInventoryClient directly with authorised live Azure CLI credentials.
• Exercise pagination with more than one result page.
• Compare ARG completeness with the current SDK scanner.
• Record properties that require targeted SDK enrichment.
• Validate throttling, partial-scope, and restricted-permission behaviour.

No sub-30-second performance guarantee is claimed until these larger-scale gates are complete.

Closes #249

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

OpenSSF Scorecard

Package	Version	Score	Details
pip/azure-mgmt-resourcegraph	8.0.1	Unknown	Unknown

Scanned Files

• requirements.txt

[TFT444]

@Vishnu2707 , @m-khan-97

I did a real live Azure benchmark using my Azure for Students subscription with read-only access.

The current Python ScanEngine ran 68 rules, returned 643 findings and completed in 113.167 seconds.

The new ARG/KQL inventory collected all 5 resources with no errors and a median time of 0.438 seconds.

This proves faster inventory collection, not yet a complete scan speedup. Python will remain the rule engine while ARG provides the shared inventory. No Azure resources or settings were changed.

[TFT444]

@Vishnu2707 PR #250 is ready for a thorough review. The tenant-isolation issue is fixed, tests were added, and all 20 CI checks pass.

[m-khan-97]

Reviewed and fetched the branch to run the tests directly (installed azure-mgmt-resourcegraph==8.0.1 locally to confirm the pin is real and importable): 11/11 pass.

This is well-built, self-contained foundational work — it's a new standalone module (scanner/arg_inventory.py) not yet wired into ScanEngine, so there's zero risk to the existing 74-rule scan path. What stood out:

• Tenant/subscription isolation is actually enforced in code, not just asserted in the docs — _normalise_resource rejects any row whose subscriptionId isn't in the authorised set or whose tenantId doesn't match, and it's tested (test_rejects_cross_tenant_and_unauthorised_subscription_rows). Given the doc's "Customer Trust Layer" section makes tenant isolation a headline guarantee, I specifically checked this claim holds in the implementation — it does.
• Failure semantics are correct and well-tested: COMPLETE only with zero errors, PARTIAL preserves already-collected resources when a later page fails, FAILED when nothing was ever collected. Matches the documented contract exactly, including the repeated-pagination-token guard (infinite-loop protection) and the truncated-without-token case.
• _normalise_subscriptions guards against the classic isinstance(x, str) foot-gun (passing a bare string and having it iterated character-by-character) — small thing, but the kind of bug that's easy to miss and annoying to debug.
• Retry-After handling is sensible (parses the header, falls back to capped exponential backoff if it's not a plain number), and retries are correctly scoped to 429/503 only.

The architecture doc is honest about scope — explicitly flags the benchmark numbers as not yet an apples-to-apples comparison until rules actually migrate to the shared snapshot, and Phase 1's non-goals are clearly listed. Good discipline for a foundational PR that could easily have overclaimed.

Approving.

[Vishnu2707]

Well Done, approved