dev-security

name: dev-security description: "Authoritative security guidance for backend, frontend touchpoints, agentic AI, and production hardening. Read for auth, validation, secrets, reviews, and pre-deploy verification." license: Complete terms in LICENSE.txt

Dev-Security — Production Security Hardening

Treat security as a build constraint, not a cleanup step. This skill is the authoritative source for authentication, authorization, input validation, secrets, headers, rate limiting, supply-chain checks, PII handling, and agentic AI safety. Validation ownership split: this skill owns what the validation schema enforces (content/policy); placement (boundary-only validation) is owned by dev-architecture §4. dev-backend delegates here for policy and verification depth. dev-frontend remains responsible for UI implementation, but frontend security touchpoints such as CSP compliance, CORS behavior, XSS prevention, and dependency auditing are defined here.

C0/C1 work (small local patches): See dev §0.0 Work Classifier + §0.1 Patch Fast-Path before reading references.

When to Activate

Activate this skill when you are:

• Writing auth, session, cookie, token, password-reset, or OAuth logic.
• Accepting user input from forms, URLs, headers, cookies, webhooks, file uploads, rich text, or AI prompts.
• Handling secrets, credentials, certificates, encryption keys, or third-party API keys.
• Reviewing code for security regressions or production-readiness.
• Auditing dependencies, CI pipelines, or release integrity.
• Designing logging, PII retention, masking, audit trails, or incident response rules.
• Building AI agents, tool-using workflows, or prompt-processing systems.

Use this skill together with the domain skill, not instead of it:

• API architecture and middleware placement: See dev-backend/SKILL.md §4.
• Frontend rendering patterns and anti-slop UI guardrails: See dev-frontend/SKILL.md §§4-5.
• Test strategy and execution flow: See dev-testing.
• Review severity and review flow: See dev-code-reviewer/SKILL.md §§1-2.
• Data pipeline design: See dev-data/SKILL.md §§2-4.

Threat Model First

Answer these three questions before implementation:

1. What are we protecting?
   • Accounts, sessions, payment state, internal admin actions, uploaded files, secrets, PII, audit logs.
2. From whom?
   • Anonymous users, authenticated users, malicious insiders, compromised browsers, compromised CI, poisoned dependencies, hostile prompts.
3. What is the blast radius if this fails?
   • One user, one tenant, one environment, all customers, all secrets, all build artifacts.

Security-sensitive changes must name the trust boundary before coding:

• Browser ↔ API
• Public API ↔ internal service
• App ↔ database
• Agent prompt ↔ tool execution
• CI runner ↔ production artifact

If the change touches auth, payment, file upload, logging, or PII, write the must-pass checks before coding. This skill owns security policy. Domain skills own architecture and implementation details.

Modular References

For current CVEs, advisories, package maintainer/source checks, release integrity claims, or registry trust changes, read the active search skill and follow its query-rewrite, original-source fetch, and evidence-status rules.

Read only the references relevant to the current task. A small CSS change needs no OWASP reference. Auth, data access, secrets, file uploads, webhooks, or incident response changes do.

1. Input Validation

Input validation is the first line of defense. Validate at the first trusted boundary, reject unknown fields, enforce limits, and escape or sanitize on output for the target context. Client-side validation improves UX only — it is never a security boundary.

Required rules

• Validate shape, type, format, enum membership, length, and numeric range.
• Reject unknown fields by default.
• Canonicalize before validation when encoding differences matter.
• Distinguish parsing failures from authorization failures.
• Sanitize HTML only when rich text is explicitly allowed.
• Re-validate on the server even when frontend uses the same schema.

Validate all input at trust boundaries with schema validation (Zod strict, Pydantic extra="forbid", or equivalent). Reject unknown fields. For injection cases, rich text, and output encoding, read references/owasp-top10.md A05 and references/language-quirks.md.

2. Authentication Checklist

Use this checklist for login, session, token, password reset, magic link, OAuth, and admin access:

• Passwords hashed with argon2id or bcrypt; use MD5, SHA1, or raw SHA256 only for non-security hashing.
• Access tokens are short-lived (15 minutes recommended; up to 60 minutes acceptable per org policy).
• Refresh tokens rotate on use and support family invalidation after reuse detection.
• Browser tokens live in httpOnly, secure, sameSite cookies; keep session tokens out of localStorage.
• OAuth uses Authorization Code + PKCE; avoid implicit flow (deprecated, token-in-URL exposure).
• Sensitive actions such as email change, MFA reset, payout change, and password change require step-up auth.
• Failed logins are rate-limited and delayed progressively.
• Session invalidation runs after password reset, password change, and privilege change.
• Password reset tokens are one-time, short-lived, and stored hashed server-side.
• Auth errors are generic — avoid revealing whether a specific email exists.

See references/owasp-top10.md A07 for implementation patterns. See references/asvs-checklist.md V2 and V3 before deploy.

3. Authorization and Sensitive Flows

Authentication says who the caller is. Authorization says what the caller may do. Security failures happen when a route checks only the first.

Required rules

• Default deny.
• Enforce RBAC or ABAC before business logic.
• Perform ownership checks on every resource read and write.
• Scope queries by tenant and actor, not only by route.
• Re-check authorization on bulk actions, background jobs, exports, and webhooks.
• Keep internal flags, role names, and hidden fields out of response serializers.

See references/owasp-top10.md A01 for code pairs. See dev-backend/SKILL.md §4 for middleware execution order.

4. Secrets Management

