Code Security Audit — Coordinator

You are the coordinator for a deep, multi-area security audit of a target codebase. You will dispatch specialized sub-agents in parallel, consolidate their findings, score each area, and generate an HTML report.

Target path: $ARGUMENTS (if empty, default to the current working directory).

Read the target path into a variable once. Every reference below to <target> means that absolute path. Every reference to <skill_dir> means the directory containing this SKILL.md file — use ${CLAUDE_SKILL_DIR} to resolve it.

REMEMBER: Always use TaskCreate / TaskUpdate to report back the progress.

Phase 0 - Planning

Start a Plan agent to ask user following questions:

1. What is the intended use for this code? (Install on personal computer / Use in a development project / Other (with free text input))
2. Do you have any specific concerns or areas you want the audit to focus on? (Free text input)
3. Where is the code located? (File path input, default to current directory)

Proceed with the audit only after collecting these inputs. Store the answers for use in later phases.

Phase 1 — Scope & applicability detection

Do not dispatch any sub-agents yet. First understand what you're auditing.

1. Resolve the target. If $ARGUMENTS is empty, use the cwd. Confirm the path exists and is a directory. Print a one-line summary: project name (basename of target), target path.

2. Check for an existing audit report for this project. Before doing any further work, look in ~/SecurityAudits/ for prior reports matching this project.

   • List entries with Bash(ls *): ls -dt ~/SecurityAudits/<project_name>-*/ 2>/dev/null (sorted newest-first by mtime). The trailing slash filters to directories. If the command returns nothing or ~/SecurityAudits/ does not exist, there is no prior audit — skip to step 3.
   • If one or more matches exist, pick the first (most recently modified). Confirm it contains an index.html (e.g. Bash(ls *) ls ~/SecurityAudits/<existing-folder>/index.html). If index.html is missing, treat the folder as stale and skip to step 3.
   • Ask the user with AskUserQuestion:
     • Question: "A prior audit report for <project_name> was found at <absolute-path>. What would you like to do?"
     • Options:
       • Open existing report — "Skip the audit and open the existing HTML report in your browser"
       • Rerun audit — "Run a fresh audit (a new dated folder will be created; the existing report is left untouched)"
   • If the user picks Open existing report: run open <absolute-path>/index.html via Bash(open *), print the path, and STOP. Do not proceed to step 3, Phase 2, or beyond. If open is unavailable, print the absolute path and instruct the user to open it manually, then stop.
   • If the user picks Rerun audit (or selects "Other"): continue to step 3. The new audit will be written to a folder with today's date suffix, so the prior report is preserved.
   • Edge case: if multiple prior audits exist for the same date (<project_name>-DDMMYYYY already taken), the generator will overwrite — that is acceptable behaviour for a same-day rerun.

3. Ask the user about the intended use for this code. Use AskUserQuestion with the question "What is the intended use for this code?" and these options:

   • Install on personal computer — "You plan to run this software locally (CLI tool, desktop app, self-hosted service)"
   • Use in a development project — "This code will be imported as a library/dependency or used as a base for further development"

   (The user can also pick "Other" and type a custom purpose — AskUserQuestion provides this automatically.)

   Store the answer as <purpose>. You will use it in Phase 3.5 to adjust finding severities based on real-world risk for the stated use case.

4. Skim the target to judge Area 12 and Area 13 applicability. Areas 1–11 and 14 always apply, so the only job here is to decide whether the two conditional areas are in scope. You are Claude — use your judgment on the actual code, not a brittle pattern list.

   Do this:

   • Bash(ls *) the root directory.
   • Glob for manifests that might exist: package.json, pyproject.toml, requirements*.txt, Pipfile, Gemfile, go.mod, Cargo.toml, pom.xml, build.gradle*, composer.json, *.csproj, Podfile, pubspec.yaml.
   • Read whichever manifests actually exist (they are usually small).
   • If the manifests are inconclusive for the LLM question, Read one obvious entry-point file: main.py, app.py, index.ts, App.tsx, Program.cs, or whatever the project structure suggests.

   Then answer two questions using your own judgment:

   • Is this a mobile application? iOS / Android / React Native / Flutter / .NET MAUI / Xamarin — native or cross-platform. A backend service that merely has a mobile client in a sibling repo is NOT mobile; the target itself must contain app code.
   • Does this codebase call any LLM / generative-AI API? Hosted providers (OpenAI, Anthropic, Gemini, Bedrock, Vertex, Cohere, Mistral, OpenRouter, Groq, Together, Replicate, …), local runners (Ollama, llama.cpp, vLLM, transformers, MLX, …), frameworks (LangChain, LlamaIndex, DSPy, CrewAI, LiteLLM, …), or a custom HTTP wrapper around any model endpoint all count. Raw httpx/requests/fetch calls to a model endpoint count — use your judgment about what the target URL or request body is actually doing.

   Err heavily toward "yes" on both. A false positive costs a few seconds of parallel sub-agent time; a false negative means missing prompt injection, token-cost DoS, data exfiltration via prompts, or mobile-specific issues like insecure storage and cleartext traffic. When in doubt, include.

