security-patterns

Security Patterns

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

Quick Reference

Total: 6 rule files across 4 categories. Topics marked "upstream" or "refs" keep only the ork delta here: floors and key decisions in this file, scars and house decisions in references/ork-delta.md, and first-party sources in Upstream coverage.

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.

Implementation tutorials for JWT, OAuth 2.1/PKCE/DPoP, Passkeys/WebAuthn, RBAC, and MFA are upstream-covered (see Upstream coverage). The ork delta, including the argon2-cffi-over-passlib scar, lives in references/ork-delta.md.

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.

Zero-trust and tenant-isolation implementation recipes (tenant-scoped repositories, RLS, tenant-keyed caches) are upstream-covered; the immutable RequestContext pattern survives in references/request-context-pattern.md and sanitized audit logging in references/audit-logging.md.

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. Merged across scopes (any scope can add, none can remove); older CC ignores the key. mode is deny or, since CC 2.1.221, mask. Settings example:

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

ork ships no sandbox.credentials baseline: CC reads only the permissions key from a plugin's settings file, so the block that used to live in src/settings/ork.settings.json was retired in #3357 as inert. Set it in your user or managed settings (deny ~/.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.

Masking instead of denial. Since CC 2.1.221, a credential file entry can take mode: "mask" on Linux and WSL: the sandboxed command reads a sentinel copy (the whole file, or only the spans an extract regex captures) and the sandbox proxy substitutes the real value on egress. On macOS file masking falls back to deny, so on a Mac it buys nothing over mode: deny. The richer options arrived in CC 2.1.224: beyond mode: deny, credentials can be masked so the command still runs against a redacted value: extract plus onExtractNoMatch pulls a secret out of a structured env value, decode: "jwt" with maskClaims masks named JWT claims, and awsPairs/sigv4 re-signs AWS SigV4 requests after masking. Two constraints decide whether these are usable at all:

• They require sandbox.network.tlsTerminate, so they only apply to traffic CC terminates.
• They are honored only from user settings, managed settings, or --settings. A value shipped by a plugin or set in project .claude/settings.json is ignored, so ork cannot ship these as a baseline the way it ships the deny list. Document them for operators; do not add them to src/settings/ork.settings.json expecting them to take effect.

Never write a deny path with a trailing slash. Through CC 2.1.223, a sandbox.filesystem deny entry ending in / (for example denyRead: "~/.aws/") was silently bypassable on Linux and macOS: the rule parsed, reported clean, and protected nothing. Fixed in 2.1.224, but the shape is still worth avoiding because it reads as protection either way. ork's shipped values (~/.aws/credentials, ~/.ssh/*, ~/.gnupg/*) were never affected.

Input Validation

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

Advanced schema recipes (discriminated unions, file upload validation, URL allowlists) and the full Zod v4 API are upstream-covered; the Zod v4-not-v3 trap list is in references/ork-delta.md, and typed schema examples in scripts/validation-schemas.ts.

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.

Injection prevention (SQL/command/SSRF) and broken-auth fixes (JWT algorithm confusion, CSRF, timing attacks) plus vulnerable-vs-secure demos are upstream-covered; see Upstream coverage.

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

LLM Safety

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

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.

LLM Guard Anonymize/Deanonymize with Vault and structlog/loguru redaction processors are upstream-covered; see Upstream coverage.

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

Scanning

Automated security scanning for dependencies, code, and secrets. Tool tutorials (npm audit, pip-audit, Trivy, Semgrep, Bandit, Gitleaks, TruffleHog, detect-secrets) are upstream-covered; the runnable house pipeline is scripts/scan-vulnerabilities.sh, and the enforced-not-advisory repo gates (pre-push security suite, CI gitleaks) are recorded in references/ork-delta.md.

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.

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

Upstream coverage (do not restate)

These topics were removed from this skill as vendor restatement. Consult the first-party source; only the ork delta (floors, scars, house decisions) lives here, in references/ork-delta.md.

Managed Hook Hierarchy (CC 2.1.49)

Plugin settings follow a 3-tier precedence:

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_PLUGIN_ROOT}/skills/security-patterns/references/<file>"):

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.220).

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.220, 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