Vuln Assessment

Vulnerability Assessment Report Skill

What This Produces

A professional PDF vulnerability assessment report (dark navy theme, severity-coded finding cards, CVSS scores, code evidence, remediation guidance, prioritized roadmap) — the same quality as a manual pentest report, generated from a 6-phase pipeline.

Output: _Vulnerability_Report.pdf saved in the target directory.

---

Step 0 — Gather Inputs (ask the user)

Before starting, collect the minimum required information:

1. Target path

If not already specified, ask: > "Which directory should I audit? (default: current working directory)"

2. Git branch selection (if it's a git repo)

Check if the target is a git repository:

git -C  rev-parse --is-inside-work-tree 2>/dev/null

If yes, list available branches and ask:

git -C  branch -a --format='%(refname:short)'

Then ask the user: > "This is a git repository. Which branch(es) would you like to audit? > > Available branches: > - main (current) > - develop > - feature/auth-refactor > - ... > > Options: > - Single branch: Enter a branch name (or press Enter to use current) > - Multiple branches: Comma-separate names to get one report per branch > - Comparison: Two branches to highlight new vulnerabilities introduced

If the user picks multiple branches or comparison mode, run the full 6-phase pipeline independently for each branch (using git worktrees — see Branch Checkout below) and generate a separate PDF per branch. Name them: __Vulnerability_Report.pdf

3. Additional export formats (optional)

After asking about the watermark, ask: > "Beyond the PDF, would you also like any of these machine-readable exports? > > - CSV — flat spreadsheet with all findings; import directly into Excel, Jira, or any SIEM > - OCSF JSON — Open Cybersecurity Schema Framework v1.2.0 (class 2002 — Vulnerability Finding); > native ingestion format for AWS Security Lake, Splunk, Chronicle, Elastic Security, and Microsoft Sentinel > > Reply with one or more: CSV, OCSF, both, or press Enter to skip."

Save the user's answer and pass the appropriate flags to the report generator in Phase 6. If the user selects OCSF, note that it produces a standards-compliant bundle containing one event per finding, including CVSS vectors, CWE references, affected resource identifiers, remediation guidance, and full OCSF envelope metadata — ready for SOC ingestion with no post-processing required.

4. Developer Remediation Guide (optional)

Ask after question 5: > "Would you also like a Developer Remediation Guide PDF alongside the security report? > > This is an engineer-facing document with root-cause pattern analysis, before/after > code fixes, sprint roadmap, and file-by-file remediation instructions — written for > developers, not security analysts. > > Reply yes or press Enter to skip."

Save the answer. If yes, Phase 7 will run after the PDF report is complete.

---

Branch Checkout (for non-current branches)

To analyze a branch without disturbing the working tree, use git worktree:

git -C  worktree add /tmp/vuln-assess- 

Analyze from /tmp/vuln-assess- instead of the original path. After analysis is complete, clean up:

git -C  worktree remove /tmp/vuln-assess- --force

If worktree creation fails (e.g. branch has an unclean name), fall back to:

git -C  stash
git -C  checkout 
# ... analyze ...
git -C  checkout -
git -C  stash pop

---

Announce the plan

Before starting the pipeline, tell the user: > "Starting vulnerability assessment for ` on branch `. > > Phase 1 — Project Discovery > Phase 2 — Architectural Context Building > Phase 3 — Ultra-Granular Function Analysis > Phase 4 — Vulnerability Hunting (checklist sections A–V) > Phase 5 — CVE & Reference Research Enrichment > Phase 6 — PDF Report Generation > (if requested) Phase 7 — Developer Remediation Guide PDF > > I'll update you after each phase completes."

---

Phase 1 — Project Discovery

Auto-detect project shape before any deep analysis:

1. List directory structure (top 2 levels), count source lines per major module.
2. Detect: primary language(s), framework(s), entry points, config/dependency files.
3. Identify: public API surfaces, authentication boundaries, data stores, external services.
4. Auto-detect project name from: directory basename, pyproject.toml/package.json

name field, or git remote get-url origin (use repo name, strip .git).

1. Determine scope: which modules get deep analysis. Exclude tests/, migrations/,

vendor/, node_modules/, dist/, .git/ unless they contain security-relevant code.

Produce a scope summary before Phase 2:

Project:     MyService
Language:    Python 3.12 / FastAPI
Branch:      main
Entry Points: src/main.py, src/worker.py
Data Stores: PostgreSQL, Redis, S3
External:    SQS, Stripe API, Auth0
Scope:       src/ (~4,200 lines)  ·  Excluding: tests/, migrations/

If the codebase is very large (>15k lines in scope), ask the user whether to do a full audit or focus on specific high-risk modules.

Scope Narrowing (user-specified focus)

If the user specifies a narrower scope — a particular file, module, or vulnerability class — honour it:

• File/module scope: Restrict Phase 1 discovery and Phase 3 function analysis to the named

paths. In Phase 4, still work through all checklist categories, but only flag findings whose evidence lives in the named paths. State the restriction clearly in the scope summary: Scope: src/auth/ only — user-specified

• Vulnerability class scope (e.g. "check for XSS only", "focus on auth issues"):

In Phase 4, explicitly work only the relevant checklist sections (e.g. for XSS → sections L, V). Skip other sections but note the restriction: Checklist: sections L, V only (user-specified). Phase 3 function analysis should still be done — it almost always surfaces the relevant class more precisely than grep alone.

• Combined scope: Apply both restrictions together.

In all narrowed cases, note the restriction in the PDF's scope table and executive summary so the reader understands this is a partial, not exhaustive, audit.

---

Phase 2 — Architectural Context Building

> ⚠️ Tool selection — common mistake: audit-context-building:audit-context is a Skill, > NOT an Agent. Invoking it via the Agent tool will fail with "Agent type not found". > Use only the Skill tool: skill: "audit-context-building:audit-context". > (Note: audit-context-building:function-analyzer in Phase 3 IS an Agent — different tool.)

Use the Skill tool to invoke audit-context-building:audit-context. Its job is pure understanding — no bug-hunting yet. Let it do a full pass.

If the skill is unavailable (not installed), perform this analysis inline by reading the key source files identified in Phase 1 and building the context yourself.

What to extract and retain from Phase 2 (you will use this in Phases 3–4):

• Module map: what each file does and how they connect
• Data flow: untrusted input → where it flows → what it touches
• Trust boundaries: exactly where is input first validated vs. directly trusted
• State variables: mutable shared state, caches, connection pools — and who mutates them
• Auth/authz gates: where authentication is enforced, where it can be bypassed
• External interactions: every DB query, HTTP call, file read, subprocess, env var read
• Invariants: what must always be true for the system to be correct

Save this as _audit_context.md in the target directory and note the path.

Why this phase matters: Skipping to hunting without understanding the system produces a shallow list of grep-matches. Understanding the architecture first means you find the real issues — the ones that live at interaction boundaries and in assumptions that span multiple functions.

---

Phase 3 — Ultra-Granular Function Analysis

With the architectural map from Phase 2, identify the 20 highest-risk functions:

Priority criteria (rank by how many of these apply):

• Directly consumes untrusted external input (HTTP handlers, queue consumers, file parsers)
• Constructs database queries or shell commands
• Enforces authentication or authorization
• Performs cryptographic operations
• Reads/writes files using user-controlled paths
• Manages sessions, tokens, or credentials
• Crosses a trust boundary (public → internal, user → admin, tenant A → tenant B)
• Has high cyclomatic complexity or deeply nested conditionals

For each priority function, use the Agent tool with subagent_type: "audit-context-building:function-analyzer" if that agent type is available. If unavailable, perform the analysis inline using the same framework:

• Block-by-block: what each block does, what it assumes, what invariant it maintains
• First Principles: what fundamental security property must hold here?
• 5 Whys on failure: why could this break? → why would that happen? → (5 levels)
• 5 Hows on exploit: how would an attacker reach this? → how would they craft input?
• Data flow trace: follow attacker-controlled data from entry to every sink

Document per-function findings in a scratch list — these become evidence for Phase 4.

---

Phase 4 — Vulnerability Hunting

Read references/vuln_checklist.md. Work through all 22 sections systematically. The checklist covers:

• A–E: Core injection, auth, authorization, crypto, misconfiguration
• F–G: Vulnerable components, data exposure & logging
• H–I: Architecture issues, cloud-specific (AWS/GCP/Azure)
• J–K: Supply chain, business logic
• L: XSS (Reflected/Stored/DOM), CSRF, CSP, Clickjacking, Open Redirect
• M: SSRF, cloud metadata SSRF, webhook abuse
• N: Insecure deserialization (pickle/yaml/XXE), unsafe archive/file parsing
• O: API security — Mass Assignment, shadow endpoints, rate limiting, upstream API trust
• P: Advanced auth — JWT algorithm attacks, OAuth2/OIDC, GraphQL-specific, WebSocket
• Q: Security observability — audit logging, alerting, incident response readiness
• R: Insecure design — fail-secure, prototype pollution, ReDoS, HTTP smuggling
• S: Container & Docker security — Dockerfile hardening, runtime privileges, Kubernetes RBAC
• T: CI/CD pipeline security — GitHub Actions injection, secret handling, artifact integrity
• U: Infrastructure as Code — Terraform/CloudFormation secrets, IAM permissions, network exposure
• V: Frontend framework specifics — React dangerouslySetInnerHTML, Next.js SSR leakage, Vue v-html, Angular bypassSecurityTrust*

For each category, check whether the codebase has that class of issue based on your Phase 2–3 understanding. Mark categories as present / not present / N/A — every category must be considered, not just the ones with obvious grep matches.

Before working through checklist sections, initialize the findings file:

Create _vuln_findings.json in the target directory with an empty findings array:

{"findings": []}

For every confirmed finding, immediately write it to _vuln_findings.json (append to the findings array using the Write tool), then show a single compact status line:

✓ VUL-001  CRITICAL  SQL Injection in login()  app.py:35  → written

Do not reproduce the full finding card as conversation text — the JSON is the canonical record. All detail lives there; Phase 5 and Phase 6 read from it directly.

Each finding must include all fields when written:

{
  "id": "VUL-NNN",
  "severity": "CRITICAL",
  "cvss": "9.8",
  "cvss_vector": "AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
  "title": "Specific, actionable title — not generic",
  "location": "file.py:line_range",
  "description": "What the vulnerability is, why it exists, what makes it exploitable.",
  "impact": "Concrete attacker outcome — not 'could lead to data exposure'",
  "evidence": "Exact code snippet (4–15 lines) from the actual codebase.",
  "remediation": "Specific, actionable fix with correct code pattern as example.",
  "references": ""
}

The references field is left empty here and populated by Phase 5.

Severity and title guidance (unchanged — quality must not regress):

• Title: specific and actionable. Bad: "SQL Injection". Good: "Pervasive SQL Injection via Untrusted Queue Message Fields"
• Impact: concrete. Bad: "Could lead to data exposure". Good: "Full database read/write; cross-tenant data exfiltration possible"
• CVSS vector: always include the full string — see references/cvss_guide.md

Severity calibration:

• CRITICAL (9.0–10.0): Direct RCE, full DB exfiltration, auth bypass with no preconditions
• HIGH (7.0–8.9): Significant data exposure, privilege escalation, DoS, hardcoded secrets
• MEDIUM (4.0–6.9): Partial exposure, requires chaining, reliability/config issues
• LOW (0.1–3.9): Defense-in-depth gaps, minor info leakage, best-practice violations
• INFO (0.0): Observations with no direct security impact

After the first pass, do a chained-attack second pass. Individual findings are one thing, but real attacks chain vulnerabilities together. Actively look for these combinations:

• XSS → CSRF bypass: A stored XSS in one part of the app can issue authenticated requests

from the victim's session, bypassing CSRF tokens entirely — does any XSS finding enable this?

• IDOR → Stored XSS: If user A can write data into user B's record (IDOR), and that record

is later rendered in user B's dashboard as HTML, the IDOR becomes a stored XSS delivery path.

• Open Redirect → OAuth token theft: An open redirect on the OAuth redirect_uri endpoint

can be used to redirect authorization codes or access tokens to an attacker's server.

• SSRF → Cloud metadata → credential exfil: An SSRF that can reach 169.254.169.254 gives

the attacker IAM role credentials, which then allows reading secrets, S3 buckets, or further lateral movement — escalate the SSRF's severity accordingly.

• Weak session token → brute force → account takeover: If random (not secrets) is used

for session/reset tokens AND there's no rate limiting on the validation endpoint, the weakness is exploitable, not just theoretical.

• Debug endpoint + hardcoded secret: A debug/config endpoint that exposes environment

variables combined with a hardcoded fallback secret creates a direct credential disclosure path.

For each chain you find, create a separate finding (or upgrade an existing finding's severity) that explains the full attack path from initial access to final impact.

---

Phase 5 — Research Enrichment

Before invoking any skill, check whether the API keys are configured:

bash -c '[ -n "$PARALLEL_API_KEY" ] || [ -n "$OPENROUTER_API_KEY" ] && echo "available" || echo "unavailable"'

• If either key is set → use the Skill tool to invoke claude-scientific-writer:research-lookup

for every CRITICAL and HIGH finding (and optionally MEDIUM).

• If neither key is set → skip skill invocation entirely. Use your built-in CWE/OWASP/CVE

knowledge directly. Do not load the skill — it cannot function without a key and loading it wastes context budget.

Tasks for each finding (via skill or built-in knowledge):

1. Verify the CWE number and get the official weakness description
2. Find the OWASP Top 10 2021 category that applies
3. Look up notable CVEs for this pattern (especially if a library is involved)
4. Get NIST SP 800-53 control references relevant to the remediation
5. Find language/framework-specific secure-coding guidance

For each enriched finding, update its references field directly in _vuln_findings.json using the Write tool (read → patch → write). Do not reproduce finding text in conversation. Show a compact status line per finding:

✓ VUL-001  references updated  →  CWE-89 · OWASP A03:2021

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Yashvendra](https://github.com/Yashvendra)
- **Source:** [Yashvendra/claude-security-skills](https://github.com/Yashvendra/claude-security-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.