security-patterns

---

name: security-patterns license: MIT compatibility: "Claude Code 2.1.183+." description: Security patterns for authentication, defense-in-depth, input validation, OWASP Top 10, LLM safety, and PII masking. Use when implementing auth flows, security layers, input sanitization, vulnerability prevention, prompt injection defense, or data redaction. tags: [security, authentication, authorization, defense-in-depth, owasp, input-validation, llm-safety, pii-masking, jwt, oauth] context: fork agent: security-auditor version: 2.0.0 author: OrchestKit user-invocable: false disable-model-invocation: false complexity: high persuasion-type: discipline effort: high model: opus hooks: PreToolUse: - matcher: "Bash" command: "${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs pretool/bash/dangerous-command-blocker" metadata: category: document-asset-creation allowed-tools:

• Read
• Glob
• Grep
• WebFetch
• WebSearch paths: ["src//auth/", "src//middleware/", "/security"] path_patterns: ["/auth/", "/middleware/", "/security/**", ".env*"]

---

Security Patterns

Comprehensive security patterns for building hardened applications. Each category has individual rule files in rules/ loaded on-demand.

Quick Reference

Category	Rules	Impact	When to Use
Authentication	3	CRITICAL	JWT tokens, OAuth 2.1/PKCE, RBAC/permissions
Defense-in-Depth	2	CRITICAL	Multi-layer security, zero-trust architecture
Input Validation	3	HIGH	Schema validation (Zod/Pydantic), output encoding, file uploads
OWASP Top 10	2	CRITICAL	Injection prevention, broken authentication fixes
LLM Safety	3	HIGH	Prompt injection defense, output guardrails, content filtering
PII Masking	2	HIGH	PII detection/redaction with Presidio, Langfuse, LLM Guard
Scanning	3	HIGH	Dependency audit, SAST (Semgrep/Bandit), secret detection
Advanced Guardrails	2	CRITICAL	NeMo/Guardrails AI validators, red-teaming, OWASP LLM

Total: 20 rules across 8 categories

Quick Start

# Argon2id password hashing
from argon2 import PasswordHasher
ph = PasswordHasher()
password_hash = ph.hash(password)
ph.verify(password_hash, password)

# JWT access token (15-min expiry)
import jwt
from datetime import datetime, timedelta, timezone
payload = {
    'sub': user_id, 'type': 'access',
    'exp': datetime.now(timezone.utc) + timedelta(minutes=15),
}
token = jwt.encode(payload, SECRET_KEY, algorithm='HS256')

// Zod v4 schema validation
import { z } from 'zod';
const UserSchema = z.object({
  email: z.email(),
  name: z.string().min(2).max(100),
  role: z.enum(['user', 'admin']).default('user'),
});
const result = UserSchema.safeParse(req.body);

# PII masking with Langfuse
import re
from langfuse import Langfuse

def mask_pii(data, **kwargs):
    if isinstance(data, str):
        data = re.sub(r'\b[\w.-]+@[\w.-]+\.\w+\b', '[REDACTED_EMAIL]', data)
        data = re.sub(r'\b\d{3}-\d{2}-\d{4}\b', '[REDACTED_SSN]', data)
    return data

langfuse = Langfuse(mask=mask_pii)

Authentication

Secure authentication with OAuth 2.1, Passkeys/WebAuthn, JWT tokens, and role-based access control.

Rule	Description
auth-jwt.md	JWT creation, verification, expiry, refresh token rotation
auth-oauth.md	OAuth 2.1 with PKCE, DPoP, Passkeys/WebAuthn
auth-rbac.md	Role-based access control, permission decorators, MFA

Key Decisions: Argon2id > bcrypt | Access tokens 15 min | PKCE required | Passkeys > TOTP > SMS

Defense-in-Depth

Multi-layer security architecture with no single point of failure.

Rule	Description
defense-layers.md	8-layer security architecture (edge to observability)
defense-zero-trust.md	Immutable request context, tenant isolation, audit logging

Key Decisions: Immutable dataclass context | Query-level tenant filtering | No IDs in LLM prompts

sandbox.network.deniedDomains (CC 2.1.113+)

