Skip to content

Bruno-Cunha-Souza/ValarMindSkills / skills/code-security-review

code-security-review

Flagged

Web/API security lifecycle for Go, Next.js, Python, and Bun — design controls, active testing, supply-chain/CI-CD, and LLM/agentic/MCP coverage. Maps to OWASP Web Top 10 2025 + API 2023 + LLM 2025 + Agentic 2026. Triggers: 'security review', 'revisão de segurança', 'auditar segurança', 'pentest', '/code-security-review'.

FileKindSize
SKILL.mdskill md17.3 KB
references/AI_SECURITY.mdmarkdown9.5 KB
references/DESIGN_CONTROLS.mdmarkdown18.0 KB
references/REPORT_TEMPLATE.mdmarkdown2.6 KB
references/SUPPLY_CHAIN_CICD.mdmarkdown9.1 KB
references/TESTING_PHASES.mdmarkdown17.5 KB
references/WEB_VULNERABILITIES.mdmarkdown22.1 KB
references/golang/API.mdmarkdown27.6 KB
references/golang/MIDDLEWARE.mdmarkdown14.4 KB
references/golang/PATCHES.mdmarkdown15.0 KB
references/golang/TESTING_PAYLOADS.mdmarkdown10.9 KB
references/golang/VULNERABILITIES.mdmarkdown20.6 KB
references/nextjs/API.mdmarkdown38.5 KB
references/nextjs/CONFIGURATION.mdmarkdown15.7 KB
references/nextjs/PATCHES.mdmarkdown16.7 KB
references/nextjs/TESTING_PAYLOADS.mdmarkdown11.9 KB
references/nextjs/VULNERABILITIES.mdmarkdown35.7 KB
references/python/API.mdmarkdown36.0 KB
references/python/CONFIGURATION.mdmarkdown22.4 KB
references/python/PATCHES.mdmarkdown12.1 KB
references/python/TESTING_PAYLOADS.mdmarkdown12.8 KB
references/python/VULNERABILITIES.mdmarkdown28.1 KB
scripts/00-pre-checks.shexecutablescript3.7 KB
scripts/01-auth-probes.shexecutablescript5.4 KB
scripts/02-jwt-attacks.pyexecutablescript10.1 KB
scripts/03-bola-probes.shexecutablescript6.4 KB
scripts/04-injection-probes.shexecutablescript7.3 KB
scripts/05-burst.k6.jsscript1.9 KB
scripts/05-rate-limit.shexecutablescript5.0 KB
scripts/06-info-disclosure.shexecutablescript5.2 KB
scripts/07-supply-chain.shexecutablescript7.9 KB
scripts/08-cors-headers.shexecutablescript5.5 KB
scripts/09-cicd-workflows.shexecutablescript6.1 KB
scripts/10-secrets-scan.shexecutablescript5.2 KB
scripts/11-ai-llm-probes.shexecutablescript8.8 KB
scripts/README.mdmarkdown8.0 KB
scripts/lib/common.shscript4.8 KB
scripts/lib/report.pyscript5.4 KB
scripts/run-all.shexecutablescript4.8 KB

references/DESIGN_CONTROLS.md

View on GitHub
# Design Controls

Proactive controls to implement when building or hardening REST/GraphQL APIs in **FastAPI**, **Gin**, **Fiber**, or **Elysia**.

> Companion: `TESTING_PHASES.md` validates these controls with active probes.

## Authentication & Authorization

### OAuth 2.1 Key Changes from 2.0

OAuth 2.1 (draft consolidation) codifies best practices that were previously scattered across RFCs:

- **PKCE is mandatory for all clients** — including confidential server-side clients
- **Implicit flow removed** — use Authorization Code + PKCE instead
- **Resource Owner Password Credentials (ROPC) removed** — migrate to Device Flow for CLI/native apps
- **Redirect URIs must be exact matches** — no wildcard or partial matching

### DPoP (Demonstrating Proof-of-Possession)

DPoP binds an access token to a specific client key pair, preventing token replay if stolen:

1. Client generates an ephemeral key pair per session
2. Each request includes a signed `DPoP` header with the public key thumbprint and request method/URI
3. Authorization server issues a token bound to that thumbprint
4. Resource server verifies the `DPoP` header on every request

