docs(audit): add JSON output schema reference for runok audit --json#338
Merged
Conversation
intent(audit): let users write jq queries against audit logs without reading runok source. cli/audit.md only had a partial command_evaluations description and no top-level / enum / nested-object reference. decision(audit): split into a dedicated cli/audit-log-schema.md page rather than expanding cli/audit.md, mirroring how configuration/schema.md is its own reference page separate from feature pages. cli/audit.md keeps the usage-focused content and links out for the field reference.
intent(audit): fix incorrect schema claims in the new audit-log-schema page. The first revision documented values that the production writers never produce, which would mislead anyone writing jq queries. learned(audit): runok check does not emit audit log entries (CheckAdapter.is_auditable() is false), so endpoint_type is exec or hook only. learned(audit): no-rule-match cases never produce action.type "default" in the JSON. From<Action> for SerializableAction maps only Allow / Deny / Ask, and rule_engine.default_action returns one of those three. SerializableAction::Default exists for the TUI formatter and roundtrip tests, not for audit JSON output. learned(audit): chrono Utc::now().to_rfc3339() emits sub-second precision with a +00:00 offset (e.g. 2026-04-29T04:09:48.090565+00:00), not the Z form. jq literal-string comparisons need to match this shape. learned(audit): sandbox_preset is also null when compound branches match different presets (SandboxInfo::MergedPolicy path), not only when no sandbox was applied.
intent(release-notes): satisfy the CLAUDE.md rule that next.md entries must carry a PR link before merge.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #338 +/- ##
==========================================
+ Coverage 88.75% 88.77% +0.01%
==========================================
Files 53 53
Lines 12317 12317
==========================================
+ Hits 10932 10934 +2
+ Misses 1385 1383 -2
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a dedicated documentation page for the runok audit --json schema, providing a comprehensive field-by-field reference. It refactors the existing audit.md file to link to this new page, removes redundant descriptions, and updates the sidebar ordering for several CLI documentation pages. The release notes are also updated to include the new schema reference. I have no feedback to provide.
intent(audit): keep the reference focused on the current schema. Pre-v0.3.0 shape changes and the legacy-read compatibility note are release-note material, not reference material — they don't help someone parsing today's output with jq.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Purpose
runok audit --jsonwithjqlook up each field's type, possible values, and omission conditions without opening the runok source.Approach
cli/audit-log-schema.mdcovering every field of onerunok audit --jsonentry.command_evaluationsexplanation incli/audit.mdwith a link to the new page so the usage and reference pages serve different reader paths.Design decisions
Where to place the doc
cli/audit-log-schema.mdconfiguration/schema.mdis positioned alongside the feature pages.cli/audit.mdfield-by-field to absorb itcli/audit.mdbecomes overloaded.