Command reference

Applies to: Kensa v0.6.0 — last updated 2026-06-22.

This chapter documents every kensa command and flag. It is the exhaustive counterpart to the task-focused chapters: for how to scan and remediate, see 04-scan-and-remediate; for rollback and the transaction log, see 05-rollback-and-history; for the mechanism catalog a rule's remediation can name, see 10-mechanisms.

Every flag below is taken verbatim from kensa <command> --help. Run that yourself any time for the authoritative form on your installed version.

Invocation

kensa [global flags] <command> [flags]

Global flags

These apply to kensa itself, before the subcommand.

Run kensa <command> --help for a subcommand's own flags.

Exit codes

verify overloads exit 1 to mean signature INVALID (tampered, wrong key, or missing key); see verify for the full table.

Environment variables

Common option groups

Several commands share the same target, rule, and output option groups. They are defined once here and referenced by each command.

Target options

For commands that connect to a host over SSH.

Sudo behaviour (passwordless vs. password, the stdin mechanism, and the fail-fast probe) is covered in 04-scan-and-remediate. Not every command exposes every row: rollback and recover omit -p/--password, and recover omits -C/--capability. Each command's section lists exactly what it carries.

Rule options

For commands that load and filter the rule corpus (check, remediate).

Positional rule.yml ... arguments are additive with --rules-dir and --rule. Default-path resolution when no rules are specified is covered in 06-rule-authoring and the chapter on install (/usr/share/kensa/rules).

Output options

Most commands take a subset of these.

detect

Probe a host and print its capability set. Read-only; no mutations.

kensa detect [flags]

Carries the full target options group (-H required).

Output options:

kensa detect -H 192.168.1.211 -u owadmin --sudo
kensa detect --host web-01 --user admin --format json

check

Run read-only compliance checks against one host or an inventory. See 04-scan-and-remediate for the workflow.

kensa check [flags] [rule.yml ...]

Carries the full target options group (-H required unless --inventory is given) plus the inventory flags below, the full rule options group, and the output options.

Inventory options (additional target options):

Output options:

Other options:

kensa check -H 192.168.1.211 -u owadmin --sudo -r /path/to/rules
kensa check --inventory hosts.ini -w 10 --sudo -r /path/to/rules
kensa check -H 192.168.1.211 -s critical -s high -r /path/to/rules
kensa check -H 192.168.1.211 -f cis-rhel9 --control cis_rhel9:5.1.12 -r /path/to/rules
kensa check -H web-01 -u admin --sudo -o jsonl rule1.yml rule2.yml

remediate

Apply failing rules to a host. Each rule runs as a four-phase atomic transaction; on validation failure the engine rolls back to the captured pre-state. See 04-scan-and-remediate.

kensa remediate [flags] [rule.yml ...]

Carries the full target options group (-H required), the full rule options group, and the output options below.

Output options:

Set KENSA_NO_AGENT=1 to disable agent mode and fall back to shell-best-effort for the kernel-atomic file handlers. Set KENSA_SIGNING_KEY for a stable evidence-signer identity.

kensa remediate -H 192.168.1.211 -u owadmin --sudo -r /path/to/rules
kensa remediate -H 192.168.1.211 -s critical -t pci -r /path/to/rules
kensa remediate -H 192.168.1.211 -f cis-rhel9 --control cis_rhel9:5.1.12 -r /path/to/rules
kensa remediate -H web-01 -u admin --sudo -o json -o oscal:/tmp/results.oscal.json

rollback

Roll back transactions using captured pre-state. Pick exactly one mode. See 05-rollback-and-history.

kensa rollback [MODE] [flags]

Mode (pick one):

Find session UUIDs first with kensa list sessions.

Target options (required for --start and --txn): -H, --host (required for those modes), -u, --user, -k, --key, -P, --port, --sudo, --sudo-password, --strict-host-keys, --no-strict-host-keys. This command does not carry -p/--password or -C/--capability.

Output options:

kensa rollback --list
kensa rollback --info 8c3a1e2b-... --detail
kensa rollback --start 8c3a1e2b-... -H 192.168.1.211 -u owadmin --sudo
kensa rollback --txn 9d4b... -H 192.168.1.211 -u owadmin --sudo   # legacy

recover

Compensate transactions interrupted before they reached a terminal status, using the durable crash-recovery journal. Each open transaction is rolled back from its captured pre-state and recorded as recovered. Holds an exclusive recover lock, so it never races a live kensa on the same store. Run it after a crash, when no live kensa is operating the host. See 05-rollback-and-history and the crash-recovery note in 10-mechanisms.

kensa recover [flags]

history

Query the transaction log. Without filters, lists recent transactions. See 05-rollback-and-history.

kensa history [flags]

kensa history                                  # 50 most recent
kensa history -n 200 --format jsonl | jq -c .  # streamable JSON Lines
kensa history -H 192.168.1.211 -S 24h          # one host, last 24h
kensa history -a by_host -S 7d                 # 7-day posture per host
kensa history --prune 30 --force               # non-interactive prune

plan

Preview a rule transaction without executing it. Returns a structured plan with captured pre-state, apply steps, validators, rollback plan, and warnings.

kensa plan [flags] rule.yml

kensa plan -H 192.168.1.211 -u owadmin --sudo --format markdown rule.yml

mechanisms

List every handler mechanism registered with the kensa engine, marked capturable (participates in atomic transactions) or non-capturable (transactional: false escape hatch). See 10-mechanisms for the catalog and reversal levels.

kensa mechanisms [flags]

coverage

An alias for mechanisms today; printing a deprecation warning on stderr. With --framework, it reports which controls in the named framework are referenced by rules in the loaded corpus (the rule IDs per control). The report is numerator-only (controls with rules, not the framework's full control set) because kensa does not bundle an external control catalog yet.

kensa coverage [flags]
kensa coverage --framework FRAMEWORK --rules-dir DIR [flags]

Without --framework (alias mode): only -h, --help.

With --framework (coverage report):

kensa coverage --framework cis_rhel9 --rules-dir /path/to/rules
kensa coverage -f nist_800_53 -r /path/to/rules --format json
kensa coverage -f cis_rhel9 -r /path/to/rules --full

Migrate scripts that rely on the mechanism listing to kensa mechanisms before upgrading: kensa coverage changes meaning in v0.2.0.

list

Introspection commands for the rule corpus and the transaction store.

kensa list <subject> [flags]

list frameworks

Lists every framework_id in the loaded corpus with the count of distinct controls referenced and distinct rules referencing each. Counts are DISTINCT, not entry-counts.

kensa list frameworks --rules-dir DIR [flags]

list sessions

Lists recent sessions in the transaction store. The session_id column is the UUID needed by kensa diff.

kensa list sessions [flags]

info

Multi-criteria lookup over a loaded rule corpus. Pick one mode; filters compose with a positional QUERY (case-insensitive substring search over title + description). --rules-dir is required.

kensa info [MODE] --rules-dir DIR [filters] [QUERY]

Mode (pick one):

Filter options (compose with QUERY; the framework shortcuts also narrow within --rule/--control):

--cis, --stig, and --nist are mutually exclusive.

Output options:

kensa info ssh --rules-dir /path/to/rules                # substring search
kensa info ssh --cis --rhel 9 --rules-dir /path/to/rules # SSH rules in CIS RHEL9
kensa info --rule sysctl-ip-forward-disabled --rules-dir /path/to/rules
kensa info --control cis_rhel9:5.1.12 --rules-dir /path/to/rules
kensa info --list-controls cis_rhel9 --rules-dir /path/to/rules
kensa info file --rules-dir /path/to/rules --limit 0     # no truncation

diff

Compare two stored sessions and emit the per-rule drift report: status changes, rules added (in SESSION_ID_2 only), and rules removed (in SESSION_ID_1 only). The from → to direction follows git-diff convention, so SESSION_ID_1 is the earlier snapshot. Comparing across hostnames is allowed (a stderr note discloses the cross-host scope). Find session IDs with kensa list sessions.

kensa diff SESSION_ID_1 SESSION_ID_2 [flags]

kensa list sessions                       # find session IDs first
kensa diff <id1> <id2>                     # compact drift report
kensa diff <id1> <id2> --show-unchanged    # include unchanged rules
kensa diff <id1> <id2> --format json       # programmatic output

verify

Verify the Ed25519 signature on a kensa evidence-envelope JSON file. The public key is looked up by the envelope's signing_key_id in a trust directory (a directory of .pub files produced by kensa-keygen).

kensa verify <evidence-file> [flags]

Default trust directory, in priority order: $KENSA_CONFIG_DIR/keys/, then $XDG_CONFIG_HOME/kensa/keys/, then $HOME/.config/kensa/keys/. Override with --trust-dir.

Exit codes (verify-specific):

Critical failure modes that exit 1 (not 2): signature mismatch (tampered after signing), unknown key (signing_key_id has no .pub in the trust dir), wrong key (signature doesn't match the found .pub), and unknown schema version (envelope from a future kensa).

Success warnings that still exit 0: signed_by_rotated_key (authentic but signed by a rotated-out key) and signing_key_id_mismatch (the signature is real but the matched key's id disagrees with the envelope's signing_key_id; investigate).

kensa verify evidence.json
kensa verify evidence.json --trust-dir /etc/kensa/keys
kensa verify evidence.json --format json | jq -r .valid

migrate

Apply pending schema migrations to the SQLite store and backfill synthetic sessions for pre-Phase-4 transactions. Idempotent: a second run finds no work and exits 0. Pre-Phase-4 transactions (rows whose session_id is NULL) are grouped one synthetic session per host_id, with subcommand legacy-backfill so they're distinguishable from real sessions in later kensa history / kensa diff runs.

kensa migrate [flags]

kensa migrate
kensa migrate --db /var/lib/kensa/results.db
kensa migrate --quiet

version

Print the kensa binary version. The top-level --version flag is the canonical GNU/POSIX form; this subcommand is preserved for backward compatibility and is planned for removal in v0.2.0.

kensa version

agent

kensa agent runs kensa as a stdio agent on the target host. It is an internal command; remediate spawns it on the target over SSH (as root via --sudo) to drive the kernel-IO primitives directly; you do not invoke it by hand. Run kensa agent --help on the target for its protocol flags. See 10-mechanisms for which handlers use the agent path and KENSA_NO_AGENT=1 to opt out.

Next

That completes the operator guide. For the rule-authoring schema and mechanism details referenced throughout, return to 06-rule-authoring and 10-mechanisms.