@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/skills/shared/external/api-security-best-practices/SKILL.md

@@ -1,212 +1,162 @@
 ---
 name: api-security-best-practices
-description: "Implement secure API design patterns including authentication, authorization, input validation, rate limiting, and protection against common API vulnerabilities. Use when designing or reviewing an API's authentication, authorization, input validation or rate limiting."
-risk: unknown
-source: community
-date_added: "2026-02-27"
+description: "API security against the OWASP API Top 10: object-level authorization, token handling, input validation, rate limits, secrets. Use when building, reviewing or hardening an HTTP API or its auth layer."
+metadata:
+  risk: safe
+  source: multi-agent-pipeline
+  date_added: "2026-09-25"
 ---
 
 # API Security Best Practices
 
-## Overview
+Most API breaches are not clever. A caller changes an id in the URL and reads
+someone else's order; a client sends `"role": "admin"` in a profile update and
+the server saves it; an endpoint returns the whole database row and the app
+hides the sensitive columns in the UI. The controls below close those holes.
+They are organised around the OWASP API Security Top 10 (2023) because that
+list reflects how APIs are actually attacked.
 
-Guide developers in building secure APIs by implementing authentication, authorization, input validation, rate limiting, and protection against common vulnerabilities. This skill covers security patterns for REST, GraphQL, and WebSocket APIs.
+This skill is for building and reviewing controls. For a structured audit of a
+whole diff or repository with CVSS-scored findings, use `security-review`.
 
-## When to Use This Skill
+## Reference files
 
-- Use when designing new API endpoints
-- Use when securing existing APIs
-- Use when implementing authentication and authorization
-- Use when protecting against API attacks (injection, DDoS, etc.)
-- Use when conducting API security reviews
-- Use when preparing for security audits
-- Use when implementing rate limiting and throttling
-- Use when handling sensitive data in APIs
+| File | Load it when |
+|---|---|
+| `references/identity-and-access.md` | Validating tokens, sessions, API keys, service identity, writing authorization checks |
+| `references/request-handling.md` | Validating input, shaping responses, preventing injection, SSRF and mass assignment |
+| `references/abuse-controls.md` | Rate limits, quotas, payload limits, bot and enumeration defence |
+| `references/operations.md` | Secrets, TLS and headers, security logging, testing the controls |
 
-## Reference Files
+## The ten risks as questions
 
-Load the reference that matches the axis under review; each holds the full runnable implementations plus the common pitfalls for that axis.
+Ask each question of every endpoint you add or review. A "no" or "not sure" is
+a finding.
 
-- `references/auth.md` - JWT token generation, verification middleware, route protection, token refresh, and the JWT-secret and missing-authorization pitfalls. Load when implementing or reviewing authentication or access control.
-- `references/input-validation.md` - parameterized queries, ORM escaping, Zod schema validation, XSS output sanitization, and the weak-password and verbose-error pitfalls. Load when handling any user input, query, or file upload.
-- `references/rate-limiting.md` - fixed-window and per-tier rate limiters, Helmet security headers, and rate-limit response headers. Load when protecting endpoints from abuse, brute force, or DDoS.
+### API1 Broken object level authorization (BOLA)
 
-## How It Works
+*Does the handler prove this caller may touch this specific object?*
 
-### Step 1: Authentication & Authorization
+Authentication says who the caller is; it says nothing about whether order
+`o_4411` belongs to them. Scope every lookup by the principal, in the query
+itself, not in a check after the fetch.
 
-- Choose authentication method (JWT, OAuth 2.0, API keys)
-- Implement token-based authentication
-- Set up role-based access control (RBAC)
-- Secure session management
-- Implement multi-factor authentication (MFA)
+Query: `references/identity-and-access.md`.
 
-Full implementations: `references/auth.md`.
+Return 404, not 403, for rows the caller cannot see, so ids cannot be
+probed. Opaque random ids (UUIDv7, ULID) help but are not a control on their own.
 
-### Step 2: Input Validation & Sanitization
+### API2 Broken authentication
 
-- Validate all input data
-- Sanitize user inputs
-- Use parameterized queries
-- Implement request schema validation
-- Prevent SQL injection, XSS, and command injection
+*Is every credential verified the same strict way on every route?*
 
