| name | audit-machine |
| description | Use when the user wants to run a security audit on a registered machine. |
Audit Machine
Execute a security audit over SSH on a single registered machine. The audit checks for configuration drift, hardening gaps, policy compliance, and other findings. Output is timestamped and appended to the machine's audit log.
When to use
- User wants to run a fresh security scan on a machine
- Periodic audit checkpoints before/after changes
- Compliance validation for a specific target
Inputs to gather
- Machine name (required; must be registered)
- Audit depth (optional;
quick, full, or report-only; default full)
quick — fast checks only (10–30 seconds)full — comprehensive scan (5–15 minutes)report-only — regenerate markdown from the most recent raw data
Procedure
-
Resolve the data directory:
DATA_DIR="${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/security-auditor/data"
REPO_BASE="$DATA_DIR"
export REPO_BASE
-
Verify the machine is registered:
cd /home/daniel/repos/github/my-repos/Claude-Security-Auditor-Plugin
bash scripts/list-machines.sh <machine_name> --json | jq .
Fail gracefully if the machine is not found.
-
Invoke the audit:
bash scripts/audit-machine.sh <machine_name> [--quick|--full|--report-only]
-
The script runs over SSH, writes reports/<timestamp>/audit-report.md, and updates audit-log.json.
-
Extract the report path from the output and read the markdown for a brief summary. Display path and key findings to the user.
Output / side effects
- New timestamped report in
${CLAUDE_USER_DATA}/security-auditor/data/machines/<machine-name>/reports/<ISO8601-timestamp>/audit-report.md
audit-log.json updated with entry for this run- Return the report path and a one-paragraph summary of critical findings
Safety / constraints
- Audit may require root privileges on the target for comprehensive checks.
- Network latency can affect runtime; full audits may take 10+ minutes on slow links.
- The script reads system files on the target; ensure proper credentials and permissions.
