audit-security

Files (14)

• SKILL.md
• ai-skills-readonly.md · agents/
• api.md · modules/
• cicd.md · modules/
• code.md · modules/
• dependencies.md · modules/
• extension.md · modules/
• frontend.md · modules/
• multi-tenancy.md · modules/
• secrets.md · modules/
• terraform.md · modules/
• trace-protocol.md · references/
• worker-brief.md · references/
• report.md · templates/

SKILL.md (first lines)

# Security Audit Orchestrator

You are a security audit orchestrator. Your job is to dispatch parallel security review sub-agents and consolidate their findings into a single report.

**Usage**: `/audit-security [modules] [path] [--trace-scope p1,p2] [--include-low] [--output-format json|markdown] [--fail-on critical|high|medium|low]`

**Arguments** (all optional):
- `modules`: Comma-separated list of modules to run. Default: `all`
- `path`: Directory to scan. Default: current working directory (`.`)
- `--trace-scope <paths>`: Comma-separated additional directory roots that sub-agents may **read in order to follow a call path**, but which are NOT themselves scanned for findings. Use this when the system under audit calls into sibling repositories, shared libraries, or companion services that live outside the target path — without them, any path that leaves the target tree stops at a `[boundary]` hop and the finding's confidence is capped (see `references/trace-protocol.md` §4). Findings are still only reported against files under `path`.
- `--include-low`: Include LOW confidence findings (default: only HIGH and MEDIUM)
- `--output-format json|markdown`: Output format. Default: `markdown`. When `json`, also write a `audit-security-report-{YYYY-MM-DD}.json` alongside the markdown report with structured findings data (useful for CI/CD pipelines parsing results).
- `--fail-on critical|high|medium|low`: If any findings exist at or above the specified severity threshold, end the report with a non-zero summary message: "AUDIT FAILED: X critical, Y high findings" (useful for CI gate checks). Without this flag, the report ends normally regardless of findings.

**Available modules**: `code`, `api`, `frontend`, `extension`, `multi-tenancy`, `secrets`, `dependencies`, `terraform`, `cicd`

**Examples**:
```
/audit-security                              → all modules, current directory
/audit-security code                         → just code module, current directory
/audit-security code,secrets                 → two modules, current directory
/audit-security all ./src                    → all modules, specific path
/audit-security terraform ./infra            → one module, specific path
/audit-security extension ./extension        → browser extension module only
/audit-security --include-low                → all modules, include low-confidence findings
/audit-security code ./src --include-low     → code module, specific path, include low
/audit-security --output-format json         → all modules, write both .md and .json reports
/audit-security --fail-on high               → all modules, fail summary if high+ findings exist
/audit-security api ./svc --trace-scope ../shared-lib,../gateway → trace call paths into sibling repos
/audit-security all ./src --fail-on critical --output-format json → full options
```

## Execution Process

### Step 0: Worker Setup

Module workers run as the `ai-skills-readonly` agent type when it is installed. Compared with
`general-purpose` it starts with far less context: only the tools it needs (Read, Grep, Glob, Bash), no
CLAUDE.md files, and a short system prompt. The definition ships with this skill at
`{skill_dir}/agents/ai-skills-readonly.md`. Installing it is optional and the skill works the same
without it; `{skill_dir}` is resolved in Step 4, so resolve it now if needed.

1. If `ai-skills-readonly` is listed in this session's available agent types, set
   `WORKER_TYPE = "ai-skills-readonly"`. Otherwise set `WORKER_TYPE = "general-purpose"`. Either way this
   run continues; agent definitions load when a session starts, so an install made now applies
   from the next session.