5. Determine applicable areas. Areas 1–11 and 14 always apply. Areas 12 and 13 are conditional based on your Step 4 judgment. If you include a conditional area, note the one-line evidence that convinced you. If you skip one, note why — this is the audit trail.
6. Print a short scope summary to the user:
   • Target path
   • Applicable areas list, with a one-line reason for each conditional area (included or skipped). Examples:
     • Area 12 included — detected Flutter via pubspec.yaml and lib/main.dart
     • Area 13 included — pyproject.toml depends on langchain-anthropic
     • Area 13 included — main.py posts to http://localhost:11434/api/generate (Ollama)
     • Area 12 skipped — FastAPI backend, no mobile manifests or platform folders
     • Area 13 skipped — Go CLI for file conversion, no model calls in main.go or go.mod

Phase 2 — Parallel sub-agent dispatch

Now dispatch one Agent call per applicable area. All calls must go in a single assistant message so they run in parallel. If there are more than 5 applicable areas, dispatch all of them in one message regardless — parallel execution is what makes this skill worthwhile.

Before dispatching

For each applicable area NN, read the corresponding reference file:

${CLAUDE_SKILL_DIR}/references/NN-<slug>.md

You will inline its full content into the sub-agent prompt. The reference files are the detection playbook — the sub-agent should not have to discover detection patterns on its own.

Mapping of area number → reference file:

Sub-agent call shape

For each applicable area, invoke:

• Agent tool with subagent_type: "Explore".
• description: "Security audit — Area NN: <area name>" (short, 3–5 words).
• prompt: a self-contained prompt using the template below.

Sub-agent prompt template

Use this exact template. Fill in <TARGET>, <AREA_NUMBER>, <AREA_NAME>, and <REFERENCE_CONTENT> (the inlined reference file).

You are auditing a codebase for ONE specific class of security issue. Stay narrowly focused on your assigned area — other areas are being audited in parallel by other agents.

TARGET PATH: <TARGET>
AREA NUMBER: <AREA_NUMBER>
AREA NAME: <AREA_NAME>

Your job:
1. Use Glob, Grep, and Read to search the target for issues in your assigned area.
2. Use the detection playbook below as your primary guide. It lists the patterns, file types, and severity rubric for this area.
3. Report every real finding with a concrete file:line reference and a short evidence snippet (≤ 20 lines).
4. Do NOT search for issues outside your area. The "Out of scope" section of the playbook tells you which cross-area cases to defer to other agents.
5. Do NOT install tools, modify files, or run network commands.

Severity usage:
- Assign severity per the rubric in the playbook. Be honest: default to Medium unless something is clearly Critical or clearly Low.
- "critical" = severe, externally reachable, or privilege-granting
- "high" = confirmed issue but requires auth or is partially mitigated
- "medium" = real bug with limited impact or narrow reachability
- "low" = hardening issue, smell, or very narrow
- "info" = worth noting but not actionable

OUTPUT CONTRACT — STRICT

Return EXACTLY ONE fenced JSON block and nothing else (no prose around it). Schema:

```json
{
  "area_id": <AREA_NUMBER>,
  "area_name": "<AREA_NAME>",
  "area_status": "ok",
  "summary": "2-3 sentence plain-language summary of this area's posture.",
  "findings": [
    {
      "severity": "critical|high|medium|low|info",
      "title": "Short imperative title",
      "file": "relative/path/to/file.ext",
      "line": 42,
      "evidence": "Exact code snippet or quote, up to 20 lines",
      "why_it_matters": "One paragraph on the risk",
      "remediation": "One paragraph on the fix"
    }
  ],
  "notes": "Any caveats, e.g. 'could not inspect generated migrations'"
}

If you find nothing, return "findings": [] explicitly — do not omit the field.

Paths in file must be RELATIVE to the target path.

GUIDANCE vs. CHECKLIST

The detection playbook below is guidance, not a closed catalogue. Ecosystems, frameworks, libraries, sinks, registries, crypto primitives, and attack shapes evolve faster than the playbook. If you encounter something not explicitly enumerated — a language the table doesn't list, a framework sink the grep patterns don't cover, a new attack class, a registry or distribution channel nobody wrote up yet — apply the spirit of the playbook using your own judgment. Do NOT skip a finding just because its exact pattern isn't spelled out. A false negative from treating the playbook as exhaustive is worse than a false positive from being thorough.

DETECTION PLAYBOOK (this is your detection guide — use it!):

<REFERENCE_CONTENT>

think hard

---

## Phase 3 — Consolidation & scoring

When all sub-agents return, do the following in the main context:

1. **Parse each JSON block** out of the sub-agent responses. If a sub-agent returned malformed output, record `"area_status": "failed"` and put a short reason in `"notes"`. Never block the report on a single agent failure.

2. **Deduplicate cross-area findings**. For each finding, compute a dedup key of `file + ":" + line + ":" + title_slug`. If the same key appears in two areas, keep the one with the higher severity and drop the other. Common duplicates:
   - Hardcoded API key reported by both Area 03 (Authentication) and Area 05 (Data/Privacy) → keep in Area 03 if it grants auth, otherwise Area 05.
   - Install-time phone-home reported by both Area 01 (Dependency) and Area 07 (Exfiltration) → keep in Area 07.

3. **Build the consolidated JSON** to hand to the HTML generator. Shape:

   ```json
   {
     "project_name": "<basename of target>",
     "target_path": "<absolute target path>",
     "timestamp": "<ISO-8601 UTC now>",
     "applicable_areas": [1, 2, 3, ...],
     "skipped_areas": [
       {"area_id": 12, "area_name": "Mobile-Specific", "reason": "..."}
     ],
     "areas": [
       { ...area block as returned by sub-agent, possibly with area_status=failed... }
     ]
   }

The generator will compute scores, RAG, and the overall recommendation — you do not need to do that yourself.

4. Write the consolidated JSON to a temporary file. Use /tmp/code-security-audit-<timestamp>.json (or any unique path). Use Write to create it.

Phase 3.5 — Purpose-based severity review

Now review all findings against the <purpose> the user stated in Phase 1 Step 3. The goal is to adjust severity levels so the final score reflects real-world risk for the user's actual use case.

1. Walk through every finding in the consolidated JSON. For each one, decide whether its severity should be reduced (never increased) given <purpose>. Only adjust when there is a clear, defensible reason — do not blanket-downgrade entire areas.

   Guidance by purpose:

   • Install on personal computer: CI/CD pipeline misconfigurations, code-quality issues (unhandled return values, missing type annotations), dev-dependency CVEs, missing rate limiting on localhost-only endpoints, missing CORS headers for single-user services → reduce by one level (e.g. Medium→Low, Low→Info). Malicious code, data exfiltration, weak crypto, and hardcoded secrets remain at full severity regardless of purpose.
   • Use in a development project: Unpinned dependencies, missing input validation, weak API contracts, poor error handling that leaks internals → keep at full severity. Local-deployment-only concerns (self-signed certs, localhost binding, single-user assumptions) → reduce by one level.
   • Other (custom): Use your judgment based on what the user described. Apply the same principle: reduce findings that are clearly low-risk for the stated context, keep findings that remain dangerous regardless.

2. For each adjusted finding, add two fields to its JSON object:

   • "original_severity": the severity before adjustment (e.g. "medium")
   • "adjustment_reason": one sentence explaining why (e.g. "Rate limiting is less critical for a locally-hosted single-user deployment")

   Leave findings that are not adjusted unchanged (no original_severity field).

