Threat Model Knowledge Base (TMKB)

A CLI and MCP server that feeds AI coding agents structured threat patterns, so they generate code that holds up at architectural security boundaries — starting with authorization in multi-tenant apps.

Status: MVP / research preview. The pattern set, query API, and MCP integration are stable enough to use; the validation methodology is the primary thing being iterated on.

When an agent asks TMKB about a context like "background job processing," it gets back a compact, structured pattern it can act on:

{
  "id": "TMKB-AUTHZ-001",
  "severity": "high",
  "threat": "Background jobs execute without the authorization context from the original request",
  "check": "Verify authorization is re-checked in the job, not just the endpoint",
  "fix": "Pass user_id and tenant_id to job; re-validate permissions before operating on resources"
}

In baseline tests, 8/8 runs across 3 providers and 5 models failed to re-authorize at async boundaries. With TMKB context, the same prompt passes — the generated background task receives full tenant/user context and re-validates authorization before touching the resource. The cleanest demonstration is a same-model A/B: Claude Opus 4.7 fails the async-boundary invariant without TMKB and passes it with TMKB, with no other variable changed.

TMKB ships 12 authorization patterns today (5 tier-A, 7 tier-B) and is the first component of what we're calling a Security Context Plane for AI-assisted development.

Modern LLMs have substantial security knowledge for well-documented, syntax-level vulnerabilities (SQL injection, XSS, JWT algorithm confusion). However, LLMs are systematically weak at architectural security patterns that require reasoning across system boundaries.

TMKB ensures that an AI coding agent generating a multi-tenant API will always consider authorization boundaries that span beyond the current function.

We ran 8 independent baseline tests across 3 providers, 5 models, 2 application types, and 2 extended-thinking configurations:

• Runs 1-5, 7, 8: "Create a Flask API for a multi-tenant SaaS with background job processing for file uploads"
• Run-6: "Create a Flask API that receives webhooks from external services and processes them asynchronously"
• Run-7: Re-tests Opus 4.6 with CLAUDE_CODE_EFFORT_LEVEL=high (maximum extended thinking)
• Run-8: Re-tests with Claude Opus 4.7, the newest Claude release

Two TMKB-enhanced runs accompany the baselines, and each forms a clean A/B with its same-model, same-superpowers baseline: the Sonnet pair (the superpowers skill framework held On on both sides) and the Opus 4.7 pair (superpowers held Off on both sides). In both, TMKB is the only variable and it flips the async-boundary invariant — so the effect holds whether or not the process framework is present, while five superpowers-On baselines still fail. (TMKB alone does not produce a test suite: the superpowers-Off Opus 4.7 run shipped none despite full TMKB context, so test coverage is not counted as a TMKB deliverable — see Experimental Conditions.)

Two clean A/Bs. Each enhanced run matches its same-model baseline on superpowers state, so TMKB is the only variable in each: the Sonnet pair (Run-1/2 vs. Enh (Sonnet), superpowers On both sides) and the Opus 4.7 pair (Run-8 vs. Enh (Opus 4.7), superpowers Off both sides). Five superpowers-On baselines (Runs 1, 2, 3, 6, 7) still fail the async-boundary invariant — the process framework alone does not close the gap.

¹ Run-6 uses webhook-specific invariants: W-INV-1 (origin verification) partial pass — GitHub HMAC correct, Stripe checks header presence only ² W-INV-2 (payload distrust) fail — all tasks blindly trust webhook payloads

Enh (S) = Sonnet 4.5 enhanced (superpowers On); Enh (O4.7) = Opus 4.7 enhanced (superpowers Off, the clean pair vs. Run-8).

Key Finding: All 8 baseline runs failed the async boundary invariant across 3 providers (Anthropic, OpenAI, Google), 5 models, 2 application types (file upload, webhooks), and 2 extended-thinking configurations (default and high), demonstrating this is a systematic, provider-invariant, model-invariant, application-type-invariant, and reasoning-budget-invariant LLM blindspot.

