Workflow · Repair

Repair: Deliberate Action After Evidence and Judgment

Repair closes the loop in AuditWalk. It turns reviewed findings into explicit action plans, then executes only after human approval. No silent mutation, no hidden state changes.

Purpose

What Repair is for

Repair is where AuditWalk becomes either disciplined or dangerous. It exists to carry out approved corrective action only after evidence has been observed, trusted, measured, and interpreted.

Repair should be deliberate, explainable, reversible where possible, and downstream of evidence. It is not magic automation and it is never a silent "trust me, I fixed it" layer.

Hierarchy

Repair sits at the end of the execution chain

Scan -> Baseline Scan -> PreFlight/Compare -> Doctor -> Repair

Repair is not the first response. It consumes evidence from prior stages and applies scoped actions with explicit approval.

Boundaries

What Repair should do and should not do

Should do

  • Restore permissions and ownership drift
  • Revert selected config drift with evidence
  • Quarantine or move unexpected files in scoped paths
  • Generate reviewable repair plans before execution

Should not do (v1)

  • Run silent bulk changes across the system
  • Delete destructively as a default response
  • Infer broad remediations without preview
  • Act on findings that cannot be explained clearly

Decisioning

Repair posture model

Not every finding should trigger action. Repair uses a posture ladder so decisions remain proportional and auditable.

  • No action: routine drift or non-actionable findings
  • Monitor: notable drift that is not yet actionable
  • Review required: human decision needed before change
  • Repair candidate: scoped and evidence-backed
  • Repair recommended: strong evidence, clear corrective path

Action Classes

Repair categories

Metadata repair

  • Permissions, ownership, mode bits
  • Low-risk and highly explainable

Presence and absence repair

  • Quarantine, remove, or restore scoped files
  • Higher risk, stronger guardrails required

Config repair

  • Restore approved settings values
  • Constrained to explicit keys and paths

Policy and browser repair

  • Policy actions are review-heavy
  • Browser repair deferred until browser contract is mature

Scoping

Repair requires explicit scope

Repair scope must never be ambiguous.

  • File, directory, or path pattern
  • Compare finding subset
  • Doctor recommendation subset
  • Browser profile scope (when enabled later)
  • Baseline-relative drift subset

Integration

How Repair uses the other workflow tools

  • Scan: source evidence of observed state
  • Baseline Scan: accepted reference for restore intent
  • PreFlight: tactical verification before/after action
  • Compare: primary operational drift input
  • Doctor: advisory triage and action suitability
  • Follow-up Compare: validates outcomes after apply

Pipeline

Repair response construction pipeline

  1. Collect actionable findings (baseline, compare, doctor, warnings).
  2. Filter to repairable items and defer ambiguous cases.
  3. Build plan entries with target, reason, action, risk, and reversibility.
  4. Present the plan with evidence sources and non-change list.
  5. Require explicit approval for selected actions.
  6. Execute scoped actions and write execution artifact.
  7. Recommend and run follow-up verification (Compare and Doctor).

Safety

Plan first, apply deliberately

Repair Plan

  • Non-mutating by default
  • Action list with rationale
  • Reviewable before any execution
  • Includes impacted paths and rollback notes

Repair Apply

  • Requires explicit confirmation
  • Executes approved actions only
  • Writes execution artifact and status
  • Never runs silently in background

Modes

Repair modes

  • Plan: generate recommendations only
  • Apply: execute an approved plan
  • Dry run: preview exact effect without mutation
  • Scoped apply: apply only selected classes or targets

Safety Contract

Minimum safety rules and high-risk conditions

Minimum rules

  • Read-only until apply is explicit
  • No action without scoped targets
  • Prefer reversible operations and quarantine where feasible
  • Log all actions, warnings, and failures

High-risk triggers

  • Missing baseline or stale evidence
  • Incomplete compare or collection blind spots
  • Overly broad scope or destructive actions
  • Conflicting findings or insufficient privileges

Explainability

Every action must be explainable

If Repair cannot explain an action clearly, it should not execute it automatically.

  • What will be changed
  • Why it is being changed
  • Which evidence supports the action
  • What reference state is being used
  • Risk level and reversibility
  • What is intentionally not being changed

Artifacts

Repair artifact contract

Plan artifact

  • repair_id, timestamp, and scope
  • Source IDs: baseline, compare, doctor
  • Action list with rationale and risk
  • Reversibility notes

Execution artifact

  • Execution timestamp and operator context
  • Approved actions and actual outcomes
  • Skipped items, failures, and warnings
  • Post-check recommendation

v1 Strategy

Recommended v1 implementation boundary

v1 should stay narrow and highly defensible.

  • Include: plan generation, permission/ownership repair, selected config restoration, scoped quarantine/move actions, durable artifacts, explicit apply step.
  • Defer: global automatic repair, broad deletion, opaque autonomous actions, deep service/process remediation, browser repair before browser contract maturity.

Semantics

Time and traceability in Repair

Repair should account for evidence freshness and repair recency, not just current state.

  • Time since baseline acceptance
  • Time since compare and doctor outputs
  • Change clustering in short intervals
  • Prior repair recency on the same targets

CLI

CLI examples

auditwalk repair plan
auditwalk repair plan --compare-id <compare_id>
auditwalk repair plan --doctor-id <doctor_id>
auditwalk repair plan --path /etc
auditwalk repair plan --dry-run
auditwalk repair plan --include browser
auditwalk repair show --repair-id <repair_id>
auditwalk repair apply --repair-id <repair_id>
auditwalk repair apply --repair-id <repair_id> --only low-risk
auditwalk repair list
auditwalk doctor run
auditwalk compare run

Workflow

Full evidence-to-action workflow

auditwalk scan run --profile full
auditwalk baseline set --scan-id <scan_id>
auditwalk preflight run --include browser
auditwalk compare run
auditwalk doctor run
auditwalk repair plan --compare-id <compare_id> --dry-run
# after review and approval
auditwalk repair apply --repair-id <repair_id>
auditwalk compare run
auditwalk doctor run

This preserves the strict chain: observe -> trust -> measure -> interpret -> act -> verify.

Positioning

Public-facing copy

Repair turns approved findings into deliberate corrective action. It uses baseline context, compare results, and Doctor recommendations to build a scoped plan you can review before anything changes. Instead of fixing systems silently, Repair keeps action explicit, explainable, and verifiable.