feat(agent): typed remediation proposals and read-only agent [Automation PR 3/5]

Objective

Create machine-validatable remediation proposals and human-readable approval packets without any execution authority. This is PR 3 of 5 and depends on #311 and #312.

Scope

Typed remediation registry

Create a code-owned, version-controlled registry. Existing shell files remain operator documentation and must not be executed directly by this PR.

Start with 3-5 candidates but mark each proposal_only or execution_candidate. At least the first execution candidates should be low-scope Storage controls with directly readable before/after state. RBAC, networking, Entra, AKS, multi-resource, interactive, and irreversible changes remain proposal-only until separately proven.

Each definition declares:

• Registry/playbook ID and semantic version.
• Supported rule IDs and exact Azure resource type.
• Fixed absolute executable or Azure SDK operation.
• Typed, bounded, allowlisted parameters derived from authoritative evidence.
• Exact target resource-ID parser and tenant/subscription checks.
• Required permissions.
• Current-state preconditions and expected postconditions.
• Verification rule IDs and relationship/path verification requirements.
• Impact, rollback procedure, or explicit irreversible warning.
• Timeout, output limit, redaction fields, idempotency behavior, and execution eligibility.

Proposal lifecycle

Add reversible migrations for remediation_runs, immutable plan versions, evidence references, and append-only transitions.

States in this PR: PROPOSED, VALIDATING, VALIDATION_FAILED, AWAITING_APPROVAL, REJECTED, and EXPIRED.

Generate canonical JSON using a documented canonicalization algorithm and a cryptographic plan hash. Bind it to tenant, subscription, resource ID, attack-path ID/version, evidence version, registry version, and expiry. Any executable change changes the hash.

APIs

• POST /api/v1/remediation-runs
• GET /api/v1/remediation-runs/{run_id}
• POST /api/v1/remediation-runs/{run_id}/reject

Enforce server-side roles: viewer may read authorised runs; proposer may create; proposer/approver separation is recorded for later policy; authorised users may reject according to policy.

Optional AI explanation

AI receives only structured published evidence and plan data. Its text is non-executable, stored separately, cites evidence IDs, and fails validation on unsupported material claims. Proposal generation works when AI is disabled, unavailable, or times out.

Required security properties

• No command, executable, flag name, target, scope, or parameter value originates from model output or free-form API text.
• Unknown JSON fields, unsupported resource types/rules, malformed resource IDs, scope expansion, and missing permissions fail closed.
• No subprocess, Azure write SDK, or execution queue code path is reachable in this PR.
• Prompt injection cannot modify canonical plan JSON or hash.

Measurable acceptance criteria

• Every valid proposal maps to exactly one registry version and authorised resource.
• Repeating the same path/option/evidence request 100 times returns one logical proposal.
• Every executable-field mutation changes the plan hash; explanation-only changes do not.
• Unsupported rule/resource combinations and extra parameters are rejected.
• Cross-tenant/subscription targets are rejected even if supplied in a validly signed request.
• Approval packet shows exact before/change/after intent, target ID, permissions, impact, preconditions, verification, expiry, and rollback status.
• At least 20 adversarial prompt/API payloads cannot add commands, flags, targets, or parameters.
• Static/runtime tests demonstrate no remediation execution path.
• Upgrade/downgrade, unit, integration, authorization, idempotency, expiry, prompt-injection, AI-outage, and failure-path tests pass.

Delivery evidence attached to PR

• Registry schema and review checklist.
• Per-candidate reversibility and impact assessment.
• Canonicalization/hash test vectors.
• Authorization matrix and adversarial test corpus.
• CI-equivalent/security-scan output and security-focused human review.
• Proposal-only deployment telemetry before #314 begins.

Deferred

Natural-language-to-shell, arbitrary commands, multi-step autonomous planning, automatic rule generation, automatic approval, and execution.

Dependencies and handoff

Requires #311 and #312. #314 may enable execution only for registry entries explicitly marked execution_candidate and reviewed under this issue.

---

Mandatory safety and automation checklist

Registry safety

• Every remediation has an immutable ID and semantic version.
• Supported rules, exact resource type, operation, parameters, permissions, preconditions, postconditions, verification, impact, and rollback status are declared.
• Executable path or SDK operation is fixed in code and cannot come from API/model input.
• Parameters are typed, bounded, allowlisted, and derived from authoritative evidence.
• Exact Azure resource IDs are parsed and checked against tenant, subscription, provider, and resource type.
• Interactive, multi-resource, RBAC, network, Entra, AKS, and irreversible candidates remain proposal_only unless separately proven.
• Existing shell scripts are documentation only and are not an execution registry.

Immutable plan

• Canonicalization algorithm and hash algorithm are documented and versioned.
• Plan binds target, scope, evidence, attack path, registry version, preconditions, postconditions, expiry, and verification.
• Every executable-field mutation changes the hash.
• Explanation-only changes do not alter or broaden the executable plan.
• Expired evidence or plan cannot proceed to approval.
• Proposal creation has a database-enforced idempotency key.

AI and input isolation

• Proposal generation succeeds with AI disabled, failed, or timed out.
• AI text is stored outside canonical executable fields.
• AI material claims cite supported evidence and are validated.
• Unknown JSON fields, free-form parameters, malformed IDs, and scope expansion fail closed.
• Adversarial prompts cannot add a target, command, executable, flag, argument, or permission.
• Static/runtime checks prove this PR contains no reachable Azure mutation or subprocess execution path.

Authorization and audit

• Viewer, proposer, rejector, and future approver permissions are server-controlled and documented.
• Every route enforces tenant/subscription authorization.
• Proposal, validation failure, rejection, and expiry transitions are append-only/auditable.
• Approval packet displays exact target, before/change intent, permissions, risks, verification, expiry, and rollback status.

Tests and proof

• Same path/option/evidence request repeated 100 times creates one logical proposal.
• Canonical hash test vectors pass across supported runtime environments.
• At least 20 adversarial API/prompt payloads fail safely.
• Cross-tenant/subscription targets fail even with otherwise valid authentication.
• Unit, integration, authorization, idempotency, expiry, AI-outage, injection, migration, and failure tests pass.
• Every execution candidate has a signed impact/reversibility and least-privilege review.
• CI-equivalent validation and security scanning pass with evidence attached.
• Security-focused human review is approved.
• Proposal-only deployment telemetry is observed before #314 begins.

Exit gate

• No known critical/high security defect remains open.
• No remediation can execute in this PR.
• Maintainer confirms #313 acceptance criteria and this checklist are complete before merge.