Web App Security Skill

npx --yes web-app-security-skill audit . --fail-on never

--fail-on never lets the first report finish without turning a suspected lead into a failing CI claim. This command reads local project files, does not contact a deployment and does not edit code. For each actionable result, the report gives you:

• the security term, a plain-language explanation and a realistic consequence;
• what the evidence proves and what still needs human or runtime confirmation;
• a reviewable change, likely product side effects, rollback conditions, and separate security and normal-behavior retests.

See the result

Audit an intentionally unsafe local source file, inspect the explanation and proposed change, then run both the security retest and the fixture's normal behavior test. Nothing reaches the network and no project dependency is installed.

git clone https://github.com/parousia8888/web-app-security-skill.git
cd web-app-security-skill
npm run demo -- --out ./demo-output

Read the generated before / proposed change / retest evidence, then inspect demo-output/demo-result.json, summary.md, before.json, hardening.patch, after.json, and functional-retest.txt. Every public demo fact is derived from demo-result.json; the repository check reruns the fixture and fails if any surface disagrees.

For the complete install-to-uninstall path, follow the tested first project tutorial.

What's new in v0.5.4

v0.5.4 corrects how detector evidence is named and adds executable guards for failures seen during real project review. It does not increase the stable detector count:

• Accurate evidence name: the author-maintained planted suite is now rule-contract conformance, with 22 positive/negative/state contracts. It no longer uses TP/FP language that could be quoted as production accuracy.
• Observed failures become gates: four historical correctness failures and one numeric-SVG DOM sink review case now execute against product code. The fifth remains a visible expected_benign_match; no blanket suppression is added.
• Try-now command follows npm latest: the main-branch first trial omits a version pin. Reusable CI, signed releases and verified installation remain fixed to a version or full commit.
• No detector-count inflation: stable detection remains 20 built-in risk rules, 2 evidence-integrity rules and 8 opt-in external-adapter rules.

The v0.5.0 explanation contract remains: every v3 source finding includes the professional term, ordinary-language meaning, realistic consequence, evidence boundary, reviewable proposal, alternatives, likely side effects, owner decisions, separate security/functional retests and rollback. The CLI does not edit the project. Stable detection remains 20 built-in risk rules, 2 evidence-integrity rules and 8 opt-in external-adapter rules, with built-in depth concentrated on JavaScript/TypeScript and Python Web code.

Exact support and limits are in the compatibility matrix, stable rule corpus, rule-contract conformance, historical real-world regressions and ordinary-project review. MCP and additional stable rules are deferred behind the documented architecture gates. The signed v0.5.3 GitHub assets and provenance, verified installer, public npm package and signed v1 Action alias have passed their public checks. The installer below defaults to v0.5.3.

Install

Zero-install CLI trial

Try the CLI without keeping an installation:

npx --yes web-app-security-skill audit . --fail-on never

Claude Code plugin

Install the Claude Code plugin from this repository marketplace in one shell line:

claude plugin marketplace add parousia8888/web-app-security-skill --scope user && claude plugin install web-app-security-skill@web-app-security --scope user

Inside an existing Claude Code session, the equivalent commands are:

/plugin marketplace add parousia8888/web-app-security-skill
/plugin install web-app-security-skill@web-app-security

Verified multi-surface installation

For a signature- and checksum-verified multi-surface installation, the command below installs the skill for Claude Code and Codex, plus the ordinary CLI under ~/.local/bin. Existing installs are refused unless you explicitly pass --force, which creates timestamped backups before replacement. It downloads an immutable bootstrap, verifies its SHA-256 before execution, then verifies the selected release manifest, checksums, SBOM, source commit and archive before installation.

( set -eu; p="$(mktemp "${TMPDIR:-/tmp}/web-app-security-bootstrap.XXXXXX")"; trap 'rm -f "$p"' EXIT HUP INT TERM; curl --proto '=https' --proto-redir '=https' --tlsv1.2 --fail --silent --show-error --location --output "$p" 'https://raw.githubusercontent.com/parousia8888/web-app-security-skill/cf6bca040dc1d78587f04ded2ace10a08312f0c5/scripts/bootstrap-install.sh?immutable=cf6bca040dc1d78587f04ded2ace10a08312f0c5'; node -e 'const c=require("node:crypto"),f=require("node:fs"),p=process.argv[1],e=process.argv[2],a=c.createHash("sha256").update(f.readFileSync(p)).digest("hex");if(a!==e){console.error(`bootstrap SHA-256 mismatch: ${a}`);process.exit(1)}' "$p" '0f203b986f75f1359fee0c0c5251ba0dbeec08a857b67415702d5f05f73f2faf'; sh "$p" )

Select a surface when needed:

sh bootstrap-install.sh --target claude
sh bootstrap-install.sh --target codex
sh bootstrap-install.sh --target cli
sh bootstrap-install.sh --target both   # Claude Code + Codex

The shortened examples assume you already downloaded and verified bootstrap-install.sh using the command above. Explicit-version, offline/manual, attestation and trust-anchor details are in verified installation. Supported environments and current limits are recorded in the compatibility matrix.

Check, upgrade, or remove an installation:

webapp-security version
# Run the verified bootstrap with --mode upgrade for a recognized installation.
sh bootstrap-install.sh --mode upgrade
webapp-security uninstall

upgrade replaces only installations carrying a recognized Web App Security Skill marker (or the documented legacy Skill identity), and keeps timestamped backups. uninstall removes recognized current installs but preserves those backups. Unknown directories and launchers are refused even with install --force.

Run the first project

Open the target repository in Claude Code or Codex and send this prompt:

webapp-security start .

This creates a private project identity plus .webapp-security/runs/<run-id>/security-scope.yml, records detected framework, package manager, lockfile and deployment/config paths, and performs no network access. Review the scope, then send:

Use $web-app-security on this repository. Start with source and local checks only. Record scope and assumptions. Classify every result as confirmed, suspected, unknown, or not_applicable. Prepare the smallest reviewable hardening patch, do not apply risky or production changes without approval, retest every applied fix, and finish with fixed, remaining, and unreached risks.

The deterministic source path can then run as:

webapp-security audit .webapp-security/runs/<run-id> --fail-on high
webapp-security explain <finding-id> --report .webapp-security/runs/<run-id>/report.json
webapp-security repair-plan <finding-id> \
  --report .webapp-security/runs/<run-id>/report.json --out ./repair-review
webapp-security start . --run-id <retest-run-id>
webapp-security retest .webapp-security/runs/<retest-run-id> \
  --baseline .webapp-security/runs/<run-id>/report.json

# Review-noise filters for the built-in adapter only
webapp-security audit . --since HEAD~1 --fail-on never
webapp-security audit . --staged --fail-on never

--since excludes untracked files. --staged reads the Git index, not unstaged working-tree content. Neither mode can be combined with external adapters or baseline/retest comparison.

The default is the bundled, network-free source adapter. Optional external adapters are explicit:

webapp-security doctor . --adapter all --json
webapp-security audit . --adapter checkov --adapter gitleaks --adapter opengrep --adapter osv --fail-on never

Tested versions are Checkov 3.3.9, Gitleaks 8.30.1, Opengrep 1.27.0 and OSV-Scanner 2.5.0. The CLI and Action do not download them. Checkov runs only three fixed root Dockerfile/GitHub Actions rules with --skip-download; it may query PyPI for version metadata but does not upload project source. Opengrep uses only the bundled, digest-pinned two-rule local ruleset and makes no network request; OSV-Scanner may query the public OSV database. Project dependencies are not executed. Compose, Terraform, Kubernetes and the rest of Checkov are not stable coverage. A blocking external-adapter run additionally requires --acknowledge-alert-policy after the consuming repository accepts the responsibilities in docs/alert-policy.md. See the adapter protocol for failure, redaction and version semantics.

Each source audit writes v3 JSON, Markdown, HTML, SARIF, JUnit, a SHA-256 sidecar and proposed.patch. Every source finding keeps the professional term and adds plain-language meaning, consequence, evidence limits, a reviewable proposal, side effects, separate security and functional retests, rollback criteria and user decisions. A direct project audit is allowed for one-off review but has ephemeral identity and cannot be a retest baseline. fixed requires the same persisted subject and scope, a compatible rule, completed current coverage and affirmative absence of the condition. The patch is never applied by this command. None of these commands grants permission to probe a deployment.

