[parthrohit22]

What does this PR do?

Adds the execution gate for any future agent-driven remediation: human approval, an empty allowlist, at-most-once execution, an append-only audit trail, and rescan-based verification. It is proposal-only, and nothing in the repo runs a playbook.

Type of change

• New scan rule
• Remediation playbook
• Bug fix
• Dashboard/front-end work
• API endpoint
• Documentation
• Compliance mapping
• Other: core persistence and safety gate (new feature, api/models and Alembic)

Design

Full write-up in docs/remediation-gate.md. Lifecycle:

PROPOSED -> APPROVED -> EXECUTING -> PENDING_VERIFICATION -> VERIFIED

with REJECTED, EXECUTION_FAILED and VERIFICATION_FAILED branches. Every transition is a single conditional UPDATE ... WHERE status = ANY(...) plus an audit row in the same transaction, so concurrency is decided by the database rather than by check-then-write in Python.

Mapping to the issue:

Requirement	Implementation
Typed allowlist, starts empty	EXECUTION_ALLOWLIST = frozenset(). A refused attempt is audited.
Mandatory human approval	begin_execution only matches APPROVED rows.
A retry never executes twice	APPROVED -> EXECUTING is won by exactly one caller. Everyone else gets InvalidTransition, never a grant. A crashed runner leaves the row EXECUTING and is not retried automatically.
Full audit log	remediation_audit_log, append-only via trigger.
Rescan verification	VERIFIED needs a later completed rescan of the same subscription whose rule evaluation (#263) for that resource is PASS. FAIL stays open as VERIFICATION_FAILED. Missing, UNKNOWN or ERROR is inconclusive and never closes the action.

It also covers the concern @babyblueviper1 raised on the issue: approval is a compare-and-swap, so two concurrent approve calls on one PROPOSED row cannot both win.

Rule details (if applicable)

N/A, no scan rule is added or changed.

Testing

• Tested against a real Azure free trial subscription (N/A: database-only change, no Azure calls)
• tests/test_remediation_gate_postgres.py: 29 tests against PostgreSQL covering every exit criterion, including 8-way concurrent proposal, approval, execution and verification
• Mutation-checked: removing the approval CAS guard, or treating missing evidence as cleared, each make a test fail
• Alembic upgrade -> downgrade -> upgrade round-trip, single head (b6d2f8a4c1e7)
• Full suite pytest tests/ passes locally (1509 passed, 3 skipped) against PostgreSQL 15; ruff check and ruff format --check are clean
• No hardcoded credentials or secrets

The existing migration test pins the head revision, so _HEAD in tests/test_scan_admission_migration_postgres.py is bumped.

Not in scope (follow-ups)

HTTP routes and UI for propose/approve, generating proposals from findings, separation of duties (approver must differ from proposer), and authenticating the actor identity. Listed in the doc.

Related issue

Closes #266

Checklist

• Every commit includes a DCO Signed-off-by trailer (git commit -s; see docs/dco.md)
• My code follows the rule template in CONTRIBUTING.md (N/A for rules)
• I added or updated the matching CLI playbook (N/A)
• I added or updated all four compliance framework mappings (N/A)
• I have not committed any real Azure credentials
• My branch name follows the convention: feat/description

[babyblueviper1]

Thanks for picking up the approve-side race. I read through _transition: the FOR UPDATE CTE plus WHERE a.status = ANY(...) does make the second concurrent approve see zero rows, so that concern is closed.

Two gaps are left in the same area. The first one I reproduced.

1. TRUNCATE gets past the append-only trigger. Row-level BEFORE UPDATE OR DELETE triggers don't fire on TRUNCATE. I ran the migration's trigger DDL on Postgres 16:

DELETE FROM remediation_audit_log;   -> ERROR: remediation_audit_log is append-only
TRUNCATE remediation_audit_log;      -> TRUNCATE TABLE   (0 rows left)

One extra statement in the migration closes it (after I added this, the same TRUNCATE raised and the row survived):

CREATE TRIGGER trg_remediation_audit_log_no_truncate
BEFORE TRUNCATE ON remediation_audit_log
FOR EACH STATEMENT EXECUTE FUNCTION remediation_audit_log_append_only();

It would also help to REVOKE UPDATE, DELETE, TRUNCATE from the app role. The table owner can still DROP TRIGGER, so if the trail needs to be evidence against the operator too, it needs a prev_hash/row_hash chain whose head is published outside the database.

2. Approval binds to the playbook path, not to what will run. remediation_actions.playbook holds playbooks/cli/fix_<rule>.sh, and the approved audit row carries no detail. If that script changes between approve and begin_execution, the grant still covers it, and the audit trail can't show what the approver actually saw.

A small fix:

• store playbook_sha256 (the script bytes) and the target (resource_id, subscription_id) at propose;
• put both in the approved audit detail;
• have begin_execution recompute the hash and refuse on mismatch.

This is the same "approve X, execute exactly X" check we use for deploy approvals here: the approval is bound to the plan's sha256 and re-verified before dispatch.

Glad to send (1) as a follow-up PR against this branch if that's useful.

[babyblueviper1]

Checked 670a751. Both fixes are right:

• The BEFORE TRUNCATE statement trigger closes the gap I reproduced.
• playbook_sha256 is stored at propose time, carried in the approved audit row, and recomputed by begin_execution, which refuses on a mismatch.

One note for when the execution side lands (nothing runs a playbook in this PR, so it's not a blocker here). The hash is checked when the grant is issued, but the executor will read the script from disk again when it runs. To make the binding hold end to end, the executor should either read the bytes once, check them against the grant's playbook_sha256, and run those exact bytes, or recompute the hash right before exec and refuse on a mismatch. Otherwise a change between the grant and exec slips through the same way the approval-to-execution gap did.