Skip to content

sodejm/incident-response-sandbox

v0.1.0PolyForm-Noncommercial-1.0.0

Offline incident action planning and fixture-only sandbox execution.

COPS Incident Response Sandbox

This portable package creates typed incident plans and executes two low-risk actions against synthetic local JSON fixtures only: isolate-host and revoke-session. There is no production API adapter.

Prerequisites and quick start

Run these commands from the repository root in an activated project environment with Python 3.11 or newer. The demo uses private temporary local fixtures; it does not require credentials or network access.

python3 -m cops info incident-response-sandbox
python3 -m cops demo incident-response-sandbox
python3 -m cops check incident-response-sandbox

Playback structure and result

The public playback:

  1. creates a private synthetic fixture and short-lived typed plans;
  2. proves that dry-run leaves fixture state unchanged;
  3. executes allowed actions and verifies the resulting fixture state;
  4. rejects reuse of the same plan and rejects an expired plan; and
  5. simulates a partial failure, records rollback evidence, and removes temporary state.
Result fieldPurpose
schemaIdentifies the output as cops.incident-response-playback/v1.
execution_boundary.providerNames the synthetic local fixture provider used by the playback.
execution_boundary.network_callsConfirms that the playback made zero network calls.
execution_boundary.live_containment_validatedRemains false; no production provider action is claimed.
execution_boundary.temporary_artifacts_removedReports whether playback cleanup completed.
primary.dry_run_decision, primary.dry_run_state_unchangedShow the dry-run decision and prove it did not mutate state.
primary.execute_status, primary.verification_stateRecord the allowed execution and its post-action state.
primary.provider_request_id, primary.post_action_verificationBind the synthetic operation to its verification record.
replay_rejection, expiry_rejectionPreserve the fail-closed duplicate and expiry outcomes.
rollback.status, rollback.verification_state, rollback.post_action_verificationRecord restoration after the simulated partial failure.

Run the registered public entry point:

python3 -m cops demo incident-response-sandbox

Use the package runner directly only when debugging the playback implementation:

python3 plugins/incident-response/incident-response-sandbox/scripts/run_demo.py

For manual runs, use a private directory (0700) for plans, receipts, and a copied fixture, and keep the fixture file at 0600. See the operator playback for artifact-preserving commands, expected fields, contract definitions, reruns, and cleanup.

Design and data flow

Execution rejects expired or modified plans, tenant or target mismatch, changed state, stale dry-run receipts, missing fixture permission, throttling, and duplicate plan hashes or nonces. Simulated partial failure records whether rollback succeeded or failed. The fixture execution history prevents replay of recorded attempts.

Each execution result and fixture history record include a deterministic provider_request_id for the synthetic fixture operation and a post_action_verification object. Available verification reports succeeded or failed with a content-addressed fixture-state reference. When the fixture sets verification_available to false, the result is unavailable and the reference is null. The generated values contain only fixed labels and SHA-256 digests; do not replace them with credentials, bearer tokens, signed URLs, or other secret provider response data. These fields demonstrate the receipt shape against a local fixture; they are not evidence from a live provider.

Contract or artifactPurposeKey fieldsProducerConsumerValidationExample
Typed planBind one synthetic action to a tenant, target, approval assertion, and expiryPlan ID, nonce, action, tenant, target, approver, expiryOperator or playbackDry-run and execution commandsSchema, action allowlist, expiry, and plan-hash checksIsolate synthetic host host-01
Fixture stateRepresent local provider state and execution historyTenant, targets, sessions, throttling, verification, historyPlayback fixture or operator copySynthetic executorPrivate path, mode, tenant/target, and expected-state checksHost starts connected
Dry-run receiptAuthorize the exact unchanged plan and fixture state for a later attemptPlan hash, state reference, issued timeDry-run commandExecution commandFreshness and exact plan/state bindingReceipt for one revoke-session plan
Execution result and historyRecord attempted state change, verification, and replay markerOutcome, provider request ID, verification, plan hash, nonceSynthetic executorOperator, rollback, and replay guardResult schema, state digest, and unique plan/nonce checksSession revoked and fixture digest recorded
Rollback resultRecord whether simulated partial failure was restoredOriginal action, rollback status, errorSynthetic executorIncident reviewerRequired after partial failureThrottled isolation restored successfully
Playback summaryQualify plan, dry-run, execution, replay, expiry, and rollback pathsStep results, rejection reasons, cleanup statusscripts/run_demo.pyMaintainerSemantic assertions across success and failure pathsReplay and expired plan both rejected

Follow the end-to-end verification playbook to qualify this package's documented workflow and prepare evidence for a maturity review.

Retention expectations

Treat plans, receipts, and fixtures as incident records because their timing, targets, and operator assertions may be sensitive even when the receipt fields contain no secrets. Store them with least-privilege access and encryption where required by the organization's approved incident-response, legal-hold, privacy, and records-retention policies. Assign an owner and deletion or review date in the system of record, preserve records subject to a legal hold, and securely delete expired copies and temporary staging files. This package does not choose a retention period or operate a records repository.

Emergency-use expectations

Use this sandbox during an emergency only under an approved break-glass procedure that names the authorizing role, allowed action and target, expiry, evidence owner, and required after-action review. Continue to use a unique nonce, explicit dry run, and private staging; record verification as unavailable when it cannot be performed instead of treating the action as verified. The package cannot grant emergency authority, bypass provider access controls, contact a live provider, or attest that authorization occurred.

The approver name is an operator assertion. The plan hash detects accidental or unauthorized changes to the plan content only when compared with a trusted copy; it is not a signature, approval proof, or immutable audit record. This package does not support concurrent writes by untrusted local accounts. Use private staging on shared hosts. Production mutation and trusted approval attestation remain separate work.