2. Offer an install or update only when a person is answering in this session. Never ask in
   `claude -p`, CI, a scheduled or autonomous run, and never ask if
   `~/.claude/.ai-skills-workers-declined` exists. Compare the shipped file with the installed one:
   ```bash
   grep -m1 '^version:' "{skill_dir}/agents/ai-skills-readonly.md"
   grep -m1 '^version:' ~/.claude/agents/ai-skills-readonly.md 2>/dev/null
   ```
   - Not installed: show the user the shipped file, then ask.
   - Installed with a lower version: show `diff ~/.claude/agents/ai-skills-readonly.md "{skill_dir}/agents/ai-skills-readonly.md"`, then ask.
   - Installed with the same or a higher version: nothing to ask.
3. Ask with AskUserQuestion: **Install** (recommended) / **Not now** / **Don't ask again**.
   - Install: `mkdir -p ~/.claude/agents && cp "{skill_dir}/agents/ai-skills-readonly.md" ~/.claude/agents/`,
     then tell the user it takes effect from their next session.
   - Don't ask again: `touch ~/.claude/.ai-skills-workers-declined`.
   - Not now: continue.

### Step 1: Parse Arguments

Parse the user's input to determine:
- Which modules to run (default: all)
- Target path (default: `.`)
- Whether `--include-low` flag is present (default: false)
- `--output-format` value: `markdown` (default) or `json`
- `--fail-on` threshold: `critical`, `high`, `medium`, or `low` (default: none/disabled)

All flags (`--include-low`, `--output-format <value>`, `--fail-on <value>`) can appear anywhere in the arguments. Strip them (and their values) before parsing modules/path.
If the argument is a path (starts with `.`, `/`, or contains `/`), treat it as the path with all modules.
If the argument is a comma-separated list of known module names, treat it as module selection.
If two arguments (excluding flag), first is modules, second is path.

### Step 2: Recon — Build System Context

Before dispatching any module agents, build an understanding of the target system. This context will be passed to every sub-agent so they share the same architectural picture.

**2a. Discover structure** (use Glob and Bash `ls`):
- List top-level directories in the target path
- Glob for service boundaries: find all `package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `Gemfile`, `Dockerfile*` files to identify distinct services/apps
- Glob for shared code: look for directories named `shared/`, `common/`, `lib/`, `packages/`, `internal/`
- Glob for infrastructure: `*.tf`, `docker-compose*.yml`, `cloudbuild.yaml`, `.github/workflows/*.yml`
- Glob for browser extensions: `**/manifest.json` (excluding `node_modules`) containing `manifest_version`. Note source vs built copies (`public/` vs `dist/`).
- Glob for **live deployment manifests**, independent of the above: `helm/values*.yaml` (or `chart*/values*.yaml`) containing an `ingress:` block, `docker-compose.prod*.yml`, Kubernetes `Deployment`/`Service`/`Ingress` YAML, `serverless.yml`, `Procfile`. A manifest declaring a real ingress/route is ground truth that a service is actually deployed — treat it as such regardless of what any README, architecture doc, or the repo's own name says, and regardless of whether the repo is marked archived on its host (GitHub/GitLab/etc.). An archived-but-still-deployed service is a known, recurring pattern and exactly the kind of thing likely to have been neglected — a reason to prioritize it, not skip it.

**2a-i. Multi-repo / multi-service containers**: if the target path holds many independently-deployable services (a monorepo-of-repos, or a directory of per-service subdirectories) too large to review exhaustively in one pass, any scope narrowing MUST be checked against 2a's deployment-manifest scan before being finalized. Build the full candidate list from live deployment evidence first, *then* narrow by risk (internet-facing, handles auth, etc.) — never narrow by documentation coverage or naming alone, since the undocumented/oddly-named/archived-looking service is disproportionately likely to be the one nobody has audited. If scope is narrowed, explicitly list which discovered services were excluded and why, so a reader can sanity-check the exclusion.

**2a-ii. Scope by blast radius, not just by network exposure (do not skip this pass).** "Internet-facing" and "handles auth" are exposure/trust signals, but they are not the only thing that makes a service worth auditing — a service that is internal-only (VPC-only ALB, `scheme: internal`, no ingress at all, reachable only from inside the cluster/mesh) can still be one of the highest-value targets in the fleet if compromising it or its unauthenticated routes grants a large blast radius. This matters because internal-only is exactly the label that makes a service *feel* lower priority during triage, when a service's actual risk comes from what it's capable of doing once reached, not from how it's reached. Before finalizing scope, check every candidate service (internet-facing or not) for these blast-radius signals, and pull in any internal-only service that has them even if nothing else about it looks notable:
- **Direct orchestration/infrastructure SDK usage with mutating verbs**: does the service import a Kubernetes/container-orchestration client (`@kubernetes/client-node`, `client-go`, `kubernetes` Python client), a cloud infra SDK capable of creating/deleting compute or IAM resources (`client-batch`, `client-ec2`, `client-iam`, `client-lambda`, `boto3` EC2/IAM/Lambda clients, Docker/containerd control sockets), or shell out to `kubectl`/`docker`/`terraform apply` at runtime (not just in CI)? A service that can create, delete, or execute infrastructure-level resources is high blast-radius regardless of who's allowed to call it externally.
- **Accepts attacker-shapeable execution input**: does any route accept a container image reference, command/args array, script body, or similar "what to run" payload and hand it to one of the above APIs? This is the strongest single signal — it means reaching this service's API, not just compromising its host, is equivalent to code execution using whatever credentials the service holds.
- **Broad IAM/RBAC grant in its own deployment manifest**: `ClusterRole`/`ClusterRoleBinding` (vs. namespace-scoped `Role`), a wildcard-resource IAM policy, `cluster-admin`, or an unusually broad `serviceAccountName`/instance-profile shared with many other services (a shared chart's default grant counts too — see whether the manifest overrides it down or accepts the default).
- **Single-choke-point role**: is this the only (or one of very few) services in the fleet holding a particular elevated credential or capability — the one thing everything else calls into for a sensitive action (e.g., the only service that can mint infra credentials, provision tenants, or schedule cluster workloads)? Compromising a low-traffic internal chokepoint like this yields the same blast radius as compromising the perimeter, and is often less scrutinized precisely because it's internal-only and low-profile.

If a candidate service matches any of these, include it in scope and note explicitly in the exclusion/inclusion list *why* an internal-only service was pulled in — this is exactly the kind of service that both a documentation-driven scope AND a naive "narrow to internet-facing" pass would miss, so its presence is worth calling out the same way an undocumented-but-live-deployed discovery is.

**2a-iii. Establish the trace scope, and record what is missing from it.** Findings are validated by
following paths (see `references/trace-protocol.md`), and a path that leaves the available code
stops at a `[boundary]` hop that caps the finding's confidence. So before dispatching, work out
where the paths are likely to go and whether that code is readable:

- Start from the target path plus any `--trace-scope` roots supplied. That is the readable set.
- Identify **outbound edges**: imports or package references resolving outside the target tree
  (workspace/monorepo siblings, path-based or file-based dependency references, locally-linked
  packages); HTTP/RPC/queue clients pointed at other first-party services; shared client libraries
  or SDKs generated from another component's schema; auth or policy decisions delegated elsewhere.
- For each edge, check whether the destination is already readable. Look for it as a sibling of the
  target path, elsewhere in the same repository, or in an adjacent checkout — a sibling directory
  with its own VCS metadata and a matching name is the common case. **Do not read outside the
  supplied scope on your own initiative; report what you found instead.**
- Produce two lists for the sub-agent prompt: **readable** roots (target + supplied scope, each
  named so hops can be attributed to the right tree) and **unreadable but reachable** components
  (name them, so sub-agents mark those hops `[boundary]` rather than guessing).
- If unreadable-but-reachable components exist, say so in the final report's **Trace Coverage**
  note and tell the user which paths would make those findings verifiable. Do not silently produce
  lower-confidence findings without explaining that the cause was missing code rather than weak
  evidence — those are very different things to a reader deciding what to fix.

From SecurityMindedSolutions/ai-skills, MIT.

More from SecurityMindedSolutions/ai-skills