Use DPoP when tokens cross trust boundaries (public APIs, mobile apps) and bearer token theft is a realistic threat.

### JWT Best Practices

- Prefer **RS256** (RSA) or **EdDSA** (Ed25519) over **HS256** (HMAC) — asymmetric keys allow public verification without sharing the secret
- Always validate `iss` (issuer) and `aud` (audience) claims explicitly — do not rely on library defaults
- Set short access token TTL (15–60 min); use refresh tokens for long sessions
- Implement **rotating refresh tokens with reuse detection**: each use invalidates the current token and issues a new one — a second use of the same token should revoke the entire family

### Framework Callouts

#### FastAPI

```python
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import JWTError, jwt

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/auth/token")

async def get_current_user(token: str = Depends(oauth2_scheme)):
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=["RS256"],
                             audience="your-api", issuer="your-auth-server")
        user_id: str = payload.get("sub")
        if user_id is None:
            raise credentials_exception
    except JWTError:
        raise credentials_exception
    return user_id
```

Packages: `fastapi-users` (full auth solution), `python-jose` or `authlib` (JWT), `passlib[bcrypt]` (password hashing).

#### Gin

```go
// Use appleboy/gin-jwt middleware
authMiddleware, _ := jwt.New(&jwt.GinJWTMiddleware{
    Realm:       "your-api",
    Key:         []byte(os.Getenv("JWT_SECRET")),
    Timeout:     time.Hour,
    IdentityKey: "user_id",
    PayloadFunc: func(data interface{}) jwt.MapClaims {
        if v, ok := data.(*User); ok {
            return jwt.MapClaims{"user_id": v.ID}
        }
        return jwt.MapClaims{}
    },
})
r.POST("/auth/login", authMiddleware.LoginHandler)
auth := r.Group("/api")
auth.Use(authMiddleware.MiddlewareFunc())
```

#### Fiber

```go
// Use gofiber/contrib/jwt
app.Use(jwtware.New(jwtware.Config{
    SigningKey: jwtware.SigningKey{
        JWTAlg: jwtware.RS256,
        Key:    publicKey,
    },
    ErrorHandler: func(c *fiber.Ctx, err error) error {
        return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "invalid token"})
    },
}))
```

#### Elysia (Bun)

```typescript
import { Elysia } from "elysia";
import { jwt } from "@elysiajs/jwt";
import { bearer } from "@elysiajs/bearer";

// Note: @elysiajs/bearer ONLY extracts the token from the Authorization header.
// It does NOT validate it. JWT validation must be explicit.
const app = new Elysia()
  .use(jwt({ name: "jwt", secret: process.env.JWT_SECRET! }))
  .use(bearer())
  .derive(async ({ bearer, jwt }) => {
    const payload = await jwt.verify(bearer);
    if (!payload) throw new Error("Unauthorized");
    return { user: payload };
  });
```

### Anti-Pattern: `allow_credentials=True` + Wildcard Origin

```python
# CRITICAL — CVE-2025-34291 (Langflow) class of vulnerability
# This combination allows any website to make credentialed cross-origin requests
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],          # ← wildcard
    allow_credentials=True,       # ← credentials
    allow_methods=["*"],
    allow_headers=["*"],
)
# Browsers will reject this combination per the CORS spec,
# but some HTTP clients (curl, httpx) will not — creating SSRF and data exfiltration risks.
# ALWAYS use an explicit allowlist when credentials=True.
```

## Input Validation & Injection Prevention

**Principle: validate at the boundary, reject early.**

Accept only what you explicitly define; reject everything else.

### Framework Callouts: Input Validation

#### FastAPI / Pydantic

```python
from pydantic import BaseModel, ConfigDict, field_validator
import re

class CreateUserRequest(BaseModel):
    model_config = ConfigDict(strict=True)  # reject coercion (int → str, etc.)

    email: str
    username: str
    age: int

    @field_validator("email")
    @classmethod
    def validate_email(cls, v: str) -> str:
        # Avoid regex engines on untrusted input — use a simple check or a library
        # CVE-2024-3772: pydantic < 2.4.0 ReDoS via email validator on long inputs
        if len(v) > 254 or "@" not in v:
            raise ValueError("invalid email")
        return v.lower()
```