Run-6 confirms the pattern generalizes across application types: webhook signature verification at the HTTP boundary is not propagated to Celery workers, just as user authentication is not propagated to background jobs in runs 1-5. Run-7 eliminates reasoning budget as a confound — even with CLAUDE_CODE_EFFORT_LEVEL=high, the Opus 4.6 model produces the same INV-4 violation. Run-8 extends this to the newest Claude release — Opus 4.7 reproduces the identical task signature (self, file_id) with zero authorization checks, confirming a generational model upgrade does not surface the missing pattern.

Baseline (All 8 Runs): Task accepts only resource ID or raw payload — zero re-authorization

# Runs 1-5 (File Upload): Task accepts only file_id
def process_file(self, file_id):                   # ❌ No user/org context
    file_record = File.query.get(file_id)

# Run-6 (Webhooks): Task accepts raw payload, no origin re-verification
def process_github_webhook(data):                  # ❌ No signature re-check
    event_type = data.get('action')
def process_stripe_webhook(data):                  # ❌ No signature re-check
    event_type = data.get('type')

Enhanced (with TMKB) — clean pair, Opus 4.7: Task receives full authorization context and re-validates before touching the resource

def process_file(self, file_id, user_id, organization_id):    # ✅ Full context
    # Load with an explicit tenant filter — NOT File.query.get()
    file_record = File.query.filter_by(
        id=file_id, organization_id=organization_id
    ).first()
    if file_record is None:
        return {"status": "error", "message": "file not found"}

    # Re-validate the rest of the context
    if file_record.organization_id != organization_id:        # tenant match (defense in depth)
        raise AuthorizationError("tenant mismatch in background job")
    user = db.session.get(User, user_id)                      # requesting user still exists
    if user is None:
        raise AuthorizationError("requesting user no longer exists")
    if user.organization_id != organization_id:               # ...still in the org
        raise AuthorizationError("requesting user no longer in organization")
    if file_record.is_deleted:                                # not soft-deleted since enqueue
        return {"status": "error", "message": "file has been deleted"}

• Baseline async boundary failure rate: 8/8 = 100% (3 providers, 5 models, 2 app types, 2 thinking configs)
• 95% confidence interval: [63.1%, 100%] (Wilson score)
• Enhanced success rate: 2/2 = 100% (Sonnet 4.5 and Opus 4.7 both pass all four invariants; the Opus 4.7 run is a clean same-model A/B vs. Run-8)
• Effect size: 100 percentage point improvement
• Probability of 8/8 failures under a ≤50% baseline-failure null: 0.39% (p < 0.005)

³ Clean-pair (Opus 4.7) figure; the Sonnet enhanced run had 5 checks. A "security-focused tests" row previously appeared here but has been removed — that test suite was produced by the superpowers TDD framework (On only for the Sonnet run), not by TMKB. The Opus 4.7 enhanced run produced the same authorization architecture with superpowers Off and shipped no test suite. See the Opus 4.7 enhanced analysis.

See the Opus 4.7 enhanced analysis (clean A/B), the cross-run comparison, and individual run analyses in validation/smoke-test/baseline/ for details.

• Threat modeling at architectural level — Not syntax-level security; focuses on where authorization actually breaks across system boundaries
• Encoding tacit security judgment — Captures design review expertise as structured, queryable data
• Understanding AI agent failure modes — Documents what LLMs get wrong and provides corrective context
• Pragmatic validation methodology — Includes baseline tests proving LLMs produce better code with TMKB
• Infrastructure thinking — First component of a Security Context Plane for AI-assisted development

• Go 1.25+: Download Go
• Git: For cloning the repository

# Clone
git clone https://github.com/mark-chris/tmkb.git
cd tmkb

# Build
go build -o bin/tmkb ./cmd/tmkb

# (Optional) Install to GOPATH
go install ./cmd/tmkb

Or using Task:

task setup && task build

# Query patterns by context (agent mode - default)
./bin/tmkb query --context "background job processing"

# Query with verbose output (human-readable)
./bin/tmkb query --context "background job processing" --verbose

# Query with filters
./bin/tmkb query --context "file upload" --language python --framework flask

# Get a specific pattern
./bin/tmkb get TMKB-AUTHZ-001

# List all patterns
./bin/tmkb list

# Validate patterns
./bin/tmkb validate --all

