Chio/Docs
LOGIN · JOIN

chio security

Prepare and supervise the confined runtime, then run this release's enforcement suites against the installed binaries on your own host.

Reference chio@5f63e6e

On this page

All command families · Global flags

chio security

Prepare, supervise, and exercise the confined runtime on this host.

Command synopsistext
chio security [OPTIONS] <COMMAND>

Example

Run every enforcement suite the host supports and keep the logs, exit statuses, and manifest together.

Terminalbash
chio security selftest --evidence ./deployment-evidence
Output
suite            result
cage             pass
restart          pass
caller-delivery  pass
deception        pass
temporal         pass   10 inventories, 40 tests
keyring          pass
broker           pass
7 suites passed; evidence in ./deployment-evidence

chio security selftest

Run the enforcement suites that ship with this release against the installed binaries on this host, and keep the evidence.

Command synopsistext
chio security selftest [OPTIONS] [SUITE]...
  • [SUITE]... Suites to run: cage, restart, caller-delivery, deception, temporal, keyring, broker, timing. Without one, every suite the host supports. timing runs the three constant-time harnesses and reports max|t| against the 4.5 threshold, a result that holds only for the host it ran on.
  • --list List the suites, their case counts, and what each needs from the host.
  • --evidence <DIR> Directory for the per-suite logs, exit statuses, and a SHA-256 manifest. Must be new.
  • --portable Run only the cases that need no Linux enforcement, for a developer laptop.
  • --require-all Fail instead of skipping a suite the host cannot run.
Additional behavior

Each suite drives real refusals: a confined process that tries to leave its cage, a restart in the middle of a call, a caller that presents another caller’s delivery, a tripped decoy. A suite the host cannot run (the Linux cage on macOS) is reported as skipped. Exit 0 when every selected suite passes, 1 when any fails, and 2 when --require-all is set and a suite was skipped.

chio security preflight

Prove the host, its bearer roles, its signed launch material, and its durable stores before the confined runtime starts.

Command synopsistext
chio security preflight [OPTIONS] [COMMAND]...
  • [COMMAND]... The wrapped MCP server command and its arguments, exactly as the launch passes them after --.
  • --require-enforcement Fail when the host cannot enforce the cage or the launch material authorizes without confining.
  • --signed-manifest <PATH> Publisher-signed manifest of the wrapped server.
  • --manifest-public-key <PUBLIC_KEY> Independently registered public key that signed the manifest.
  • --cage-policy <PATH> Canonical signed native-launch policy for the wrapped server.
  • --cage-policy-signer <PUBLIC_KEY> Independently pinned public key for the native-launch policy signer.
  • --server-id <SERVER_ID> Server identifier the manifest and policy must belong to.
Additional behavior

The exit code follows the worst probe severity, like chio doctor: 0 for ok, info, or warning, 1 for error, 2 for fatal.

chio security supervise

Run one service under systemd: credentials from the credentials directory, readiness on the notify socket, stop signals forwarded.

Command synopsistext
chio security supervise [OPTIONS] <COMMAND>...
  • <COMMAND>... The service command and its arguments, after --. Required.
  • --credentials-dir <PATH> Directory holding the credential files; systemd sets it for every unit with LoadCredential=. Reads CREDENTIALS_DIRECTORY.
  • --credential-env <VARIABLE=CREDENTIAL> Deliver the credential file CREDENTIAL to the service as VARIABLE. Repeat for every secret.
  • --ready-http <URL> Report readiness once a GET of this URL succeeds.
  • --ready-unix-socket <PATH> Report readiness once this Unix socket accepts a connection from the supervised service.
  • --ready-timeout <SECONDS> Seconds the service may take to become ready before it is stopped. Default 60.
  • --stop-grace <SECONDS> Seconds a stopped service may take to drain before SIGKILL. Default 30.
  • --exec Deliver the credentials and replace this process with the service instead of supervising it.
Additional behavior

With --exec it only delivers the credentials and replaces itself with the service, which is the form for ExecStartPre= checks.

chio security shadow-migrate

Verify registry evidence and atomically write a deterministic migration report.

Command synopsistext
chio security shadow-migrate [OPTIONS] --input <PATH> --output <PATH>
  • --input <PATH> Closed JSON inventory containing registered keys, manifests, receipts, and observations. Required.
  • --output <PATH> Destination for the canonical JSON report. Required.

