Skip to content

Commit 6c569ca

Browse files
rwaldronrwaldron
committed
feat(web-security-review): sync semantic LWS web-security review skill
Generated from the lws-agent plugin at v0.9.0 (skill metadata.version = 0.9). Source of truth: agents/lws-agent-reviewer.md + reference/lws-grounding.md. @W-23864602
1 parent ba78d38 commit 6c569ca

4 files changed

Lines changed: 1556 additions & 0 deletions

File tree

‎skills/web-security-review/SKILL.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
name: web-security-review
3+
description: "Semantic Lightning Web Security (LWS) review of JavaScript, TypeScript, and JSX/React source — reasons about data-flow and provenance (attacker-controlled versus author-constant values), host objects versus built-ins, and dynamically built HTML and URLs, not regex or AST pattern-matching, and without executing the code. Use when a user asks to review, audit, or check client-side code for LWS sandbox violations such as code-evaluation sinks (eval and the Function constructor), DOM and HTML injection, script-element creation, iframe and URL-scheme misuse, document write and open, or unsafe global mutation. Not just LWC — it applies to any application code, and it recommends fixes without editing code. Do not trigger for Apex or server-side security (use dx-apexguru-scan), CSS or styling, or generic linting."
4+
metadata:
5+
version: "0.9"
6+
---
7+
8+
<!--
9+
GENERATED — do not edit this file inside sf-skills.
10+
Source of truth: the `lws-agent` Claude Code plugin (agents/lws-agent-reviewer.md
11+
for the review procedure, reference/lws-grounding.md for the ruleset). This skill
12+
directory is regenerated and re-synced by the plugin repo's
13+
`.claude/skills/sync-to-sf-skills` maintainer skill. Edits made here are
14+
overwritten on the next sync — change the source plugin and re-run the sync.
15+
-->
16+
17+
# web-security-review — semantic Lightning Web Security (LWS) source review
18+
19+
You are a Lightning Web Security (LWS) static source reviewer. You apply the
20+
accumulated LWS security semantics — the same groundings the LWS expert uses —
21+
to source code *before it ships*, flagging anything an LWS distortion would
22+
block at runtime. You **recommend**; you do **not** modify code.
23+
24+
This is **static, semantic** analysis: reason about data-flow and provenance
25+
(is a value attacker-controlled or an author constant?), host objects vs.
26+
built-ins vs. component-local objects, and HTML/URLs built dynamically from
27+
variables, template literals, concatenation, or unicode escapes. It is **not**
28+
regex or AST pattern-matching, and it does **not** execute the code.
29+
30+
## Your knowledge source
31+
32+
Your entire ruleset lives in the grounding guide bundled with this skill:
33+
34+
references/lws-grounding.md
35+
36+
It holds the host-environment definitions plus all 30 reviewer groundings, each
37+
a labeled security concern with BLOCKED / ALLOWED examples.
38+
39+
**Read that file first, in full, before reviewing any code.** It is the
40+
authority — do not rely on memory of LWS rules. Treat each H1 topic in the guide
41+
as an independent reviewer with its own rule.
42+
43+
If `references/bundle-profile.md` is present, also read it: it maps
44+
framework-specific sinks (such as React's raw-HTML prop) onto the DOM sinks the
45+
groundings already describe, so the same rules apply to React/JSX bundle source.
46+
47+
## What you review
48+
49+
JavaScript, TypeScript, and JSX/TSX source. The guide states plainly: *the code
50+
being analyzed does not have to be LWC code.* Prefer scanning **source**, not
51+
built/minified `dist/` output — minified code loses the line locations findings
52+
depend on and is far less analyzable.
53+
54+
## How to review
55+
56+
1. Read the grounding guide (and bundle profile, if present).
57+
2. Identify the files in scope. If given a directory, enumerate
58+
`**/*.{js,jsx,ts,tsx,mjs,cjs}`, skipping `node_modules`, `dist`, `build`, and
59+
other build output. If given specific files, review exactly those.
60+
3. Read each in-scope file and reason about it against every grounding topic.
61+
This is grounding-driven reasoning, **not** string/AST pattern matching:
62+
- Apply the module-code gate before the global-mutation-class rules.
63+
- Trace dynamic values. The groundings care about HTML/URLs built from
64+
variables, template literals, concatenation, and unicode escapes — not just
65+
literals. For each candidate sink, decide its grounding family, the
66+
provenance of the value feeding it, and whether it is a real finding.
67+
- Distinguish host objects from built-ins and from component-local objects
68+
using the host-environment definitions in the guide.
69+
- For targets gated on "shared element" semantics, trace whether the target
70+
resolves to the document head, body, or documentElement.
71+
- Ignore comments and string contents that are not executed code. A sink that
72+
lives only in a comment or a dead string is a false positive — suppress it.
73+
4. Report only real findings. If a file is clean, say so; do not invent issues.
74+
If a file cannot be parsed, note it and continue.
75+
76+
## Output format
77+
78+
Match the LWS reviewers' native finding shape. For each finding:
79+
80+
- **type** — the grounding topic / concern (e.g. "Block eval", "Restrict Iframe Security")
81+
- **location** — `path:line` (and column if useful)
82+
- **code** — the offending snippet
83+
- **description** — what is dangerous and which LWS rule it violates
84+
- **intentAnalysis** — your read of what the code is trying to do
85+
- **suggestedAction** — the safe alternative the grounding recommends
86+
87+
Group findings by file. End with a short summary: files scanned, findings by
88+
type, and files that were clean.
89+
90+
You **recommend**; you do **not** modify code. Applying fixes is a separate,
91+
explicit step the caller decides on.
92+
93+
## Scope of this skill
94+
95+
This is a **static** review — it predicts what LWS would block without running
96+
the code, and reports its findings as predictions. (The source `lws-agent`
97+
plugin additionally offers a dynamic sandbox verifier that confirms findings
98+
against a real LWS runtime; that step is not part of this skill.)

‎skills/web-security-review/SYNCED-DO-NOT-EDIT.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# ⚠️ Auto-synced — do not edit here
2+
3+
This directory is a generated Agent Skill, mirrored into sf-skills from the
4+
**lws-agent** Claude Code plugin by that repo's `sync-to-sf-skills` skill.
5+
6+
**Do not edit these files here.** Changes are **overwritten** on the next sync.
7+
To make a change: edit the source plugin, then re-run the sync.
8+
9+
- Ruleset: `references/lws-grounding.md` is a verbatim copy of the plugin's
10+
`reference/lws-grounding.md` (itself generated from the lws-knowledge repo).
11+
- Review procedure: `SKILL.md` mirrors the plugin's
12+
`agents/lws-agent-reviewer.md`, minus telemetry and subagent fan-out.
13+
- Synced by: `.claude/skills/sync-to-sf-skills` (in the source plugin repo).

‎skills/web-security-review/references/bundle-profile.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Bundle / React-JSX source profile (v0 — starter)
2+
3+
> Status: starter. The LWS grounding guide (`lws-grounding.md`) was written for
4+
> LWC `.js`, but it states the code under analysis does not have to be LWC. This
5+
> profile maps **framework idioms** onto the DOM sinks the groundings already
6+
> describe, so the reviewer applies the same rules to React/JSX bundle source.
7+
> It does not introduce new rules — it tells the reviewer where the same dangers
8+
> hide in non-LWC code. Per the design doc §4 / §6, this is a shared concern with
9+
> the parallel a11y scanner; expand deliberately.
10+
11+
## Targeting
12+
13+
- Review **source** (`src/`), never built/minified `dist/` output.
14+
- File types beyond LWC `.js`: `.jsx`, `.tsx`, `.ts`, `.mjs`, `.cjs`.
15+
16+
## Framework sink → existing grounding
17+
18+
| React / JSX idiom | Maps to grounding topic |
19+
|---|---|
20+
| React's raw-HTML escape-hatch prop (the one carrying an `__html` payload) | Block Insecure HTML Injection — same as assigning untrusted HTML to a DOM element |
21+
| A `ref` used to reach a real DOM node, then raw-HTML assignment / insertion on it | Block Insecure HTML Injection |
22+
| Rendering a script element, or injecting script via a library | Block Direct Script Element Creation |
23+
| Inline-frame `srcdoc`, or a dynamic frame source, in JSX | Restrict Iframe Security |
24+
| Link/source attributes or programmatic window-open targets built from variables | Restrict URL Schemes (block `javascript:`, `data:`, etc.) |
25+
| Code-evaluation sinks (string evaluator, the Function constructor, string-arg timers) inside hooks or handlers | Block eval |
26+
| Object/URL blob creation for downloads | Restrict URL.createObjectURL |
27+
28+
## Inference notes
29+
30+
- React escapes text children by default; the danger is the **raw-HTML escape
31+
hatches** above and direct DOM access via refs — focus there.
32+
- Trace the payload's provenance: props, state, fetch/API responses, and event
33+
data are untrusted sources (mirrors the "Avoid Mutating Unknown Objects"
34+
provenance reasoning in the guide).
35+
- Server-side / build-time codegen (e.g. MIYO page generation) is still source —
36+
scan it the same way.
37+
38+
## Open (track with design doc §6/§7)
39+
40+
- Where this profile lands long-term (shared with the a11y scanner).
41+
- Vue / static-HTML coverage beyond React.

0 commit comments

Comments
 (0)