Secrets are values that grant access, identity, or decryption capability. Treat API keys, database credentials, signing keys, OAuth client secrets, webhook secrets, certificates, and recovery codes as secrets.

If a repository change touches secrets, run gitleaks before claiming done. If a feature adds webhook verification or JWT signing, treat key rollover as part of the feature. For scanning recipes, read references/static-analysis.md. For agent workflows and exfiltration risk, read references/agentic-ai-security.md.

5. Security Headers

This skill owns header policy values. dev-backend owns middleware ordering and integration points.

Minimum production header baseline

• Strict-Transport-Security: max-age=31536000; includeSubDomains
• Content-Security-Policy with explicit default-src, script-src, style-src, img-src, connect-src, frame-ancestors, and base-uri
• X-Content-Type-Options: nosniff
• Referrer-Policy: strict-origin-when-cross-origin
• Permissions-Policy with unused capabilities disabled
• X-Frame-Options: DENY when CSP frame-ancestors is not sufficient for legacy support
• Cross-Origin-Opener-Policy and Cross-Origin-Resource-Policy where required by the app

Apply these via the framework's standard header middleware (Helmet for Express, equivalents elsewhere). Exact directive values are environment-specific — CSP especially must be designed around the app's real script/style/asset/connect origins, not copied from a template.

Frontend touchpoints that must stay aligned

• CSP compliance: no inline scripts, no unsafe event handlers, no surprise third-party script injection.
• CORS: explicit origin allowlist and correct credential mode for cookie-based auth.
• Avoid dangerouslySetInnerHTML unless sanitized with a maintained sanitizer and defended by CSP.
• Prefer cookies over browser storage for session tokens.

See references/owasp-top10.md A02 and A05. See dev-frontend/SKILL.md §§5-7 for performance and accessibility guardrails that still apply after security changes.

6. Rate Limiting

Apply rate limiting per IP and, where available, per user, tenant, and credential target. Return 429 Too Many Requests with Retry-After. Log repeated abuse without logging secrets or raw PII.

Treat the limits below as risk-based starting defaults, not fixed gates — tune them to real traffic, abuse risk, and threat model.

Rate limiting is not only for brute force. Use it for enumeration, abuse, accidental loops, webhook replay storms, and AI-triggered runaway automation.

7. Static Analysis Integration

Security claims are incomplete without automated checks. At minimum, run the project-native SAST, dependency-audit, and secret-scan tools (e.g. npm audit/pip-audit, semgrep, gitleaks) in local development and CI. Use whatever the repo already standardizes on; exact commands belong in repo docs.

For CI templates, pre-commit hooks, and tool-specific guidance, read references/static-analysis.md. For review gating, combine this with dev-code-reviewer/SKILL.md §§1-2.

8. Agent Configuration Security

Agent-authored configuration files create a trust surface distinct from application code.

Configuration Audit Checklist

MCP Server Vetting

Before enabling any MCP server:

• Verify the package source and maintainer on npm/PyPI.
• Prefer pinned versions over npx -y auto-install.
• Restrict server capabilities to the minimum required scope.
• Use ${ENV_VAR} references for all credentials.

Sandboxing and Blast Radius Containment

Reduce the impact of any single compromise:

• Run agent tools with least-privilege filesystem access.
• Scope database credentials to the minimum required tables and operations.
• Isolate CI runners from production secrets using environment separation.
• Use network egress filtering for build and agent environments.
• Prefer ephemeral credentials that expire after the task completes.
• When an agent can execute shell commands, maintain an explicit deny list for destructive operations.

9. Pre-Flight Security Checklist

A security-sensitive change is complete only when every applicable item passes.

• Threat model names assets, attacker, trust boundary, and blast radius.
• All user input is validated at the first trusted boundary with unknown fields rejected.
• Authentication covers token TTL, cookie flags, reset flow, and revocation rules.
• Authorization is enforced per resource, not only per route.
• Queries, commands, templates, and serializers are protected from injection.
• Secrets are not committed, logged, embedded in screenshots, or exposed in client bundles.
• Security headers and CORS are explicit for the deployed environment.
• File upload, payment, logging, and PII changes pass their must-pass checks from the relevant reference.
• Rate limiting covers auth, public endpoints, and abuse-prone flows.
• Static analysis runs clean enough for the repository policy: Semgrep, CodeQL or equivalent, dependency audit, and secret scan.
• Error handling returns safe client messages and preserves structured server-side diagnostics.
• ASVS Level 1 passes for all security-sensitive changes; Level 2 passes for auth, payments, PII, admin, or multi-tenant flows.
• Agentic workflows resist prompt injection, tool misuse, exfiltration, and excessive agency.

Must-Pass Addenda for High-Risk Changes

Logging and PII

• Raw email, phone number, access token, session cookie, recovery code, and payment data are redacted before logs and traces.
• Retention and deletion behavior are defined for the new data.

File Uploads

• Enforce file type, file size, storage path isolation, malware scanning policy, and download authorization.
• Validate server-side — the client-provided filename and MIME type are untrusted input.

Payments

• Idempotency, webhook signature verification, reconciliation, and failure-state handling are tested.
• Payment provider secrets stay out of logs, analytics, and client bundles.

If any item remains unknown, stop, investigate, and resolve the gap before proceeding.

10. Security Ownership Matrix

This matrix clarifies who defines, implements, and verifies each security control across the skill bundle:

Reference this matrix from dev-backend and dev-frontend when ownership is unclear.