Skip to content

docs: add audit command reference page #23957

Description

@Mossaka

Parent Epic

Part of #22735

Summary

The audit epic shipped ~13K LOC with 3 CLI commands (gh aw audit, gh aw audit diff, gh aw audit report), but there are zero dedicated documentation pages in the docs site. This issue tracks creating the primary reference page.

What to Create

File: docs/src/content/docs/reference/audit.md

An exhaustive command reference covering all three audit subcommands:

gh aw audit <run-id-or-url>

  • All accepted input formats (run ID, run URL, job URL, step URL, GHES URLs)
  • Flags table: --output, --json, --parse, --repo, --verbose
  • All 25+ report sections documented (from AuditData struct in pkg/cli/audit_report.go): Overview, Comparison, TaskDomain, BehaviorFingerprint, AgenticAssessments, Metrics, KeyFindings, Recommendations, ObservabilityInsights, PerformanceMetrics, EngineConfig, PromptAnalysis, SessionAnalysis, SafeOutputSummary, MCPServerHealth, Jobs, DownloadedFiles, MissingTools, MissingData, Noops, MCPFailures, FirewallAnalysis, PolicyAnalysis, RedactedDomainsAnalysis, Errors, Warnings, ToolUsage, MCPToolUsage, CreatedItems
  • Output formats: console (stderr), JSON (stdout), markdown (--parse)
  • Caching behavior
  • GHES auto-detection

gh aw audit diff <run1> <run2>

  • What it compares: firewall domains, MCP tool invocations, run metrics
  • Flags: --format (pretty, markdown), --json, --repo
  • Diff output structure: NewDomains, RemovedDomains, StatusChanges, VolumeChanges, MCPToolsDiff, RunMetricsDiff
  • Anomaly detection rules

gh aw audit report

  • What it aggregates across runs
  • Flags: --workflow, --last, --format, --json, --repo
  • Report structure: Executive Summary, Domain Inventory, Metrics Trends, MCP Health, Error Trends
  • Cross-run thresholds (spike detection, MCP error rate, connection rate)

Also Include

  • JSON schema documentation for AuditData, AuditDiff, and CrossRunAuditReport for programmatic consumers
  • Exit codes section

Source Files to Reference

  • pkg/cli/audit.go — command definition, flags, URL parsing
  • pkg/cli/audit_report.goAuditData struct
  • pkg/cli/audit_diff_command.go — diff command flags
  • pkg/cli/audit_report_cross_run_command.go — report command flags
  • pkg/cli/audit_report_render.go — output format details

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    auditclidocumentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions