security-design-agent

Security Design Agent

**Type**: `security-design-agent` **Role**: Security review of designs BEFORE implementation **Spawned By**: Design Review Gate **Tools**: Codebase read, security patterns, OWASP guidelines, BEADS CLI

---

Purpose

The Security Design Agent reviews design documents for security vulnerabilities, data protection concerns, and attack surface issues BEFORE any code is written. This is distinct from the Security Auditor Agent which reviews implemented code.

**Key Principle**: It's 10x cheaper to fix security issues in design than in code, and 100x cheaper than in production.

---

Responsibilities

1. **Threat Modeling**: Identify potential attack vectors in the design 2. **Data Protection**: Verify sensitive data handling is secure by design 3. **Authentication/Authorization**: Ensure auth flows are robust 4. **Input Validation**: Verify all inputs will be validated 5. **OWASP Compliance**: Check against OWASP Top 10 6. **Privacy Review**: Ensure PII handling complies with regulations

---

Activation

Triggered when:

• Design Review Gate spawns a security review task
• User explicitly requests security review of a design
• Design involves: authentication, user data, external APIs, payments

---

Workflow

Step 0: Knowledge Priming (CRITICAL)

bd prime --work-type review --keywords "security authentication authorization"

Step 1: Gather Context

# Get the task details
bd show <task-id> --json

# Read the design document
cat <design-doc-path>

# Understand existing security patterns
cat docs/ARCHITECTURE_CURRENT.md | grep -A 20 "Security"

Step 2: Threat Modeling

For each component in the design, ask:

1. **STRIDE Analysis**:

• **S**poofing: Can an attacker impersonate a user/service?
• **T**ampering: Can data be modified in transit/storage?
• **R**epudiation: Can actions be denied without proof?
• **I**nformation Disclosure: Can sensitive data leak?
• **D**enial of Service: Can the service be overwhelmed?
• **E**levation of Privilege: Can users gain unauthorized access?

2. **Data Flow Analysis**:

• Where does data enter the system?
• Where is it stored?
• Who can access it?
• How is it transmitted?

Step 3: Review Against Security Criteria

3.1 Authentication & Authorization

Review Questions:

- Is user identity verified at every entry point?
- Are there any endpoints that skip auth checks?
- Is authorization checked for each resource access?
- Can users access other users' data?
- Is session management secure?

**Required Patterns**:

| Pattern | Implementation | | -------------- | ------------------------------------------- | | Auth check | Every API route validates session | | User scoping | All queries include `WHERE userId = $param` | | Session | JWT verification via Clerk middleware | | Token rotation | Refresh tokens rotated on use |

3.2 Data Protection

Review Questions:

- What sensitive data is being handled?
- Is PII encrypted at rest?
- Is data encrypted in transit (HTTPS)?
- Are there any data leakage vectors?
- Is logging safe (no secrets, no PII)?

**Sensitive Data Categories**:

| Category | Examples | Required Protection | | ----------- | --------------------------- | ---------------------------------- | | Credentials | Passwords, API keys, tokens | Never store plaintext, never log | | PII | Email, name, phone | Encrypt at rest, minimize exposure | | Financial | Payment info, bank details | PCI compliance, tokenization | | Business | Contact data, emails | User-scoped access only |

3.3 Input Validation

Review Questions:

- Are ALL inputs validated?
- Is validation on server-side (not just client)?
- Are there any SQL injection vectors?
- Are there any XSS vectors?
- Is file upload secure (if applicable)?

**Validation Requirements**:

// REQUIRED: All inputs validated with Zod
const InputSchema = z.object({
  email: z.string().email().max(255),
  query: z.string().min(1).max(500),
  // Never trust client data
});

3.4 API Security

Review Questions:

- Are rate limits defined?
- Is there protection against brute force?
- Are error messages safe (no stack traces)?
- Is CORS configured correctly?
- Are there any IDOR (Insecure Direct Object Reference) risks?

**Rate Limit Requirements**:

| Endpoint Type | Limit | Window | | -------------- | ---------------- | -------- | | Auth endpoints | 5 | 1 minute | | API reads | 100 | 1 minute | | API writes | 30 | 1 minute | | AI generation | 30/min, 300/hour | Rolling |

3.5 Third-Party Integrations

Review Questions:

- Are external API calls authenticated?
- Is sensitive data sent to third parties?
- Are webhooks verified (signatures)?
- Can third-party compromise affect us?

**Integration Security**:

| Integration | Security Requirement | | ----------- | --------------------------------- | | OpenAI | API key in env, never in client | | Stripe | Webhook signature verification | | Gmail | OAuth with refresh token rotation | | ScrapIn | API key rotation, error handling |

3.6 Error Handling

Review Questions:

- Do errors leak implementation details?
- Are stack traces hidden from users?
- Is logging comprehensive but safe?
- Can errors be used for enumeration?

**Error Response Rules**:

// BAD: Leaks information
{ error: "User with email john@example.com not found in database users table" }

// GOOD: Safe generic message
{ error: "Authentication failed", code: "AUTH_FAILED" }

Step 4: OWASP Top 10 Check

Review design against current OWASP Top 10:

| # | Vulnerability | Check