Commands

This page is the command contract for operators running governed workflows and reviewers checking command-linked artifacts.

Quick reference links

• Reference
• Commands (current page)
• Proof Artifact Classes
• Glossary
• man witnessops(7) — draft; not published as a primary public page

1. Problem this page solves

Command names are easy to remember. Command semantics are where drift happens.

This page fixes that by defining:

• exact command entry points
• usage boundaries for governed vs exception paths
• expected artifacts and observable outputs for review

2. What you should understand after reading

After this page:

• operators can run the five-command lifecycle without guessing side effects
• approvers and reviewers can map command actions to state.json, receipt.json, and run artifacts
• both lanes can separate command guarantees from broader policy or verification claims

Fleet and mesh operators (not this public site)

Public buyer docs describe the proof-package path only. Fleet / mesh operators use internal OffSec mesh documentation and tooling that is not published on this docs site and is not part of the public product contract.

The runbook helper commands below apply to the witnessops-offsec engagement layout (ops/engagements/) when that layout is in use. They are not a public hunt loop and do not replace the buyer proof path on /verify.

3. Command surface and lifecycle order (runbook helpers)

The runbook helper surface is intentionally narrow:

1. new-engagement
2. runbook-exec
3. runbook-state
4. runbook-approve
5. runbook-resume

Use this order for normal governed execution. Repeated runbook-state checks are expected. Repeated runbook-resume is safe for interrupted runs.

4. Command semantics, boundaries, and outputs

new-engagement

bash automation/helpers/new-engagement.sh <engagement-name>

Semantics: initializes an engagement workspace at ops/engagements/<engagement-name>/.

Expected outputs:

ops/engagements/<engagement-name>/
├── scope/
├── recon/
├── scans/
├── loot/
├── notes/
└── report/

Usage boundary: this command does not set scope or execute runbooks. Populate scope/in-scope.txt before runbook-exec.

runbook-exec

bash automation/helpers/runbook-exec.sh <runbook-id> \
  --target <target> \
  --engagement <engagement-name>

Semantics: validates runbook inputs, creates a timestamped run directory, enforces scope by default, executes ordered steps, and emits receipt-linked artifacts when the run reaches a terminal state.

Expected outputs: a run directory under ops/engagements/<engagement>/report/drafts/ with state.json, manifest.json, hash-manifest.txt, runbook-summary.md, step logs, and receipt.json at terminal completion.

Options:

Usage boundary: --no-scope and --lab are not normal production-governed paths. Review Lab Mode and Scope Bypass before use.

runbook-state

bash automation/helpers/runbook-state.sh <engagement-name> <run-id>

Semantics: read-only state inspection for a run.

Expected outputs: formatted status on stdout, such as status, completed steps, and pending step or gate. With --json, raw state.json.

Usage boundary: this command does not mutate run state, approve gates, or resume execution.

runbook-approve

bash automation/helpers/runbook-approve.sh <engagement-name> <run-id> --approve

Semantics: writes an explicit approval event for the currently gated step in paused state.

Expected outputs: updated state.json approval record with step, approver identity, and timestamp, later embedded in receipt.json.

Usage boundary: approval records permission. They do not execute the gated step. Use runbook-resume to continue.

runbook-resume

bash automation/helpers/runbook-resume.sh <engagement-name> <run-id>

Semantics: continues from the next incomplete step in state.json. If a step was interrupted while running, it restarts that step from the beginning.

Expected outputs: additional step artifacts in the same run directory and final receipt.json when terminal.

Usage boundary: resume does not bypass future gates or scope checks. It re-enters governed step flow.

5. Explicit scope limits and non-claims

This page defines command behavior only. It does not:

• replace Governance, Authorization Model, or escalation policy
• claim canonical bundle-verification or retained-reference corpus semantics as part of this command contract
• prove tool correctness, operator or approver judgment quality, or business-impact conclusions
• expose internal-only proof implementation detail beyond operator and reviewer-visible artifacts

6. Operator and reviewer crosslinks

Operator lane

1. New Operator
2. Runbooks
3. Is This In Scope?
4. What Evidence Is Required?
5. Sensitive Artifact Handling

Approver and reviewer lane

1. Manager / Approver
2. Receipts
3. How to Verify a Receipt
4. Receipt Spec
5. Threat Model

7. Next-page handoff

Next, read Proof Artifact Classes to align command outputs with current artifact names, ownership lanes, and status boundaries.