feat(audit): add machine-readable summaries

Author: altaywtf

AGENTS.md

@@ -81,6 +81,12 @@ For fast local script loops before the final check:
 ./scripts/bootstrap/verify-repo.sh --skip-security
 ```
 
+To install the same fast gate as a local pre-push hook:
+
+```zsh
+./scripts/bootstrap/install-git-hooks.sh
+```
+
 For a live machine that should use these dotfiles:
 
 ```zsh

README.md

@@ -77,6 +77,12 @@ Use repo checks before committing:
 ./scripts/bootstrap/verify-repo.sh
 ```
 
+To install the local pre-push guard for the fast repo gate:
+
+```zsh
+./scripts/bootstrap/install-git-hooks.sh
+```
+
 Use live-machine checks only on a machine that should actually use these
 dotfiles:
 

docs/agent-readiness.md

@@ -15,20 +15,22 @@ flow to drive. Agent readiness means an agent can:
 | --- | --- | --- | --- |
 | Bootable | pass | `scripts/bootstrap/brew-bundle.sh` installs shared plus profile bundles; `scripts/bootstrap/install.sh` links tracked files. | First-time macOS still needs Command Line Tools, Homebrew, and GitHub auth. |
 | Testable | pass | `scripts/bootstrap/verify-repo.sh` runs shell syntax, ShellCheck, Actionlint, diff hygiene, agent-entrypoint checks, and repo secret scans. | Live bootstrap checks require a matching personal or devbox Mac. |
-| Observable | partial | Verification and audit scripts print stable sectioned output; CI exposes Verify and Secret scanning logs. | Scripts do not emit JSON or SARIF reports yet. |
+| Observable | pass | Verification and audit scripts print stable sectioned output; security audits also support compact `--json` summaries; CI exposes Verify and Secret scanning logs. | SARIF output is not generated yet. |
 | Verifiable | pass | `.github/workflows/verify.yml`, `.github/workflows/secrets.yml`, `scripts/bootstrap/verify.sh`, `scripts/devbox/verify.sh`, and audit scripts. | Host-local service and token checks cannot run meaningfully on GitHub-hosted CI. |
 
 Overall grade: **B for a bootstrap repo**.
 
 The repo has a reliable repo gate, CI gates, and separate host-local audits.
-The remaining readiness gap is structured machine-readable audit output.
+The remaining readiness gap is richer machine-readable report formats such as
+SARIF for tools that can emit it cleanly.
 
 ## Verification Matrix
 
 | Situation | Command | What it proves |
 | --- | --- | --- |
 | Before committing repo changes | `./scripts/bootstrap/verify-repo.sh` | Scripts parse, ShellCheck passes, workflows lint, diffs are clean, agent entrypoints are valid, and secret scanners pass. |
 | Fast local loop | `./scripts/bootstrap/verify-repo.sh --skip-security` | Same repo checks without Gitleaks/TruffleHog. Run the full command before commit. |
+| Install local push guard | `./scripts/bootstrap/install-git-hooks.sh` | Adds a pre-push hook that runs `verify-repo.sh --skip-security` before pushing. |
 | Personal Mac bootstrap | `./scripts/bootstrap/verify.sh --profile personal` | Required CLIs, Homebrew bundle, mise, Codex defaults, and linked config exist on the live host. |
 | Devbox bootstrap | `./scripts/bootstrap/verify.sh --profile devbox` | Shared/devbox CLIs, Homebrew bundle, mise, Codex defaults, and linked config exist on the live host. |
 | Devbox service boundary | `./scripts/devbox/verify.sh` | process-compose and generated env/token boundaries match the local devbox contract. |
@@ -75,6 +77,5 @@ See [GitHub pipelines](github-pipelines.md) for triggers and non-goals.
 
 ## Future Improvements
 
-- Add optional JSON output to audit scripts for easier agent parsing.
-- Add an installable pre-push hook that runs `verify-repo.sh --skip-security`.
-- Add a short machine-readable summary mode for `security-audit.sh` scripts.
+- Add optional SARIF output for scanners that support it cleanly.
+- Add a lightweight report collector for comparing both devbox users in one run.

docs/security-audits.md

@@ -31,6 +31,12 @@ That command runs the repository secret scan through
 diff checks. Run `./scripts/security/audit.sh --skip-mscp` directly when you
 only need the secret scanners.
 
+For agent or dashboard consumption, add `--json`:
+
+```zsh
+./scripts/security/audit.sh --skip-mscp --json
+```
+
 GitHub Actions also runs Gitleaks and TruffleHog on pushes to `main`, pull
 requests, weekly schedule, and manual dispatch through
 `.github/workflows/secrets.yml`.
@@ -84,6 +90,9 @@ Run this from a normal personal Mac user:
 ./scripts/security/audit-personal.sh
 ```
 
+Use `./scripts/security/audit-personal.sh --json` when an agent needs a compact
+status summary.
+
 It checks:
 
 - default shells do not export `OP_SERVICE_ACCOUNT_TOKEN`
@@ -110,6 +119,9 @@ Run this from each devbox user:
 ./scripts/devbox/security-audit.sh
 ```
 
+Use `./scripts/devbox/security-audit.sh --json` when collecting per-user devbox
+audit summaries over SSH.
+
 It checks:
 
 - default shells do not export `OP_SERVICE_ACCOUNT_TOKEN`

scripts/README.md

@@ -19,6 +19,12 @@ Repository-only verification:
 ./scripts/bootstrap/verify-repo.sh
 ```
 
+Install the local pre-push guard:
+
+```zsh
+./scripts/bootstrap/install-git-hooks.sh
+```
+
 Personal bootstrap:
 
 ```zsh
@@ -36,6 +42,7 @@ Security audits:
 
 ./scripts/security/audit.sh --skip-mscp
 ./scripts/security/audit-personal.sh
+./scripts/security/audit-personal.sh --json
 ```
 
 Devbox checks:
@@ -44,6 +51,7 @@ Devbox checks:
 
 ./scripts/devbox/verify.sh
 ./scripts/devbox/security-audit.sh
+./scripts/devbox/security-audit.sh --json
 ```
 
 Before committing script changes:

scripts/bootstrap/install-git-hooks.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+hooks_dir="$repo_root/.git/hooks"
+pre_push="$hooks_dir/pre-push"
+
+if [ ! -d "$repo_root/.git" ]; then
+  printf 'not a normal Git checkout: %s\n' "$repo_root" >&2
+  exit 1
+fi
+
+mkdir -p "$hooks_dir"
+
+if [ -e "$pre_push" ] || [ -L "$pre_push" ]; then
+  if ! grep -q 'uinaf-dotfiles: pre-push' "$pre_push" 2>/dev/null; then
+    backup="$pre_push.backup.$(date +%Y%m%d%H%M%S)"
+    mv "$pre_push" "$backup"
+    printf 'backed up existing pre-push hook to %s\n' "$backup"
+  fi
+fi
+
+cat > "$pre_push" <<'HOOK'
+#!/usr/bin/env bash
+set -euo pipefail
+
+# uinaf-dotfiles: pre-push
+repo_root="$(git rev-parse --show-toplevel)"
+exec "$repo_root/scripts/bootstrap/verify-repo.sh" --skip-security
+HOOK
+
+chmod 0755 "$pre_push"
+printf 'installed %s\n' "$pre_push"

scripts/devbox/security-audit.sh

@@ -10,6 +10,7 @@ token_file="${UINAF_OP_SERVICE_ACCOUNT_TOKEN_FILE:-/var/db/uinaf/devbox-secrets/
 openclaw_env_file="${UINAF_OPENCLAW_ENV_FILE:-/var/db/uinaf/devbox-env/$devbox_user/openclaw.env}"
 openclaw_env_link="${UINAF_OPENCLAW_ENV_LINK:-$HOME/.openclaw/.env}"
 expected_admin_users="${UINAF_EXPECTED_ADMIN_USERS:-}"
+json_output=0
 warn_count=0
 fail_count=0
 secret_scan_count=0
@@ -24,6 +25,7 @@ Runs a non-destructive devbox drift audit for the current Unix user.
 Options:
   --config PATH                 local devbox config, default: ~/.config/uinaf/devbox.env
   --expected-admin-users LIST   space-separated admin users expected on this Mac
+  --json                        print a machine-readable summary instead of prose
   -h, --help
 
 The script checks secret boundaries, process-compose isolation, Git/GitHub
@@ -33,23 +35,51 @@ USAGE
 }
 
 section() {
+  [ "$json_output" -eq 1 ] && return
   printf '\n## %s\n' "$1"
 }
 
 ok() {
+  [ "$json_output" -eq 1 ] && return
   printf 'ok %s\n' "$1"
 }
 
 warn() {
   warn_count=$((warn_count + 1))
+  [ "$json_output" -eq 1 ] && return
   printf 'warn %s\n' "$1" >&2
 }
 
 fail_check() {
   fail_count=$((fail_count + 1))
+  [ "$json_output" -eq 1 ] && return
   printf 'FAILED: %s\n' "$1" >&2
 }
 
+json_string() {
+  local value="$1"
+  value="${value//\\/\\\\}"
+  value="${value//\"/\\\"}"
+  printf '"%s"' "$value"
+}
+
+print_json_summary() {
+  local status="pass"
+  if [ "$fail_count" -gt 0 ]; then
+    status="fail"
+  fi
+
+  printf '{"audit":'
+  json_string "devbox-security"
+  printf ',"status":'
+  json_string "$status"
+  printf ',"failed":%s,"warnings":%s,"user":' "$fail_count" "$warn_count"
+  json_string "$USER"
+  printf ',"devbox_user":'
+  json_string "$devbox_user"
+  printf ',"secret_scan_count":%s}\n' "$secret_scan_count"
+}
+
 mode_of() {
   stat -f '%Lp' "$1"
 }
@@ -132,6 +162,10 @@ while [ "$#" -gt 0 ]; do
       expected_admin_users="${2:-}"
       shift 2
       ;;
+    --json)
+      json_output=1
+      shift
+      ;;
     --help|-h)
       usage
       exit 0
@@ -176,7 +210,15 @@ else
   fail_check "current shell exports OP_SERVICE_ACCOUNT_TOKEN"
 fi
 
-if zsh -lic 'test -z "${OP_SERVICE_ACCOUNT_TOKEN+x}"'; then
+if [ "$json_output" -eq 1 ]; then
+  zsh_login_has_no_token="$(zsh -lic 'test -z "${OP_SERVICE_ACCOUNT_TOKEN+x}"' >/dev/null 2>&1; printf '%s' "$?")"
+elif zsh -lic 'test -z "${OP_SERVICE_ACCOUNT_TOKEN+x}"'; then
+  zsh_login_has_no_token=0
+else
+  zsh_login_has_no_token=1
+fi
+
+if [ "$zsh_login_has_no_token" = "0" ]; then
   ok "login shell does not export OP_SERVICE_ACCOUNT_TOKEN"
 else
   fail_check "login shell exports OP_SERVICE_ACCOUNT_TOKEN"
@@ -370,7 +412,11 @@ else
   fail_check "tailscale is missing"
 fi
 
-printf '\ndevbox security audit summary: %s failed, %s warnings\n' "$fail_count" "$warn_count"
+if [ "$json_output" -eq 1 ]; then
+  print_json_summary
+else
+  printf '\ndevbox security audit summary: %s failed, %s warnings\n' "$fail_count" "$warn_count"
+fi
 
 if [ "$fail_count" -gt 0 ]; then
   exit 1

scripts/security/audit-personal.sh

@@ -2,6 +2,7 @@
 set -euo pipefail
 
 expected_admin_users="${UINAF_EXPECTED_ADMIN_USERS:-}"
+json_output=0
 warn_count=0
 fail_count=0
 
@@ -14,6 +15,7 @@ Runs a non-destructive personal/non-devbox drift audit for the current Unix user
 
 Options:
   --expected-admin-users LIST   space-separated admin users expected on this Mac
+  --json                        print a machine-readable summary instead of prose
   -h, --help
 
 The script checks local secret boundaries, Git/GitHub identity state, SSH key
@@ -23,23 +25,49 @@ USAGE
 }
 
 section() {
+  [ "$json_output" -eq 1 ] && return
   printf '\n## %s\n' "$1"
 }
 
 ok() {
+  [ "$json_output" -eq 1 ] && return
   printf 'ok %s\n' "$1"
 }
 
 warn() {
   warn_count=$((warn_count + 1))
+  [ "$json_output" -eq 1 ] && return
   printf 'warn %s\n' "$1" >&2
 }
 
 fail_check() {
   fail_count=$((fail_count + 1))
+  [ "$json_output" -eq 1 ] && return
   printf 'FAILED: %s\n' "$1" >&2
 }
 
+json_string() {
+  local value="$1"
+  value="${value//\\/\\\\}"
+  value="${value//\"/\\\"}"
+  printf '"%s"' "$value"
+}
+
+print_json_summary() {
+  local status="pass"
+  if [ "$fail_count" -gt 0 ]; then
+    status="fail"
+  fi
+
+  printf '{"audit":'
+  json_string "personal-security"
+  printf ',"status":'
+  json_string "$status"
+  printf ',"failed":%s,"warnings":%s,"user":' "$fail_count" "$warn_count"
+  json_string "$USER"
+  printf '}\n'
+}
+
 mode_of() {
   stat -f '%Lp' "$1"
 }
@@ -107,6 +135,10 @@ while [ "$#" -gt 0 ]; do
       expected_admin_users="${2:-}"
       shift 2
       ;;
+    --json)
+      json_output=1
+      shift
+      ;;
     --help|-h)
       usage
       exit 0
@@ -127,7 +159,15 @@ else
   fail_check "current shell exports OP_SERVICE_ACCOUNT_TOKEN"
 fi
 
-if zsh -lic 'test -z "${OP_SERVICE_ACCOUNT_TOKEN+x}"'; then
+if [ "$json_output" -eq 1 ]; then
+  zsh_login_has_no_token="$(zsh -lic 'test -z "${OP_SERVICE_ACCOUNT_TOKEN+x}"' >/dev/null 2>&1; printf '%s' "$?")"
+elif zsh -lic 'test -z "${OP_SERVICE_ACCOUNT_TOKEN+x}"'; then
+  zsh_login_has_no_token=0
+else
+  zsh_login_has_no_token=1
+fi
+
+if [ "$zsh_login_has_no_token" = "0" ]; then
   ok "login shell does not export OP_SERVICE_ACCOUNT_TOKEN"
 else
   fail_check "login shell exports OP_SERVICE_ACCOUNT_TOKEN"
@@ -254,7 +294,11 @@ else
   warn "tailscale CLI is missing"
 fi
 
-printf '\npersonal security audit summary: %s failed, %s warnings\n' "$fail_count" "$warn_count"
+if [ "$json_output" -eq 1 ]; then
+  print_json_summary
+else
+  printf '\npersonal security audit summary: %s failed, %s warnings\n' "$fail_count" "$warn_count"
+fi
 
 if [ "$fail_count" -gt 0 ]; then
   exit 1