> **CVE-2024-3772**: pydantic < 2.4.0 — ReDoS via malformed email strings. Upgrade to 2.4.0+.
> **CVE-2024-24762**: python-multipart — unbounded memory on form-data. Pin `python-multipart >= 0.0.7`.

#### Go (pgx / sqlx)

```go
// Always use parameterized queries — never fmt.Sprintf for SQL
row := db.QueryRow(ctx,
    "SELECT id, email FROM users WHERE id = $1", userID)

// go-playground/validator for struct validation
type CreateUserRequest struct {
    Email    string `json:"email" validate:"required,email,max=254"`
    Username string `json:"username" validate:"required,alphanum,min=3,max=32"`
}

validate := validator.New()
if err := validate.Struct(req); err != nil {
    c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
    return
}
```

#### Elysia (TypeBox)

```typescript
import { t } from "elysia";

// TypeBox schema — validated at compile-time AND runtime
// additionalProperties: false prevents mass assignment
app.post("/users", ({ body }) => createUser(body), {
  body: t.Object({
    email: t.String({ format: "email", maxLength: 254 }),
    username: t.String({ minLength: 3, maxLength: 32, pattern: "^[a-zA-Z0-9_]+$" }),
    age: t.Integer({ minimum: 0, maximum: 150 }),
  }, { additionalProperties: false }),
});
```

### Injection Prevention Rules

| Vector | Prevention |
| --- | --- |
| SQL Injection | Parameterized queries or ORM — never string concatenation |
| NoSQL Injection | Cast/validate input type before passing to query builder |
| Command Injection | Avoid shell execution; if unavoidable, use argument arrays, not strings |
| SSRF | URL allowlist + block RFC1918/loopback; do not follow redirects automatically |
| XXE | Disable external entity processing in XML parsers |

## Rate Limiting & Throttling

### Algorithm Selection

| Algorithm | Best for | Trade-off |
| --- | --- | --- |
| **Token Bucket** | APIs with bursty traffic | Allows short bursts above average rate |
| **Sliding Window** | Strict fairness, auth endpoints | Higher Redis memory usage |
| **Fixed Window** | Simple implementations | Boundary burst vulnerability |

Use **sliding window** for authentication endpoints (brute force prevention) and **token bucket** for general API traffic.

### For AI APIs: Rate Limit by Token Count

Request count is an insufficient proxy for compute cost. Rate limit by input + output token count using a leaky-bucket or quota system, similar to OpenAI's TPM (tokens per minute) model.

### Framework Callouts: Rate Limiting

#### FastAPI (SlowAPI)

```python
from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.util import get_remote_address
from slowapi.errors import RateLimitExceeded

limiter = Limiter(key_func=get_remote_address, storage_uri="redis://localhost:6379")
app.state.limiter = limiter
app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)

@app.post("/auth/login")
@limiter.limit("5/15minutes")  # strict limit for auth endpoints
async def login(request: Request, ...):
    ...

@app.get("/api/data")
@limiter.limit("100/minute")
async def get_data(request: Request, ...):
    ...
```

#### Gin Rate Limiting

```go
// Using gin-contrib/ratelimit or a custom Redis middleware
func RateLimitMiddleware(rdb *redis.Client, limit int, window time.Duration) gin.HandlerFunc {
    return func(c *gin.Context) {
        key := "rl:" + c.ClientIP()
        count, _ := rdb.Incr(ctx, key).Result()
        if count == 1 {
            rdb.Expire(ctx, key, window)
        }
        if int(count) > limit {
            c.Header("Retry-After", strconv.Itoa(int(window.Seconds())))
            c.AbortWithStatusJSON(429, gin.H{"error": "rate limit exceeded"})
            return
        }
        c.Header("X-RateLimit-Remaining", strconv.Itoa(limit-int(count)))
        c.Next()
    }
}
```

#### Fiber (built-in) Rate Limiting

```go
import "github.com/gofiber/fiber/v2/middleware/limiter"

app.Use(limiter.New(limiter.Config{
    Max:        100,
    Expiration: 1 * time.Minute,
    KeyGenerator: func(c *fiber.Ctx) string {
        return c.IP()
    },
    LimitReached: func(c *fiber.Ctx) error {
        return c.Status(fiber.StatusTooManyRequests).JSON(fiber.Map{
            "error": "rate limit exceeded",
        })
    },
}))
```