Network-layer blocklist enforced before Bash/WebFetch egress — pair with the hook-layer DENY_PATTERNS for defense in depth. Settings example:

"sandbox": {
  "network": {
    "deniedDomains": ["*.evil.com", "pastebin.com", "transfer.sh"]
  }
}

Wildcards supported (*.example.com, evil.com/*/malicious/*). Plugins ship a baseline list in src/settings/ork.settings.json; project settings can extend it. Use for: prompt-injection exfil sinks, known-bad registries, paste services that bypass audit.

sandbox.credentials (CC 2.1.187+)

Blocks sandboxed Bash from reading credential files and secret env vars — defense-in-depth beside sandbox.filesystem.denyRead. Deny-only and merged across scopes (any scope can add, none can remove); older CC ignores the key. Settings example:

"sandbox": {
  "credentials": {
    "files": [{ "path": "~/.aws/credentials", "mode": "deny" }],
    "envVars": [{ "name": "GITHUB_TOKEN", "mode": "deny" }]
  }
}

Plugins ship a baseline in src/settings/ork.settings.json (denies ~/.aws/credentials, ~/.ssh, ~/.gnupg, ~/.netrc, ~/.npmrc plus the token env vars that can hijack git-push auth). Pair with CLAUDE_CODE_SUBPROCESS_ENV_SCRUB to scrub all subprocess credentials regardless of sandboxing.

Input Validation

Validate and sanitize all untrusted input using Zod v4 and Pydantic.

Rule	Description
validation-input.md	Schema validation with Zod v4 and Pydantic, type coercion
validation-output.md	HTML sanitization, output encoding, XSS prevention
validation-schemas.md	Discriminated unions, file upload validation, URL allowlists

Key Decisions: Allowlist over blocklist | Server-side always | Validate magic bytes not extensions

OWASP Top 10

Protection against the most critical web application security risks.

Rule	Description
owasp-injection.md	SQL/command injection, parameterized queries, SSRF prevention
owasp-broken-auth.md	JWT algorithm confusion, CSRF protection, timing attacks

Key Decisions: Parameterized queries only | Hardcode JWT algorithm | SameSite=Strict cookies

LLM Safety

Security patterns for LLM integrations including context separation and output validation.

Rule	Description
llm-prompt-injection.md	Context separation, prompt auditing, forbidden patterns
llm-guardrails.md	Output validation pipeline: schema, grounding, safety, size
llm-content-filtering.md	Pre-LLM filtering, post-LLM attribution, three-phase pattern

Key Decisions: IDs flow around LLM, never through | Attribution is deterministic | Audit every prompt

Context Separation (CRITICAL)

Sensitive IDs and data flow AROUND the LLM, never through it. The LLM sees only content — mapping back to entities happens deterministically after.

# CORRECT: IDs bypass the LLM
context = {"user_id": user_id, "tenant_id": tenant_id}  # kept server-side
llm_input = f"Summarize this document:\n{doc_text}"       # no IDs in prompt
llm_output = call_llm(llm_input)
result = {"summary": llm_output, **context}               # IDs reattached after

Output Validation Pipeline

Every LLM response MUST pass a 4-stage guardrail pipeline before reaching the user:

def validate_llm_output(raw_output: str, schema, sources: list[str]) -> str:
    # 1. Schema — does it match expected structure?
    parsed = schema.parse(raw_output)
    # 2. Grounding — are claims supported by source documents?
    assert_grounded(parsed, sources)
    # 3. Safety — toxicity, PII leakage, prompt leakage
    assert_safe(parsed, max_toxicity=0.5)
    # 4. Size — prevent token-bomb responses
    assert len(parsed.text) < MAX_OUTPUT_CHARS
    return parsed.text

PII Masking

PII detection and masking for LLM observability pipelines and logging.

Rule	Description
pii-detection.md	Microsoft Presidio, regex patterns, LLM Guard Anonymize
pii-redaction.md	Langfuse mask callback, structlog/loguru processors, Vault deanonymization

Key Decisions: Presidio for enterprise | Replace with type tokens | Use mask callback at init

Scanning

Automated security scanning for dependencies, code, and secrets.

Rule	Description
scanning-dependency.md	npm audit, pip-audit, Trivy container scanning, CI gating
scanning-sast.md	Semgrep and Bandit static analysis, custom rules, pre-commit
scanning-secrets.md	Gitleaks, TruffleHog, detect-secrets with baseline management

Key Decisions: Pre-commit hooks for shift-left | Block on critical/high | Gitleaks + detect-secrets baseline

Advanced Guardrails

Production LLM safety with NeMo Guardrails, Guardrails AI validators, and DeepTeam red-teaming.

Rule	Description
guardrails-nemo.md	NeMo Guardrails, Colang 2.0 flows, Guardrails AI validators, layered validation
guardrails-llm-validation.md	DeepTeam red-teaming (40+ vulnerabilities), OWASP LLM Top 10 compliance

Key Decisions: NeMo for flows, Guardrails AI for validators | Toxicity 0.5 threshold | Red-team pre-release + quarterly

Managed Hook Hierarchy (CC 2.1.49)

Plugin settings follow a 3-tier precedence:

Tier	Source	Overridable?
1. Managed (plugin settings.json)	Plugin author ships defaults	Yes, by user
2. Project (.claude/settings.json)	Repository config	Yes, by user
3. User (~/.claude/settings.json)	Personal preferences	Final authority

Security hooks shipped by OrchestKit are managed defaults — users can disable them but are warned. Enterprise admins can lock settings via managed profiles.

CC 2.1.166 — managed-settings enforcement fix: before 2.1.166 a single invalid entry in managed settings silently disabled enforcement of all remaining valid policies — one typo could void your entire security lockdown. Require 2.1.166+ when relying on managed profiles, and validate the file before deploying it. The same release fixed allowedMcpServers/deniedMcpServers predicates not matching when they use ${VAR} references.

CC 2.1.160 — write prompts: Claude Code now prompts before writing shell startup files (.zshenv, .zlogin, .bash_login, ~/.config/git/) and — under acceptEdits — build-tool configs that grant code execution (.npmrc, .yarnrc*, bunfig.toml, .bazelrc, .pre-commit-config.yaml, .devcontainer/). Treat these as defense-in-depth defaults: approve deliberately rather than blanket-allowing.

Permission-rule semantics (≥ 2.1.166): allow/ask/deny rules gained security-relevant behavior — Read deny now hides files from Glob/Grep, deny tool-names accept globs ("*" = default-deny), explicit WebFetch(domain:…) overrides the preapproved-host auto-allow, relayed SendMessage from other sessions carries no authority, and org-managed rules apply for the whole session. See references/cc-permission-model.md for the full model + a recommended baseline settings.json.

Anti-Patterns (FORBIDDEN)

# Authentication
user.password = request.form['password']       # Plaintext password storage
response_type=token                             # Implicit OAuth grant (deprecated)
return "Email not found"                        # Information disclosure

# Input Validation
"SELECT * FROM users WHERE name = '" + name + "'"  # SQL injection
if (file.type === 'image/png') {...}               # Trusting Content-Type header

# LLM Safety
prompt = f"Analyze for user {user_id}"             # ID in prompt
artifact.user_id = llm_output["user_id"]           # Trusting LLM-generated IDs

# PII
logger.info(f"User email: {user.email}")           # Raw PII in logs
langfuse.trace(input=raw_prompt)                   # Unmasked observability data

Detailed Documentation

Load on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>"):

File	Content
cc-permission-model.md	CC allow/ask/deny rule semantics (≥2.1.166): Read-deny hides from Glob/Grep, deny-globs, WebFetch precedence, cross-session auth, org-managed rules
oauth-2.1-passkeys.md	OAuth 2.1, PKCE, DPoP, Passkeys/WebAuthn
request-context-pattern.md	Immutable request context for identity flow
tenant-isolation.md	Tenant-scoped repository, vector/full-text search
audit-logging.md	Sanitized structured logging, compliance
zod-v4-api.md	Zod v4 types, coercion, transforms, refinements
vulnerability-demos.md	OWASP vulnerable vs secure code examples
context-separation.md	LLM context separation architecture
output-guardrails.md	Output validation pipeline implementation
pre-llm-filtering.md	Tenant-scoped retrieval, content extraction
post-llm-attribution.md	Deterministic attribution pattern
prompt-audit.md	Prompt audit patterns, safe prompt builder
presidio-integration.md	Microsoft Presidio setup, custom recognizers
langfuse-mask-callback.md	Langfuse SDK mask implementation
llm-guard-sanitization.md	LLM Guard Anonymize/Deanonymize with Vault
logging-redaction.md	structlog/loguru pre-logging redaction

Related Skills

• api-design-framework - API security patterns
• ork:rag-retrieval - RAG pipeline patterns requiring tenant-scoped retrieval
• llm-evaluation - Output quality assessment including hallucination detection

Capability Details

authentication

Keywords: password, hashing, JWT, token, OAuth, PKCE, passkey, WebAuthn, RBAC, session Solves:

• Implement secure authentication with modern standards
• JWT token management with proper expiry
• OAuth 2.1 with PKCE flow
• Passkeys/WebAuthn registration and login
• Role-based access control

defense-in-depth

Keywords: defense in depth, security layers, multi-layer, request context, tenant isolation Solves:

• How to secure AI applications end-to-end
• Implement 8-layer security architecture
• Create immutable request context
• Ensure tenant isolation at query level

cc-subprocess-hardening (CC 2.1.98)

Keywords: subprocess, sandbox, PID namespace, env scrub, script caps Solves:

• Limit runaway hook scripts: CLAUDE_CODE_SCRIPT_CAPS=100
• Strip credentials from subprocesses: CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1
• PID namespace isolation on Linux for subprocess sandboxing
• Prevent Bash permission bypasses via backslash escapes and compound commands

CC 2.1.128 — SDK host "Always allow" persistence: when a user picks "Always allow" from a Bash permission prompt in an SDK host, the grant now persists via .claude/settings.local.json instead of evaporating at session end. Audit your SDK consumers' .gitignore to confirm .claude/settings.local.json is excluded — committing it leaks per-developer Bash auth grants. Project-committed .claude/settings.json is unchanged; only the user-machine-local file receives the new entries.

CC 2.1.169 — managed MCP enforcement + OTEL cert-path trust: two policy-bypass classes closed. Enterprise allowedMcpServers/deniedMcpServers policies were NOT enforced on reconnect, IDE-typed configs, --mcp-config servers in the first post-install session, or before remote settings loaded — treat any pre-2.1.169 managed-MCP audit as incomplete on those paths. And untrusted project settings could set OTEL client-certificate paths without trust confirmation (a cloned repo could point telemetry at an attacker cert); now gated behind trust. Both fixes are active at ork's floor (2.1.183).

CC 2.1.163 — home-path deny rules now cover $HOME Bash refs: before this fix a Read(~/.ssh/**)-style deny rule blocked the Read tool but NOT a Bash command that reached the same file via $HOME/.ssh/... — a silent secrets-read bypass. If you gate home-directory secrets (e.g. ~/.aws/credentials, ~/.ssh/*, ~/.gnupg/*) through permission deny rules, pin your CC floor to >= 2.1.163; older builds (< 2.1.163) leave the Bash path open — ork's floor is now 2.1.183, which already includes this fix.

input-validation

Keywords: schema, validate, Zod, Pydantic, sanitize, HTML, XSS, file upload Solves:

• Validate input against schemas (Zod v4, Pydantic)
• Prevent injection attacks with allowlists
• Sanitize HTML and prevent XSS
• Validate file uploads by magic bytes

owasp-top-10

Keywords: OWASP, sql injection, broken access control, CSRF, XSS, SSRF Solves:

• Fix OWASP Top 10 vulnerabilities
• Prevent SQL and command injection
• Implement CSRF protection
• Fix broken authentication

llm-safety

Keywords: prompt injection, context separation, guardrails, hallucination, LLM output Solves:

• Prevent prompt injection attacks
• Implement context separation (IDs around LLM)
• Validate LLM output with guardrail pipeline
• Deterministic post-LLM attribution

pii-masking

Keywords: PII, masking, Presidio, Langfuse, redact, GDPR, privacy Solves:

• Detect and mask PII in LLM pipelines
• Integrate masking with Langfuse observability
• Implement pre-logging redaction
• GDPR-compliant data handling