Skip to content

Evidence and redaction

Defines minimum evidence and redaction norms for HybridOps operations.

Evidence provides non-secret records that support traceability, reproducibility, and post-run review.

In operator-facing instructions and general product copy, prefer the specific record being discussed: run record, validation result, health report, test result, or log. Use evidence when referring to this formal standard, its schemas, compliance requirements, or an assembled review package. Internal API and path names retain evidence for compatibility.

Norms

  • Evidence MUST be written for install, setup, preflight, init, module, and driver operations.
  • Evidence MUST NOT contain secrets.
  • Evidence MUST be redacted prior to persistence.
  • Evidence paths MUST be stable in structure.

Evidence locations

Evidence is stored under the runtime root:

  • Install: <root>/logs/install/<run_id>/
  • Setup: <root>/logs/setup/<scope>/<run_id>/
  • Preflight: <root>/logs/preflight/<run_id>/
  • Init: <root>/logs/init/<target>/<run_id>/
  • Module: <root>/logs/module/<module_id>/<run_id>/
  • Driver: <root>/logs/driver/<driver_id>/<run_id>/

Minimum evidence set

Evidence MUST include, at minimum:

  • run metadata identifying the operation and run_id
  • resolved non-secret inputs and resolved non-secret paths
  • execution results for subprocess calls where used (argv, rc, duration)
  • output inventory of files written (non-secret paths)

Install, setup, and preflight command records MUST contain:

  • output.log, containing the redacted output shown to the operator
  • result.json, containing the command name, redacted argument vector, start and finish timestamps, exit code, status, and platform details

The command MUST print the run-record directory after writing the record. Evidence capture MUST preserve the command exit code. Operators MUST NOT need tee or shell pipeline settings to obtain a complete record.

Additional records MAY be included where useful (plans, exports, inventories) provided they are non-secret or redacted.

Operational logging expectations:

  • Long-running driver executions SHOULD write a primary human-readable log file in the evidence directory (for example ansible.log, terragrunt.log, packer.log).
  • CLI/operator output MAY reference that file using a stable hint (for example open: <evidence>/ansible.log) without dumping full tool output to terminal.
  • If verbose streaming is enabled, streamed stdout/stderr MUST still be persisted to evidence using the same redaction policy.

Redaction requirements

  • Secret values MUST NOT be written to evidence records.
  • Token-, password-, key-, and credential-like strings SHOULD be redacted by pattern matching.
  • Redaction MUST apply to stdout/stderr captures, structured logs, and any copied output files.
  • Redaction patterns MAY evolve without a version bump.

Minimum redaction scope includes:

  • provider tokens and secrets
  • API keys and bearer tokens
  • private keys and certificates
  • service principal and service account credentials
  • email addresses where they appear in sensitive contexts

Storage and permissions

  • Evidence directories SHOULD be mode 0700 where supported by the platform.
  • Evidence files SHOULD be mode 0600 when they may contain sensitive non-secret context.
  • Evidence retention is an operational policy; evidence files are not committed to Git.

Contract references

This standard applies to: