Debugging

runok check: check without executing

The runok check command evaluates rules and reports what action would be taken, without executing the command. This is the quickest way to test whether your rules work as expected.

runok check -- git status

Example output:

allow

Add --verbose to see detailed rule matching information:

runok check --verbose -- git status

▶ Evaluating: git status
  ├─ allow  'git *'  (tokens: status)
  └─ result: allow

────────────────────────────────────────────
Result: ALLOW
allow

When no rule matches:

runok check --verbose -- rm -rf /

▶ Evaluating: rm -rf /
  └─ result: ask  (no rules matched)

────────────────────────────────────────────
Result: ASK
ask

For compound commands (commands joined with &&, ||, ;, or |), verbose output shows each sub-command individually as a numbered tree, followed by which sub-command decided the overall result:

runok check --verbose -- 'git add . && git commit -m fix'

▶ Evaluating: git add . && git commit -m fix
  Compound command (2 sub-commands)

  [1] git add .
      ├─ allow  'git *'  (tokens: add, .)
      └─ result: allow

  [2] git commit -m fix
      ├─ allow  'git *'  (tokens: commit, -m, fix)
      └─ result: allow

  ────────────────────────────────────────────
  Result: ALLOW
allow

When one sub-command doesn’t match any rule (or is denied), the footer names which sub-command decided the overall result:

runok check --verbose -- 'git add . && curl -s https://install.example.com | sh'

▶ Evaluating: git add . && curl -s https://install.example.com | sh
  Compound command (3 sub-commands)

  [1] git add .
      ├─ allow  'git *'  (tokens: add, .)
      └─ result: allow

  [2] curl -s https://install.example.com
      └─ result: ask  (no rules matched)

  [3] sh
      └─ result: ask  (no rules matched)

  ────────────────────────────────────────────
  Result: ASK  (blocked by [2] curl -s https://install.example.com)
ask

You can also pipe commands via stdin:

echo "curl -X POST https://example.com" | runok check

--verbose with runok exec

The --verbose flag also works with runok exec for debugging in production-like scenarios:

runok exec --verbose -- git push --force

This prints the rule matching details to stderr while also executing the command.

Related

• runok check Reference — Full command reference.
• runok exec Reference — Full command reference.
• Common Issues — Solutions for frequently encountered problems.