-Full implementations: `references/input-validation.md`.
+- Verify JWT signature, `alg` against an allowlist, `iss`, `aud`, `exp` and
+  `nbf`. Never accept `alg: none` or let the token choose the key.
+- Short-lived access tokens (5 to 15 minutes); rotate refresh tokens and detect
+  reuse.
+- Rate limit and lock out credential endpoints (login, OTP, password reset).
+- Prefer a maintained identity provider or library over hand-rolled crypto.
 
-### Step 3: Rate Limiting & Throttling
+### API3 Broken object property level authorization
 
-- Implement rate limiting per user/IP
-- Set up API throttling
-- Configure request quotas
-- Handle rate limit errors gracefully
-- Monitor for suspicious activity
+*Can the caller read or write a field they should not?*
 
-Full implementations: `references/rate-limiting.md`.
+This merges the old "excessive data exposure" and "mass assignment" risks.
 
-### Step 4: Data Protection
+- Response: serialise through an explicit output schema per audience; never
+  return the ORM entity.
+- Request: bind to an input schema that lists writable fields; reject or drop
+  everything else. `isAdmin`, `accountId`, `priceOverride` are never
+  client-writable.
 
-- Encrypt data in transit (HTTPS/TLS)
-- Encrypt sensitive data at rest
-- Implement proper error handling (no data leaks)
-- Sanitize error messages
-- Use secure headers (see Helmet setup in `references/rate-limiting.md`)
-
-### Step 5: API Security Testing
-
-- Test authentication and authorization
-- Perform penetration testing
-- Check for common vulnerabilities (OWASP API Top 10)
-- Validate input handling
-- Test rate limiting
-
-## Illustrative Snippets
-
-Verify a bearer token before the handler runs; full middleware in `references/auth.md`:
-
-```javascript
-const authHeader = req.headers['authorization'];
-const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN
-if (!token) return res.status(401).json({ error: 'Access token required' });
-```
-
-Never build SQL from user input; parameterize instead (full patterns in `references/input-validation.md`):
-
-```javascript
-// Bad:  `SELECT * FROM users WHERE id = '${userId}'`
-// Good:
-await db.query('SELECT id, email, name FROM users WHERE id = $1', [userId]);
-```
-
-## Best Practices
-
-### Do This
-
-- **Use HTTPS Everywhere** - Never send sensitive data over HTTP
-- **Implement Authentication** - Require authentication for protected endpoints
-- **Validate All Inputs** - Never trust user input
-- **Use Parameterized Queries** - Prevent SQL injection
-- **Implement Rate Limiting** - Protect against brute force and DDoS
-- **Hash Passwords** - Use bcrypt with salt rounds >= 10
-- **Use Short-Lived Tokens** - JWT access tokens should expire quickly
-- **Implement CORS Properly** - Only allow trusted origins
-- **Log Security Events** - Monitor for suspicious activity
-- **Keep Dependencies Updated** - Regularly update packages
-- **Use Security Headers** - Implement Helmet.js
-- **Sanitize Error Messages** - Don't leak sensitive information
-
-### Don't Do This
-
-- **Don't Store Passwords in Plain Text** - Always hash passwords
-- **Don't Use Weak Secrets** - Use strong, random JWT secrets
-- **Don't Trust User Input** - Always validate and sanitize
-- **Don't Expose Stack Traces** - Hide error details in production
-- **Don't Use String Concatenation for SQL** - Use parameterized queries
-- **Don't Store Sensitive Data in JWT** - JWTs are not encrypted
-- **Don't Ignore Security Updates** - Update dependencies regularly
-- **Don't Use Default Credentials** - Change all default passwords
-- **Don't Disable CORS Completely** - Configure it properly instead
-- **Don't Log Sensitive Data** - Sanitize logs
-
-## Common Pitfalls
-
-Each pitfall's symptom-to-fix code lives in the reference file for its axis.
-
-- **JWT secret exposed in code** - hardcoded or committed secret; load from env and fail fast if missing. See `references/auth.md`.
-- **Missing authorization checks** - authentication passes but resource ownership is never verified. See `references/auth.md`.
-- **Weak password requirements** - no strength floor; enforce a schema or a strength library. See `references/input-validation.md`.
-- **Verbose error messages** - raw DB errors returned to the client; log server-side, return generic messages. See `references/input-validation.md`.
-
-## Security Checklist
-
-### Authentication & Authorization
-- [ ] Implement strong authentication (JWT, OAuth 2.0)
-- [ ] Use HTTPS for all endpoints
-- [ ] Hash passwords with bcrypt (salt rounds >= 10)
-- [ ] Implement token expiration
-- [ ] Add refresh token mechanism
-- [ ] Verify user authorization for each request
-- [ ] Implement role-based access control (RBAC)
-
-### Input Validation
-- [ ] Validate all user inputs
-- [ ] Use parameterized queries or ORM
-- [ ] Sanitize HTML content
-- [ ] Validate file uploads
-- [ ] Implement request schema validation
-- [ ] Use allowlists, not blocklists
-
-### Rate Limiting & DDoS Protection
-- [ ] Implement rate limiting per user/IP
-- [ ] Add stricter limits for auth endpoints
-- [ ] Use Redis for distributed rate limiting
-- [ ] Return proper rate limit headers
-- [ ] Implement request throttling
-
-### Data Protection
-- [ ] Use HTTPS/TLS for all traffic
-- [ ] Encrypt sensitive data at rest
-- [ ] Don't store sensitive data in JWT
-- [ ] Sanitize error messages
-- [ ] Implement proper CORS configuration
-- [ ] Use security headers (Helmet.js)
-
-### Monitoring & Logging
-- [ ] Log security events
-- [ ] Monitor for suspicious activity
-- [ ] Set up alerts for failed auth attempts
-- [ ] Track API usage patterns
-- [ ] Don't log sensitive data
-
-## OWASP API Security Top 10
-
-1. **Broken Object Level Authorization** - Always verify user can access resource
-2. **Broken Authentication** - Implement strong authentication mechanisms
-3. **Broken Object Property Level Authorization** - Validate which properties user can access
-4. **Unrestricted Resource Consumption** - Implement rate limiting and quotas
-5. **Broken Function Level Authorization** - Verify user role for each function
-6. **Unrestricted Access to Sensitive Business Flows** - Protect critical workflows
-7. **Server Side Request Forgery (SSRF)** - Validate and sanitize URLs
-8. **Security Misconfiguration** - Use security best practices and headers
-9. **Improper Inventory Management** - Document and secure all API endpoints
-10. **Unsafe Consumption of APIs** - Validate data from third-party APIs
-
-## Related Skills
-
-- `@ethical-hacking-methodology` - Security testing perspective
-- `@sql-injection-testing` - Testing for SQL injection
-- `@xss-html-injection` - Testing for XSS vulnerabilities
-- `@broken-authentication` - Authentication vulnerabilities
-- `@backend-dev-guidelines` - Backend development standards
-- `@systematic-debugging` - Debug security issues
-
-## Additional Resources
-
-- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/)
-- [JWT Best Practices](https://tools.ietf.org/html/rfc8725)
-- [Express Security Best Practices](https://expressjs.com/en/advanced/best-practice-security.html)
-- [Node.js Security Checklist](https://blog.risingstack.com/node-js-security-checklist/)
-- [API Security Checklist](https://github.com/shieldfy/API-Security-Checklist)
+### API4 Unrestricted resource consumption
 
----
+*What stops one caller from exhausting CPU, memory, storage, money or a
+downstream quota?*
+
+Rate limits per identity, body size caps, page size caps, timeouts, GraphQL
+depth and cost limits, upload size and type limits, and spend caps on anything
+that calls a paid provider (SMS, email, LLM). See `references/abuse-controls.md`.
+
+### API5 Broken function level authorization
+
+*Is every privileged operation gated by role or permission on the server?*
+
+Admin routes hidden from the UI are still reachable. Enforce permissions in
+middleware or a policy layer that denies by default, and test that an ordinary
+user gets 403 on each admin route.
+
+### API6 Unrestricted access to sensitive business flows
+
+*Could a script abuse this flow even though each request is individually valid?*
+
+Checkout of limited stock, coupon redemption, account sign-up, review posting.
+Controls are business-aware: per-account and per-device limits, velocity checks,
+proof-of-work or CAPTCHA at the right step, and human review queues.
+
+### API7 Server side request forgery (SSRF)
+
+*Does any endpoint fetch a URL the caller supplied?* Fetch only through an
+allowlisting, private-range-rejecting client; details in
+`references/operations.md`.
+
+### API8 Security misconfiguration
+
+*Is the deployment as strict as the code?*
+
+TLS everywhere, HSTS, CORS limited to known origins (never reflect the `Origin`
+header with credentials), verbose errors off in production, default accounts
+removed, security headers set, unused HTTP methods rejected.
+
+### API9 Improper inventory management
+
+*Do you know every API version and host that is live?*
+
+Old `/v1` routes, staging hosts with production data, forgotten debug
+endpoints. Keep an inventory generated from code (OpenAPI), retire versions on a
+schedule, and apply the same gateway policies to every environment that holds
+real data.
+
+### API10 Unsafe consumption of APIs
+
+*Do you trust third-party responses more than user input?*
+
+Validate upstream payloads against a schema, set timeouts and size limits,
+follow redirects only deliberately, and never pass upstream strings into SQL,
+shell or HTML unescaped.
+
+## Operating the controls
+
+Detail: `references/operations.md`. Secrets come from a
+secret store with per-environment keys, rotation and hashed API keys, never
+in logs; TLS 1.2+ with HSTS, `no-store` on sensitive responses and `nosniff`;
+structured security events with alerts on 401/403/404 bursts; and BOLA,
+privileged-route, mass-assignment and size-limit tests in the suite, plus
+dependency audit and a DAST baseline in CI.
+
+## Review checklist
+
+- [ ] Every object lookup is scoped by the caller's identity or tenant.
+- [ ] Token validation checks signature, algorithm allowlist, issuer, audience, expiry.
+- [ ] Input and output go through explicit schemas; no raw entities returned.
+- [ ] Privileged routes deny by default and are covered by negative tests.
+- [ ] Per-identity rate limits, body and page size caps, and timeouts are set.
+- [ ] User-supplied URLs are fetched only through an SSRF-safe client.
+- [ ] CORS, TLS, HSTS and error verbosity are production-strict.
+- [ ] Secrets come from a secret store and never reach logs.
+- [ ] Every live version and host is in the inventory.
+- [ ] Third-party responses are validated like user input.
+
+## Related skills
+
+- `security-review`: full audit with threat model and scored findings.
+- `api-patterns`: idempotency and error shapes that also limit abuse.
+- `rest-api-design`: status code choices for auth failures.
+- `nodejs-backend-patterns`, `fastapi-pro`: framework-level wiring.
+- `ios-security`, `android-security`: client-side storage of the tokens issued here.
+
+## External references
 
-**Pro Tip:** Security is not a one-time task - regularly audit your APIs, keep dependencies updated, and stay informed about new vulnerabilities.
+- OWASP API Security Top 10 2023: https://owasp.org/API-Security/editions/2023/en/0x11-t10/
+- OWASP Cheat Sheet Series: https://cheatsheetseries.owasp.org/
+- RFC 8725, JWT Best Current Practices: https://www.rfc-editor.org/rfc/rfc8725

package/pipeline/skills/shared/external/api-security-best-practices/references/abuse-controls.md

@@ -0,0 +1,140 @@
+# Abuse Controls
+
+Limits that keep one caller, script or bug from exhausting the service or its
+budget. Covers OWASP API4 (unrestricted resource consumption) and API6
+(unrestricted access to sensitive business flows).
+
+## Contents
+
+1. Layers of limits
+2. Choosing a rate limit algorithm
+3. Keys: what to limit by
+4. A shared-store limiter
+5. Telling clients about limits
+6. Size, time and cost limits
+7. Protecting business flows
+8. Operating the limits
+
+## 1. Layers of limits
+
+| Layer | Stops | Tooling |
+|---|---|---|
+| Edge / CDN | Volumetric floods, obvious bots | Cloudflare, AWS WAF + Shield, Fastly |
+| API gateway | Per-key quotas, plan tiers | Kong, Envoy, AWS API Gateway usage plans |
+| Application | Per-user and per-route rules that need business context | Middleware backed by Redis or the database |
+| Downstream | Spend on paid providers | Budget counters, provider-side caps |
+
+Do not rely on one layer. The edge cannot tell which account a request belongs
+to; the application cannot absorb a flood.
+
+## 2. Choosing a rate limit algorithm
+
+- **Fixed window** (N per minute, reset on the minute): simplest, allows a burst
+  of 2N at window edges. Fine for coarse quotas.
+- **Sliding window** (weighted count across the current and previous window):
+  smooth, cheap, the usual choice for API limits.
+- **Token bucket** (refill rate R, capacity B): allows short bursts up to B while
+  enforcing an average of R. Good for interactive clients.
+- **Concurrency limit** (at most K running at once): protects slow endpoints such as
+  exports and report generation, where request rate is the wrong measure.
+
+## 3. Keys: what to limit by
+
+- Authenticated routes: the account or API key id, possibly per route group.
+- Credential routes: the submitted identifier (email, username) **and** the
+  source, so neither a spread-out attack on one account nor one source hitting
+  many accounts gets through.
+- Anonymous routes: client IP as seen by your trusted proxy. Configure the
+  framework's trusted proxy list; a naively read `X-Forwarded-For` lets anyone
+  pick their own key.
+- IPv6: limit by /64 prefix, since one host can own a whole block.
+
+## 4. A shared-store limiter
+
+In-memory counters break as soon as there are two instances. Use Redis (or
+Valkey) with an atomic script. A sliding-window sketch:
+
+```lua
+-- KEYS[1] = current window key, KEYS[2] = previous window key
+-- ARGV[1] = limit, ARGV[2] = window seconds, ARGV[3] = elapsed seconds in current window
+local current = tonumber(redis.call("GET", KEYS[1]) or "0")
+local previous = tonumber(redis.call("GET", KEYS[2]) or "0")
+local window = tonumber(ARGV[2])
+local weight = (window - tonumber(ARGV[3])) / window
+local estimated = previous * weight + current
+if estimated >= tonumber(ARGV[1]) then
+  return 0
+end
+redis.call("INCR", KEYS[1])
+redis.call("EXPIRE", KEYS[1], window * 2)
+return 1
+```
+
+In practice use a maintained implementation: `@fastify/rate-limit` or
+`rate-limiter-flexible` on Node, `slowapi` or `limits` on Python, or the
+gateway's built-in plugin. Decide explicitly what happens when Redis is down:
+fail open for general traffic, fail closed for credential endpoints.
+
+## 5. Telling clients about limits
+
+Return `429 Too Many Requests` with a problem-details body and a `Retry-After`
+header in seconds. Advertise the policy so well-behaved clients can pace
+themselves; the IETF `RateLimit` and `RateLimit-Policy` header fields are the
+emerging standard, and many APIs still send `X-RateLimit-Limit`,
+`X-RateLimit-Remaining` and `X-RateLimit-Reset`. Pick one convention and
+document it.
+
+```http
+HTTP/1.1 429 Too Many Requests
+Retry-After: 20
+Content-Type: application/problem+json
+
+{ "type": "https://api.example.com/problems/rate-limited", "title": "Too many requests", "status": 429 }
+```
+
+## 6. Size, time and cost limits
+
+Rate limits count requests; these bound what a single request can cost.
+
+- **Body size:** reject at the proxy (`client_max_body_size`) and in the
+  framework (`bodyLimit`, `max_request_size`). JSON APIs rarely need more than
+  1 MB; uploads get their own route and limit.
+- **Collections:** cap array lengths in schemas and `limit` on list endpoints.
+- **Time:** server-side request timeout, statement timeout on the database
+  (`SET statement_timeout`), and deadlines on outbound calls.
+- **GraphQL:** maximum depth, maximum aliases, a query cost budget per request
+  and per minute, and persisted queries in production.
+- **Regular expressions:** avoid catastrophic backtracking on user input; use
+  linear-time engines (RE2) or bounded patterns.
+- **Compression:** limit decompressed size to stop decompression bombs.
+- **Paid side effects:** per-account daily caps on SMS, email, LLM tokens and
+  payment attempts, with alerts well before the provider bill does.
+
+## 7. Protecting business flows
+
+Some abuse uses perfectly valid, correctly rate-limited requests. Identify the
+flows where volume itself is the harm:
+
+- buying limited-stock products or reserving limited slots;
+- creating accounts, redeeming promo codes or referral rewards;
+- posting reviews, comments or messages to other users;
+- enumerating public identifiers (usernames, order numbers, gift card codes).
+
+Controls, cheapest first:
+
+1. Per-account and per-device limits specific to that flow (one redemption per
+   account, five sign-ups per device per day).
+2. Make identifiers unguessable and responses uniform so enumeration yields
+   nothing.
+3. Friction at the decisive step: email or phone verification, CAPTCHA or
+   privacy-preserving attestation (Turnstile, App Attest, Play Integrity).
+4. Velocity and anomaly scoring with a review queue for borderline cases.
+
+## 8. Operating the limits
+
+- Log every 429 with the key and route; dashboard the top limited keys.
+- Start new limits in report-only mode, read the data, then enforce.
+- Give trusted partners explicit higher tiers instead of exempting them silently.
+- Load test with the limits on, so capacity planning reflects production
+  behaviour.
+- Review limits after incidents and when pricing plans change.