chio security provision-reference-runtime

Provision signed launch material for one confined tool at an enforcing migration stage.

Command synopsistext
chio security provision-reference-runtime [OPTIONS] --output-dir <PATH> --cage-init <PATH> --target <PATH> --execution-uid <UID> --execution-gid <GID> --server-id <SERVER_ID>
  • --output-dir <PATH> Directory to create with every artifact; an existing one is revalidated. Required.
  • --runtime-security-dir <PATH> Directory the runtime reads the ledger and receipt material from, when it differs from the output directory.
  • --cage-init <PATH> Static position-independent chio-cage-init the policy binds. Required.
  • --max-artifact-bytes <MAX_ARTIFACT_BYTES> Signed per-artifact retention ceiling for the helper, target, and runtime files (at most 256 MiB). Default 1048576.
  • --receipt-rollback-anchor-root <PATH> Private external receipt rollback anchor directory, on a different filesystem from the receipt database. Required for the Enforced stage.
  • --broker-binding <PATH> Reviewed JSON socket path, authentication digest, and broker peer identity.
  • --tools-fixture <PATH> Reviewed tools/list fixture of the target.
  • --discover-tools Spawn the target once and review its own tools/list.
  • --target <PATH> The wrapped MCP server executable. Required.
  • --target-arg <VALUE> One argument of the wrapped server, in order. Repeat for each.
  • --working-directory <PATH> Working directory of the wrapped server; its parent directory by default.
  • --read-path <PATH> A path the wrapped server may read. Repeat for each grant.
  • --write-path <PATH> A path the wrapped server may write. Repeat for each grant.
  • --runtime-file <PATH> Interpreter or shared object a dynamically linked target needs; each must also be a read path.
  • --syscall-profile <SYSCALL_PROFILE> Reviewed syscall set; minimal by default. Values minimal, standard.
  • --execution-uid <UID> Non-root UID applied to the target before sandboxing. Required.
  • --execution-gid <GID> Non-root primary GID applied to the target before sandboxing. Required.
  • --execution-supplementary-gid <GID> Supplementary target GID, in ascending order. Repeat for each.
  • --server-id <SERVER_ID> Server identifier the manifest and the policy bind. Required.
  • --server-name <SERVER_NAME> Server name committed to the signed manifest. Default Chio reference tool.
  • --server-version <SERVER_VERSION> Server version committed to the signed manifest. Default 1.
  • --stage <STAGE> Stage the migration ledger is promoted to. Default enforced. Values shadow, enforced.
Additional behavior

Writes a static cage helper binding, the target’s digest, argument list, and working directory, the manifest’s read and write grants, and a ledger promoted through Shadow to the requested stage. An existing output directory is revalidated, not overwritten.

chio security provision-native-mcp-demo

Provision a signed native MCP launch at migration stage Disabled, to review the material before enforcing it.

Command synopsistext
chio security provision-native-mcp-demo [OPTIONS] --output-dir <PATH> --target <PATH> --execution-uid <UID> --execution-gid <GID> --server-id <SERVER_ID>
  • --output-dir <PATH> New absolute output directory, or an exact prior provision for an idempotent rerun. Required.
  • --runtime-security-dir <PATH> Absolute directory committed to runtime policy paths. Defaults to the output directory.
  • --tools-fixture <PATH> Reviewed JSON tools/list fixture used to build the signed manifest.
  • --discover-tools Spawn the target once and review its own tools/list.
  • --target <PATH> Absolute canonical MCP server executable bound into the launch policy. Required.
  • --target-arg <VALUE> One target argv element after the executable. Repeat for each.
  • --working-directory <PATH> Absolute canonical working directory. Defaults to the target’s parent.
  • --execution-uid <UID> Non-root UID applied to the target before sandboxing. Required.
  • --execution-gid <GID> Non-root primary GID applied to the target before sandboxing. Required.
  • --execution-supplementary-gid <GID> Supplementary target GID, in ascending order. Repeat for each.
  • --server-id <SERVER_ID> Server identifier committed to the manifest, policy, and migration ledger. Required.
  • --server-name <SERVER_NAME> Server name committed to the signed manifest.
  • --server-version <SERVER_VERSION> Server version committed to the signed manifest. Default 1.
Additional behavior

Disabled artifacts cannot authorize a native MCP launch. The command creates its own private signers for the review.

Read more in Harden a deployment.

PreviousCLI task index