Reports summarize by risk domain, then evidence state, then severity. The default CI policy gates confirmed HIGH security_exposure and supply_chain findings only. Existing --fail-on behavior continues to set those two domains; opt into another domain explicitly, for example:

webapp-security crawl --site https://example.com --out ./security-report \
  --fail-on high --fail-on-domain search_discoverability=high

Multiple --fail-on-domain <domain=threshold> options may be combined. Effective thresholds are recorded in the report. The generated rule taxonomy separates source rule kind, family, language, domain, severity, default evidence state and standards. Exact stable source counts and complete explanation metadata come from the machine-readable stable-source-rules.json: 20 built-in risk rules, 2 built-in evidence-integrity rules and 8 external adapter risk rules on main, for 30 stable source and deployment-policy rules. Eight JavaScript/TypeScript and eight Python rules are bounded lexical leads for execution, unsafe browser or framework configuration, transport, authentication secrets and deserialization. Their exact detection and false-positive boundaries are recorded in the JS/TS and Python decisions. They do not prove input flow or runtime reachability and remain suspected until independently reproduced.

Capability boundary

Capabilities use two independent dimensions so support tooling is not counted as vulnerability coverage:

• Category: Detection; Evidence and reporting; Lifecycle and distribution; or Agent-guided methodology.
• Maturity: stable, experimental, agent_guided, or planned.

The current stable Detection families are the narrow built-in source audit, opt-in Checkov, Gitleaks, Opengrep and OSV-Scanner adapters, crawl-boundary audit, crawler identity verification, edge verification, and the read-only AWS inventory helper. Project discovery, the demo, report renderers, retest infrastructure, installer, and GitHub Action are tested product capabilities, but are not additional detector families. API authorization, business logic, LLM/OAuth, data-layer and broader AWS reviews remain Agent-guided methodology until a named adapter earns regression evidence.

The generated capability matrix links every category and maturity statement to evidence. Results are confirmed, suspected, unknown, or not_applicable; a check that could not run is never a pass. Installing the Skill does not prove a project secure.

Current detector and workflow constraints are listed in KNOWN_LIMITATIONS.md. The MCP and stable-rule expansion decision is a future gate, not shipped behavior.

Deterministic tools

Ask Claude Code or Codex to use web-app-security, or run the same deterministic tools directly:

# Network-free project discovery and versioned scope
webapp-security start .

# Source-only audit, explain and required-baseline retest
webapp-security audit .webapp-security/runs/<run-id> --fail-on high
webapp-security audit . --since HEAD~1 --fail-on never
webapp-security audit . --staged --fail-on never
webapp-security doctor . --adapter all
webapp-security audit . --adapter checkov --adapter gitleaks --adapter opengrep --adapter osv --fail-on never
webapp-security explain <finding-id> --report <report.json>
webapp-security start . --run-id <retest-run-id>
webapp-security retest .webapp-security/runs/<retest-run-id> \
  --baseline <report.json> --fail-on high

# Historical v1 reports stay non-comparable; moved/cloned projects require explicit binding
webapp-security migrate-report <v1-report.json> --scope <security-scope.yml> \
  --acknowledge-subject <subject-id> --out <new-directory>
webapp-security rebind <moved-project> --scope <security-scope.yml> \
  --acknowledge-subject <subject-id>

# Passive crawl-boundary and crawler accessibility audit
webapp-security crawl --site https://example.com --out ./security-report

# Active sensitive-path probes require both ownership/written authorization and an explicit gate
webapp-security crawl --site https://example.com --out ./security-report \
  --active-probe --acknowledge-authorization

# Crawler identity: exact product ranges or FCrDNS, never a user-agent string alone
webapp-security verify-crawler --ip 66.249.66.1 --ua Googlebot --ranges

# Passive headers, redirect, certificate and TLS policy verification
webapp-security verify-edge --site https://example.com

# Read-only AWS posture inventory
webapp-security aws --profile default --region us-east-1 --out ./security-report

Active rate-limit verification also requires --acknowledge-authorization. Network or evidence failure is unknown and exits non-zero; it is never rendered as safe.

Source conclusions use finding/report v3, including the before/after source reports inside the new demo. Crawl, crawler identity, edge and AWS remain on v2; the demo's small demo-result.json fact schema is separate from either report schema. Both report versions preserve the same coverage, evidence-state, policy and exit-code semantics. Report bundles and their tool-specific observations are sanitized in memory, staged as private files in the target directory, and committed together without overwriting prior evidence. A renderer or handled write failure is rolled back without leaving a partial new bundle. Historical v1 reports remain readable only for display, release verification and explicit non-comparable migration; they are never accepted as a comparable baseline. Compatible persisted v2 source baselines remain readable and are upgraded in memory for v3 comparison without rewriting their bytes.

GitHub Action

The composite Action keeps the v0.3 crawl inputs and outputs. Crawl mode is passive by default and requires deployment authorization acknowledgement:

- name: Audit public crawl boundary
  uses: parousia8888/web-app-security-skill@621e0bc2ad044f9390fa9d567bf4b9fca138a959
  with:
    site: https://example.com
    acknowledge-authorization: true
    active-probe: false
    fail-on: high

For repeatable CI, use the immutable v0.5.3 commit above. The signed stable major-version alias now resolves to the same v0.5.3 source after its public passive and authorization consumer passed:

uses: parousia8888/web-app-security-skill@v1

Source mode defaults to the bundled adapter. The immutable v0.5.3 Action runs the v3 source contract, the stable v0.5.0 rule corpus, the v0.5.1/v0.5.2 correctness fixes and the v0.5.3 distribution, diff-scope and benchmark surfaces. External binaries must be installed and pinned by the caller; the Action never downloads them:

- name: Audit source
  uses: parousia8888/web-app-security-skill@621e0bc2ad044f9390fa9d567bf4b9fca138a959
  with:
    mode: source
    project: .
    adapters: builtin
    fail-on: high

The moving v1 tag is promoted with a guarded lease only after the versioned source and installation gates pass, then the public consumer must pass before promotion is recorded complete. Review release notes before accepting a future update; use the full commit above when the workflow must not move.

Trust and release evidence

• CI runs Ubuntu/macOS x Node 22/24, deterministic HTTP/HTTPS fixtures and Bash 3.2 smoke tests.
• Third-party Actions in release and CodeQL workflows are pinned to full commit SHAs.
• Tagged releases require matching VERSION, changelog and a versioned evidence note. The tag is signed and the release records its source commit.
• Release assets contain a reproducible source archive, SPDX 2.3 SBOM, SHA256SUMS and GitHub build-provenance attestation. CI builds the archive twice, compares every byte, then runs the lifecycle from the extracted archive in an isolated home with network access denied.
• SECURITY.md, threat model, false-positive policy and compatibility matrix make the trust boundary reviewable.

Verify downloaded release assets:

sha256sum -c SHA256SUMS
gh attestation verify web-app-security-skill-*.tar.gz \
  --repo parousia8888/web-app-security-skill
git -c gpg.ssh.allowedSignersFile=.github/release-signers verify-tag v0.5.3

5 ordinary project journeys

The original v0.4.0 journeys preserve the complete v2 built-in/Gitleaks/OSV evidence. The separate v0.5.0 built-in review reruns the same fixed commits through the broader v3 JavaScript/TypeScript and Python rules and manually classifies every finding. No hosted instance or project dependency was executed in either pass.

Read the structured v0.5.0 classification and the historical journey method. Confirmed source facts, scanner leads and false-positive outcomes are kept visible; this is not a precision score. Uptime Kuma and Mealie overlap with the methodology corpus below at the same commits, so these are two evidence views rather than ten distinct projects.

The 5 earlier source methodology studies remain as a separate corpus: three intentionally vulnerable benchmarks and two production projects.

Read the method and corpus limits. These are evidence for the methodology, not a fabricated precision score for a CLI that is not yet a general SAST engine.

Program map

Cross-cutting references cover crawl boundaries, verified crawler identity, source-map/dotfile exposure, enforcement placement, AWS hardening, overlooked surfaces, regression gates and safe deployment. Start from SKILL.md.

Contributing

The roadmap separates correctness work from adoption work. New contributors can start from bounded good-first issues, the issue forms, and CONTRIBUTING.md. False-positive reports need a sanitized minimal fixture and expected classification; sensitive details go through private vulnerability reporting.

The generated launch evidence collects only reproducible capability, demo, project-journey, methodology-study and release facts. The publication kit provides evidence-linked drafts and a reusable public/private case-study workflow without claiming that external publication has occurred.

MIT licensed.