#### Elysia Rate Limiting

```typescript
// Elysia does not include a built-in rate limiter as of 2025
// Use the community plugin or implement middleware:
import { Elysia } from "elysia";

const rateLimitMap = new Map<string, { count: number; reset: number }>();

const rateLimit = (limit: number, windowMs: number) =>
  new Elysia().derive(({ request, set }) => {
    const ip = request.headers.get("x-forwarded-for") ?? "unknown";
    const now = Date.now();
    const entry = rateLimitMap.get(ip) ?? { count: 0, reset: now + windowMs };
    if (now > entry.reset) { entry.count = 0; entry.reset = now + windowMs; }
    entry.count++;
    rateLimitMap.set(ip, entry);
    set.headers["X-RateLimit-Limit"] = String(limit);
    set.headers["X-RateLimit-Remaining"] = String(Math.max(0, limit - entry.count));
    if (entry.count > limit) {
      set.status = 429;
      set.headers["Retry-After"] = String(Math.ceil((entry.reset - now) / 1000));
      return { error: "rate limit exceeded" };
    }
  });
```

### Required Rate Limit Response Headers

```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1740000000
Retry-After: 900
```

## Security Headers & CORS

### CORS Rules

- **Never** combine `allow_origins=["*"]` with `allow_credentials=True`
- Use explicit allowlists — validate `Origin` against a list, not a wildcard regex
- Restrict `allow_methods` to only what each route needs

### Framework Callouts: CORS

#### FastAPI CORS

```python
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com", "https://admin.example.com"],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["Authorization", "Content-Type"],
)
```

#### Gin CORS

```go
import "github.com/gin-contrib/cors"

r.Use(cors.New(cors.Config{
    AllowOrigins:     []string{"https://app.example.com"},
    AllowMethods:     []string{"GET", "POST", "PUT", "DELETE"},
    AllowHeaders:     []string{"Authorization", "Content-Type"},
    AllowCredentials: true,
    MaxAge:           12 * time.Hour,
    // AllowAllOrigins: true would prevent cookies/credentials from working
}))
```

#### Fiber CORS

```go
import (
    "github.com/gofiber/fiber/v2/middleware/cors"
    "github.com/gofiber/fiber/v2/middleware/helmet"
)

app.Use(helmet.New())  // sets XSS, MIME sniff, X-Frame-Options, HSTS
app.Use(cors.New(cors.Config{
    AllowOrigins:     "https://app.example.com",
    AllowHeaders:     "Authorization, Content-Type",
    AllowCredentials: true,
}))
```

#### Elysia CORS

```typescript
import cors from "@elysiajs/cors";

app.use(cors({
  origin: ["https://app.example.com"],
  credentials: true,
  allowedHeaders: ["Authorization", "Content-Type"],
}));
```

### Minimum Required Security Headers

| Header | Value | Purpose |
| --- | --- | --- |
| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains` | Enforce HTTPS |
| `X-Content-Type-Options` | `nosniff` | Prevent MIME sniffing |
| `X-Frame-Options` | `DENY` | Prevent clickjacking |
| `Content-Security-Policy` | `default-src 'self'` | Restrict resource loading |
| `Referrer-Policy` | `strict-origin-when-cross-origin` | Limit referrer leakage |

## Data Protection & Error Handling

### Error Handling Rules

- **Never** return stack traces, SQL errors, or file paths to the client in production
- Return generic error messages to clients; log full details internally
- Use consistent error response shape — `{"error": "message", "code": "ERROR_CODE"}`
- Return `404 Not Found` for missing resources regardless of whether the record exists vs. access is denied for sensitive resources (prevents enumeration)

### Data Serialization Rules

- **Never** serialize ORM model objects directly — define explicit DTO/response schemas
- Explicitly list allowed fields in responses; use `select` or `include` patterns
- Do not log passwords, tokens, secrets, PII, or payment card data

### TLS Requirements

- TLS 1.2 minimum; TLS 1.3 preferred (removes weak cipher suites, provides 0-RTT option)
- Use `HSTS` with `preload` for public APIs
- For internal service-to-service: see mTLS section below

**FastAPI — production error handler example:**

```python
from fastapi import Request
from fastapi.responses import JSONResponse
import logging

