feedback loop: as new threats emerge, the wiki updates, and the AI review contract automatically adapts without requiring prompt rewrites.

Core Solution

Implementing a threat-driven AI review pipeline requires five sequential phases. Each phase builds context for the next, ensuring the model operates within strict architectural and threat boundaries.

Phase 1: Architecture Discovery & Scope Definition

Before any review begins, establish a high-level map of the application. Identify core components, data stores, message brokers, caching layers, and external integrations. For a typical multi-tenant SaaS backend, this includes the web framework, relational database, async task queues, cache layers, and API gateways. This step is critical because security boundaries are defined by architecture, not syntax. A misconfigured message broker, for example, creates a completely different threat surface than a misconfigured ORM query.

Phase 2: Threat Model Generation

Map the architecture to the two vulnerability categories. For business logic, identify where authentication, authorization, tenant isolation, and CSRF protections must exist. For source-sink patterns, identify data entry points and dangerous execution boundaries. The output is a prioritized threat list scoped to the actual deployment topology.

Phase 3: Security Wiki Construction

Translate the threat model into a living reference document. Each threat entry must include:

• A clear description of the vulnerability
• Expected secure implementation patterns
• Code examples demonstrating correct mitigation
• A relevance trigger defining when this threat applies to a given change set

The wiki serves as the execution contract for both human reviewers and AI. It eliminates ambiguity by standardizing what "secure" means in the context of the specific application.

Phase 4: AI Skill Configuration

Structure the AI review process as a deterministic pipeline rather than an open-ended prompt. The skill should enforce a strict sequence: ingest the diff, cross-reference the security wiki, filter for relevant threats based on the relevance triggers, validate mitigations against the diff, and output a structured summary. This prevents scope creep and ensures consistent output formatting.

Phase 5: Execution & Validation

Run the skill against the target pull request. The model evaluates only the threats marked as relevant, verifies implementation against the wiki standards, and flags deviations. Human engineers then validate the output, focusing on architectural edge cases and business rule nuances that AI may misinterpret.

New Code Example: Unsafe Deserialization Boundary

The following TypeScript example demonstrates how to safely handle serialized payloads in a worker environment, contrasting with unsafe deserialization patterns. Note the explicit type validation and schema enforcement before any parsing occurs.

import { z } from 'zod';

const TaskPayloadSchema = z.object({
  taskId: z.string().uuid(),
  action: z.enum(['process_report', 'sync_inventory', 'notify_user']),
  metadata: z.record(z.string(), z.unknown()),
  timestamp: z.number().int().positive()
});

function safelyDeserializePayload(rawBuffer: Buffer): z.infer<typeof TaskPayloadSchema> {
  const parsed = JSON.parse(rawBuffer.toString('utf-8'));
  const validationResult = TaskPayloadSchema.safeParse(parsed);
  
  if (!validationResult.success) {
    throw new Error('Invalid task payload structure');
  }
  
  return validationResult.data;
}

// Usage in worker
async function executeTask(rawPayload: Buffer) {
  try {
    const task = safelyDeserializePayload(rawPayload);
    await processTaskLogic(task);
  } catch (error) {
    logger.warn('Rejected malformed task payload', { error: error.message });
  }
}

This approach replaces executable deserialization with strict schema validation. Unlike Python's pickle, which reconstructs objects and can trigger arbitrary code execution during reconstruction, JSON parsing combined with runtime schema enforcement guarantees that only expected data shapes enter the execution path. The same principle applies to any serialization boundary: never trust the wire format, always validate against a contract before execution.

Architecture Rationale

• Threat model first: AI lacks inherent security intuition. Providing a bounded threat list prevents hallucination and focuses compute on relevant attack surfaces.
• Wiki-driven standards: Security expectations must be codified, not implied. A wiki ensures consistency across teams and PRs.
• Relevance filtering: Not every threat applies to every change. Filtering reduces noise and accelerates review cycles.
• Deterministic pipeline: Structured steps replace open-ended prompting, making outputs reproducible and auditable.

Pitfall Guide

1. Raw Diff Feeding

Explanation: Passing unstructured pull request diffs directly to AI without architectural context or threat boundaries. Fix: Always prepend architecture discovery and threat model generation. Feed the model a scoped context packet before the diff.

2. Ignoring Data Flow Boundaries

Explanation: Focusing only on synchronous request/response paths while missing async queues, webhooks, or background workers where deserialization or command execution occurs. Fix: Map all data ingress points, including message brokers, event streams, and scheduled jobs. Treat each as a potential source-sink boundary.

3. Overlooking Tenant Context

Explanation: Reviewing authorization checks in isolation without verifying multi-tenant isolation guarantees. A user may be authenticated and authorized, but still able to cross tenant boundaries if resource queries lack tenant scoping. Fix: Enforce tenant ID propagation through all data access layers. Verify that every query, cache key, and message includes tenant context.

4. Treating AI Output as Verdict

Explanation: Accepting AI-generated findings without architectural validation. Models can misinterpret business rules, miss edge cases, or flag safe patterns as vulnerable. Fix: Implement a human-in-the-loop validation step. Use AI for coverage and consistency, not final judgment.

5. Static Wiki Drift

Explanation: Security wikis become outdated as the codebase evolves. New frameworks, libraries, or architectural shifts invalidate old guidelines. Fix: Version the wiki alongside the codebase. Automate wiki updates during major dependency upgrades or architectural migrations. Review wiki relevance quarterly.

6. Missing Deserialization Trust Boundaries

Explanation: Assuming that internal services or message queues are inherently safe. Attackers can exploit misconfigured brokers, default credentials, or network exposure to inject malicious payloads directly into workers. Fix: Never trust internal message formats. Apply schema validation, signature verification, and network segmentation to all async boundaries. Rotate default credentials immediately.

7. Prompt Injection in Reviews

Explanation: Malicious or poorly formatted PR descriptions/comments can influence AI review behavior, causing it to skip checks or misclassify severity. Fix: Sanitize review inputs. Strip PR descriptions of executable instructions. Use system-level prompts that enforce strict evaluation criteria regardless of user-provided text.

Production Bundle

Action Checklist

• Architecture Discovery: Document core components, data stores, message brokers, and external integrations before starting any review.
• Threat Model Generation: Map vulnerabilities to business logic and source-sink categories based on actual deployment topology.
• Security Wiki Creation: Codify mitigation standards with code examples and relevance triggers for each identified threat.
• AI Skill Configuration: Structure the review pipeline as a deterministic sequence: ingest, cross-reference, filter, validate, summarize.
• Relevance Filtering: Apply trigger-based filtering to ensure only applicable threats are evaluated per PR.
• Human Validation: Implement a mandatory review step for AI output, focusing on architectural edge cases and business rule nuances.
• Wiki Versioning: Tie security guidelines to codebase versions and automate updates during major architectural shifts.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Small PR, single endpoint change	AI + Threat Model Framework	Fast, consistent, covers auth/authz/CSRF checks automatically	Low compute, high ROI
Major architectural refactor	Manual Review + AI Assistance	Complex data flow changes require human architectural validation	Higher engineering time, lower risk
Legacy codebase with no docs	Architecture Discovery + Threat Model First	AI cannot operate without baseline context; manual mapping required	High initial investment, long-term savings
Async/queue-heavy system	Source-Sink Focus + Deserialization Validation	Message brokers introduce unique trust boundaries and serialization risks	Moderate compute, critical risk reduction
Multi-tenant SaaS	Tenant Isolation + RBAC Verification	Business logic flaws dominate; static tools miss cross-tenant data leaks	High accuracy, prevents data breach costs

Configuration Template

# security-wiki.yaml
version: "2.1"
last_updated: "2024-06-15"

threats:
  - id: AUTH-01
    category: business_logic
    name: Missing Authentication Enforcement
    description: All protected routes must verify user identity before processing.
    secure_pattern: "Middleware checks session/JWT validity before handler execution."
    relevance_trigger: "PR modifies route definitions or removes middleware."
    
  - id: AUTHZ-02
    category: business_logic
    name: Tenant Isolation Failure
    description: Multi-tenant queries must scope data access by tenant identifier.
    secure_pattern: "Repository methods inject tenant_id into WHERE clauses or use tenant-scoped ORM contexts."
    relevance_trigger: "PR introduces new database queries or modifies data access layers."
    
  - id: SRC-03
    category: source_sink
    name: Unsafe Deserialization
    description: Worker payloads must be validated against strict schemas before parsing.
    secure_pattern: "JSON parsing + runtime schema validation (e.g., Zod, Pydantic). No executable deserialization."
    relevance_trigger: "PR modifies message consumer logic or serialization formats."

ai_review_skill:
  pipeline:
    - step: ingest_diff
    - step: load_wiki
    - step: filter_relevance
    - step: validate_mitigations
    - step: generate_summary
  output_format: markdown_table
  max_false_positive_threshold: 0.15

Quick Start Guide

1. Initialize Context: Run an architecture discovery prompt against the target repository. Extract component list, data flows, and external integrations.
2. Generate Threat Model: Feed the architecture summary into a threat modeling prompt. Request categorization into business logic and source-sink vulnerabilities.
3. Build Security Wiki: Convert the threat model into a structured YAML/JSON reference with mitigation patterns and relevance triggers.
4. Configure AI Skill: Set up a deterministic review pipeline that ingests the PR diff, cross-references the wiki, filters by relevance, and outputs a validation table.
5. Execute & Validate: Run the skill against the target pull request. Review the output, verify architectural assumptions, and merge only after human validation.

This framework transforms AI from a speculative code scanner into a repeatable security execution engine. By anchoring reviews to threat boundaries, codifying standards, and enforcing deterministic pipelines, teams achieve consistent coverage, reduce false positives, and maintain audit-ready documentation without sacrificing delivery velocity.