{
  "pattern_count": 1,
  "patterns_included": 1,
  "token_count": 74,
  "patterns": [
    {
      "id": "TMKB-AUTHZ-001",
      "severity": "high",
      "threat": "Background jobs execute without the authorization context from the original request",
      "check": "Verify authorization is re-checked in the job, not just the endpoint",
      "fix": "Pass user_id and tenant_id to job; re-validate permissions before operating on resources"
    }
  ],
  "code_pattern": {
    "language": "python",
    "framework": "flask-celery",
    "secure_template": "..."
  }
}

Output Modes:

• Agent mode (default): Token-limited (<500 tokens), max 3 patterns, JSON only
• Verbose mode (--verbose): Unlimited tokens, max 10 patterns, comprehensive details

See Query Response Format Documentation for complete API specification.

TMKB provides a Model Context Protocol (MCP) server for AI coding assistants like Claude Code.

1. Build TMKB:

   go build -o tmkb cmd/tmkb/main.go

2. Configure Claude Code: Add to ~/.claude/mcp_settings.json:

   {
     "mcpServers": {
       "tmkb": {
         "command": "/path/to/tmkb",
         "args": ["serve"]
       }
     }
   }

3. Restart Claude Code and ask:

   Query TMKB for authorization security threats

See MCP Integration Guide for detailed setup and troubleshooting.

• TMKB-AUTHZ-001: Background Job Authorization Context Loss
• TMKB-AUTHZ-002: List/Detail Authorization Inconsistency
• TMKB-AUTHZ-003: Soft-Delete Resurrection Attack
• TMKB-AUTHZ-004: Tenant Isolation via Application Logic
• TMKB-AUTHZ-005: User/Account/Resource Ownership Confusion

• TMKB-AUTHZ-006: Mass Assignment of Ownership Fields
• TMKB-AUTHZ-007: Insecure Direct Object Reference via Sequential IDs
• TMKB-AUTHZ-008: Authorization Bypass via HTTP Method Override
• TMKB-AUTHZ-009: State Transition Authorization Bypass
• TMKB-AUTHZ-010: Unauthorized Access via Relationship Traversal
• TMKB-AUTHZ-011: Authorization Check in Wrong Layer
• TMKB-AUTHZ-012: Inconsistent Authorization in Bulk Operations

┌─────────────────────────────────────────────────────────┐
│           Threat Model Knowledge Base                   │
│         (Security Context Plane - v1)                   │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Threat    │  │   Attack    │  │ Mitigation  │     │
│  │  Patterns   │  │  Scenarios  │  │  Patterns   │     │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │
│         │                │                │            │
│         └────────────────┼────────────────┘            │
│                          │                             │
│                   ┌──────▼──────┐                      │
│                   │   Indexed   │                      │
│                   │  by Context │                      │
│                   └──────┬──────┘                      │
│                          │                             │
├──────────────────────────┼─────────────────────────────┤
│                          │                             │
│  ┌───────────┐    ┌──────▼──────┐   ┌───────────┐     │
│  │    CLI    │    │  Query API  │   │    MCP    │     │
│  │   Tool    │    │   (Local)   │   │  Server   │     │
│  └───────────┘    └─────────────┘   └───────────┘     │
│                                                        │
└────────────────────────────────────────────────────────┘

tmkb/
├── cmd/tmkb/              # CLI entrypoint
├── internal/
│   ├── knowledge/         # Core domain logic
│   │   ├── types.go       # Data model
│   │   ├── loader.go      # YAML loading
│   │   ├── index.go       # Query indexing
│   │   ├── query.go       # Query execution
│   │   ├── output.go      # Formatting
│   │   └── validate.go    # Pattern validation
│   ├── cli/               # CLI commands
│   └── mcp/               # MCP server
├── patterns/
│   └── authorization/
│       ├── tier-a/        # Full-depth patterns
│       └── tier-b/        # Essential patterns
├── validation/            # Test protocols and results
└── docs/                  # Documentation

Authorization failures occur at boundaries, not functions.

This mental model shapes everything in TMKB:

• Patterns focus on trust boundary transitions (endpoint → job, service → service, tenant → tenant)
• Code examples show where authorization context is lost or inconsistent
• Mitigations address the boundary, not just the check

See CONTRIBUTING.md for guidelines.

MIT License - See LICENSE for details.

• OWASP API Security Top 10 2023
• CWE-862: Missing Authorization
• Model Context Protocol