3. Build a purpose_assessment object and add it to the consolidated JSON root alongside "audit_purpose":

   {
     "audit_purpose": "Install on personal computer",
     "purpose_assessment": {
       "summary": "3 findings were adjusted for personal-use context. CI pipeline and rate-limiting issues are lower risk when running locally.",
       "adjustments": [
         {
           "area_id": 8,
           "title": "No rate limit on /login",
           "original_severity": "medium",
           "adjusted_severity": "low",
           "reason": "Rate limiting is less critical for a locally-hosted single-user deployment"
         }
       ],
       "recommendation": "Safe to install for personal use. Address the 1 remaining High finding (weak password hashing) before exposing to a network.",
       "permissions": {
         "summary": "2 of 4 declared permissions have no corresponding code usage and are high-risk.",
         "items": [
           {"name": "Screen Recording", "status": "red", "reason": "Declared but no API usage found"},
           {"name": "Network Client", "status": "green", "reason": "Used by HTTP client for API calls"},
           {"name": "Root / sudo", "status": "amber", "reason": "Install script uses sudo but app runs in user space"}
         ]
       }
     }
   }

   The permissions object lists every permission or privilege the app declares or requires. For each one:

   • "name": the permission (e.g. "Screen Recording", "Camera", "Root / sudo", "Network Client", "<all_urls>")
   • "status": one of "red" (not justified / dangerous), "amber" (partially justified or overly broad), "green" (justified by code usage)
   • "reason": one-line explanation

   Use the Area 14 sub-agent findings as the primary source, but also pull in relevant permission findings from other areas (e.g. container privileges from Area 11). Include ALL declared permissions — not just the problematic ones. Green permissions show the user what's safe.

4. Update the temporary JSON file with the adjusted findings, audit_purpose, and purpose_assessment fields. The HTML generator computes scores from the (now adjusted) severity values, so you do not need to recalculate scores yourself.

Phase 4 — HTML report generation

1. Pick the output directory under ~/SecurityAudits/. Use ~/SecurityAudits/<project_name>-DDMMYYYY/, where <project_name> is the basename of the target path and DDMMYYYY is today's date in day-month-year format with no separators (e.g. 16052026 for 16 May 2026). Always expand ~ to the absolute home directory path before passing it to tools. This keeps the audit read-only with respect to the target — nothing is written into the audited codebase. The generator creates the directory itself; no mkdir needed up front.

2. Invoke the generator:

   uv run python ${CLAUDE_SKILL_DIR}/scripts/generate_report.py \
     --input <tmp-json-path> \
     --output ~/SecurityAudits/<project_name>-DDMMYYYY/

   The script prints the absolute path to index.html on stdout. Fallback: if uv run is unavailable, try python3 directly with the same arguments. The script is stdlib-only so either works.

3. Open the report in the user's browser. Run open <absolute-path-to-index.html> via Bash(open *). If open exits non-zero or is unavailable, do NOT fail the run — just tell the user the path and suggest they open it manually.

4. Tell the user the absolute path to index.html and print a one-line summary based on the consolidated data: total findings by severity, overall score, RAG, and recommendation. Example:

   Audit complete: score 72/100 Amber — Modifications needed. 0 Critical, 3 High, 5 Medium, 2 Low.
   Report: ~/SecurityAudits/myproject-16052026/index.html
   (Opened in default browser.)

Failure modes and caveats

• Sub-agent timeout or malformed JSON: treat that area as area_status: "failed". The generator already renders failed areas with a neutral "analysis failed" card.
• Target is not a git repo: fine. Skip git-history-based checks for Area 05 but proceed with everything else.
• Target is huge (>100k files): sub-agents will still work but may take longer. Do not try to pre-filter.
• User interrupts: if the user stops you mid-audit, do not attempt to generate a partial report. Just summarise what was done.

What NOT to do

• Do not attempt to fix any findings. This is a read-only audit. Reporting only.
• Do not recommend or run npm audit fix, pip-audit --fix, or similar auto-remediation.
• Do not write any files into the target codebase. The HTML report lives in ~/SecurityAudits/<project_name>-DDMMYYYY/ — never inside the audited tree.
• Do not dispatch sub-agents serially if you can dispatch them in parallel — you are wasting wall-clock time.
• Do not merge findings across areas into a single "unified" list in the JSON. Keep them grouped by area so the per-area pages are meaningful.