logger = logging.getLogger(__name__)

@app.exception_handler(Exception)
async def generic_exception_handler(request: Request, exc: Exception):
    logger.error("Unhandled exception", exc_info=exc, extra={"path": request.url.path})
    return JSONResponse(
        status_code=500,
        content={"error": "An unexpected error occurred"},
    )
```

## Supply Chain Security

Quick per-ecosystem commands below. For the full A03:2025 deep-dive — lockfile pinning, GitHub Actions hardening, secrets hygiene, SBOM, typosquatting/slopsquatting, and incident case studies — see [`SUPPLY_CHAIN_CICD.md`](SUPPLY_CHAIN_CICD.md).

### Python

```bash
# Audit installed packages for CVEs
pip-audit

# Lock dependencies with hashes (tamper detection)
pip install --require-hashes -r requirements.txt

# In CI — fail if any vulnerable package is found
pip-audit --strict
```

Recommended: use `poetry.lock` or `pip-compile` with hash verification. Never `--no-verify`.

### Go

```bash
# Verify module checksums against go.sum
go mod verify

# Scan for known vulnerabilities in dependencies
govulncheck ./...

# go.sum MUST be committed — it is the source of truth for module integrity
```

Set `GONOSUMDB` only for internal-only modules. Do not set `GONOSUMCHECK` globally.

### Bun / Node

```bash
# CI — fail if lockfile does not match package.json
bun install --frozen-lockfile

# Audit for CVEs
bun audit           # or: npm audit --audit-level=high

# lockfile (bun.lockb) MUST be committed
```

> **PackageGate (Jan 2026)**: Bun's `trustedDependencies` list allows lifecycle scripts from specific packages by default. Review which packages are on this list and audit their postinstall scripts before adding to production builds.

### Cross-Stack Tools

| Tool | Stack | Command |
| --- | --- | --- |
| `snyk` | All | `snyk test` |
| `trivy` | Container + deps | `trivy fs .` |
| `govulncheck` | Go | `govulncheck ./...` |
| `pip-audit` | Python | `pip-audit` |
| `bun audit` | Bun/Node | `bun audit` |

## mTLS for Service-to-Service Communication

Mutual TLS requires both client and server to present certificates, eliminating reliance on network perimeter for trust.

### When to Use mTLS

- Microservices in zero-trust networks
- Service-to-database connections containing sensitive data
- Internal APIs that should never be reachable from external clients

### mTLS Implementation Options

#### Service mesh (recommended for Kubernetes)

Istio, Linkerd, and Consul Connect provide transparent mTLS without application code changes. The sidecar proxy handles certificate negotiation automatically.

```yaml
# Istio — enforce mTLS for the entire namespace
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: default
  namespace: production
spec:
  mtls:
    mode: STRICT
```

#### cert-manager (Kubernetes)

Automates certificate issuance, rotation, and renewal from Let's Encrypt, Vault, or internal CAs. Short certificate validity (24–72 hours) limits the blast radius of a leaked certificate.

#### Application-level (FastAPI example)

```python
import ssl
import httpx

ssl_ctx = ssl.create_default_context(ssl.Purpose.SERVER_AUTH, cafile="ca.pem")
ssl_ctx.load_cert_chain(certfile="client.pem", keyfile="client.key")

async with httpx.AsyncClient(verify=ssl_ctx) as client:
    response = await client.get("https://internal-service/api/data")
```

## AI / LLM API Security

When your API is AI-powered, consumes LLM services, exposes agentic tools, or runs MCP servers, the model surface needs its own controls. Token-budget rate limiting is the one design control that belongs here:

```python
# Count tokens before sending to LLM; reject if over budget (LLM10 Unbounded Consumption)
from tiktoken import encoding_for_model

enc = encoding_for_model("gpt-4o")
if len(enc.encode(user_input)) > MAX_INPUT_TOKENS:
    raise HTTPException(status_code=400, detail="Input too long")
```

See [`AI_SECURITY.md`](AI_SECURITY.md) for the full reference: OWASP LLM Top 10 2025, Agentic Top 10 2026, MCP security, prompt-injection design controls, AI-generated-code review, and testing payloads.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall