security

Security Scan Patterns for Claude Code Plugins

Context-Aware File Classification

Before assigning severity to any finding, classify the file by its execution context:

Documentation Files (*.md)

Patterns in .md files are instructional content, not executable code. A curl | bash in a README documents a user action the reader types manually — the plugin never runs it. Apply this rule universally:

Any Critical or High pattern found in a .md file → downgrade to Low (informational). Note it as "instructional content in documentation — not executable."

Examples:

• curl https://... | bash in README.md → Low: install instruction for end users
• eval $var in SKILL.md → Low: pattern shown as example to avoid
• new Function(...) in CLAUDE.md → Low: educational reference

Exception: if a .md file is explicitly referenced as a script via command: in hooks.json or executed via bash file.md, treat it as executable and apply full severity.

Scanning Workflow

1. Classify files — categorize each file by execution context (see table above)
2. Identify execution surfaces — map hooks, scripts, MCP configs, commands, and install scripts
3. Scan each surface — apply pattern tables below, matching regex against file contents
4. Apply context adjustments — downgrade documentation findings to Low per the markdown rule
5. Validate findings — verify each Critical/High finding is in an executable context before finalizing
6. Generate report — produce the structured report (see Report Format section)

Execution Surfaces

Claude Code plugins have five execution surfaces that must be scanned:

Dangerous Shell Patterns

Critical (immediate risk)

High (likely dangerous)

Medium (context-dependent)

MCP Configuration Risks

Scan .mcp.json for:

Known-safe MCP domains: localhost, 127.0.0.1, modelcontextprotocol.io, github.com, api.anthropic.com

Hook Safety Rules

Scan hooks/hooks.json for:

Dependency Supply Chain

Scan package.json for:

Scan requirements.txt / pyproject.toml for:

Prompt Injection Surfaces

Severity Definitions

Pre-Match Context Filter (apply BEFORE flagging)

Before generating ANY Critical or High finding from the pattern tables above, verify the matched pattern is in executable position — not quoted text being displayed, documented, echoed, or used as test data. This filter applies universally to every Critical/High pattern in this skill, not just curl | bash. The audit data has shown the same class of false positives across SEC-curl-pipe-sh, SEC-new-function-eval, SEC-eval-with-variables, and SEC-base64-decode-and-exec — pattern syntactically present in the file, but in a string context where the shell or interpreter never parses it as code.

Drop the finding silently if any of these apply:

A pattern is in executable position only when the shell or interpreter would actually parse it as a command — not when it is a string the program displays, returns, stores, or transmits. Apply this filter BEFORE confidence assignment, not after; once a Critical/High finding is emitted, the contribute path may ship it.

Per-pattern guidance

SEC-curl-pipe-sh / download-then-execute:

• Match curl ... | (bash|sh) only when the curl invocation is at the start of a pipeline whose right-hand side is a shell, NOT when the pattern text appears as a quoted argument to another command.
• A chmod +x file && ./file immediately after a curl -o file ... IS executable; flag it. A chmod +x shown inside a usage heredoc is NOT; drop it.

SEC-new-function-eval / SEC-eval-with-variables:

• Match eval(...), new Function(...), exec(...) only when the call is in executable position. Verify by reading the surrounding 5 lines: if the match is the value of an object property, the body of a string literal, or fixture/test data being passed to a remote system, drop it.
• A python3 -c "..." block where the -c argument interpolates variables IS executable when the script runs locally; flag it.
• A string constant jsCode: 'const result = eval(item.json.code);' defined in test data destined for an external workflow runtime is NOT executable in the audited repo; drop it.

SEC-base64-decode-and-exec:

• Match base64 -d | sh, base64.decode(...) | exec only when the decoded output is fed to a local shell or interpreter. If the base64 is a transport encoding for code sent to a remote sandbox/container (e.g., printf X | base64 -d where X is constructed locally and shipped via stdin to an E2B sandbox), the local audit has no exposure — drop it.

If a pattern is in executable position but is intentional and trusted (e.g., a CI release script that pipes a known maintainer-controlled URL to bash, or python3 -c interpolating values from mktemp/stat/internal tools that cannot contain injection characters), mark it false_positive: true with an fp_reason explaining the trust path. The reproduction gate at the contribute step will drop it; the rule still gets the self-learning signal.

Public-by-Design Identifiers (drop SEC-hardcoded-api-key matches)

Many "API keys" embedded in client-side code are PUBLIC BY DESIGN — they identify a project to a third-party SDK but carry no privileged access. Flagging them as hardcoded secrets is a category error: the maintainer cannot remove the value without breaking the integration, and the value is already visible to any browser that visits the site.

Drop SEC-hardcoded-api-key findings silently when ALL of these apply:

Known-public-by-design key patterns:

Public DSN/CSP-safe identifiers in meta tags, <script src> URLs, or ESM imports are also public by design.

What still IS a finding (never drop):

• Stripe secret keys (sk_live_, sk_test_)
• AWS access keys (AKIA..., ASIA...)
• GitHub PATs (ghp_, gho_, ghu_, ghs_, ghr_)
• OpenAI keys (sk-..., sk-proj-...)
• Anthropic keys (sk-ant-...)
• Database connection URLs with embedded credentials
• Private keys (-----BEGIN ...PRIVATE KEY-----)
• Twilio Auth Tokens, SendGrid API keys, etc. — server-side credentials
• Any key matched in a server-side path (api/, server/, backend/, routes/, lib/server/, files NOT under public output dirs)

The discipline: ask "if this key were swapped tomorrow, would the end-user-visible product break?" If yes (analytics, tag managers, SDK identifiers), it's public-by-design — drop. If no (auth, write operations, admin endpoints), it's a real secret — flag.

Finding source: 2026-05-05 audit of wasp-lang/open-saas flagged 3 PostHog/Reo public keys in opensaas-sh/blog/public/scripts/. All 3 were self-marked false_positive: true by the scorer. Adding this filter prevents the audit cycle from being burned on the same false positive shape.

Finding Validation

After the pre-match filter, verify each surviving Critical or High result:

• Confirm the file is in an executable context (not documentation)
• Verify the pattern is reachable at runtime (not dead code behind a feature flag)
• Cross-reference with the project's test suite — a pattern in test fixtures is lower risk

Report Format

The security scan section in an audit report follows this structure:

## Security Scan

| Severity | Count |
|----------|-------|
| Critical | N |
| High | N |
| Medium | N |
| Low | N |

### Findings

| # | Severity | File | Line | Pattern | Description |
|---|----------|------|------|---------|-------------|

Risk Gate

If any Critical or High findings exist, the contribute-approved label must NOT be applied. The audit report must include a prominent warning and the tracking issue must link to the security findings.

Scope Note

This skill covers the security-pattern catalog and risk-gate logic used by the security-scanner agent. For the schemas of executable artifacts the scanner inspects (hooks, scripts, MCP configs), see nlpm:conventions. For the broader anti-pattern catalog covering NL-quality findings that are not security risks, see nlpm:patterns.