/security-threat-model

name: security-threat-model
description: "Security threat model: scan toolkit for attack surface, supply-chain risks."
agent: python-general-engineer
effort: high
user-invocable: false
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
routing:
  triggers:
    - threat model
    - security audit
    - supply chain scan
    - deny list
    - learning db sanitize
    - security posture
    - injection scan
    - surface scan
    - audit hooks
    - audit skills
  pairs_with:
    - python-general-engineer
  complexity: Complex
  category: security

Security Threat Model Skill

Overview

This skill executes a structured, phase-gated security threat model workflow that scans the toolkit installation for attack surface exposure, supply-chain injection patterns, and learning DB contamination. It follows the toolkit's four-layer architecture: deterministic Python scripts perform all checks and produce JSON artifacts; Phase 5 (synthesis only) is the LLM step. Each phase gates on artifact validation before proceeding.

Outputs are saved to `security/` with a shared `run_id` for correlation across phases. Phase 5 produces an actionable threat model document.

---

Instructions

Phase 1: SURFACE SCAN

**Goal**: Enumerate the active attack surface of the current installation.

Create the `security/` output directory and run the surface scan script:

mkdir -p security
python3 scripts/scan-threat-surface.py --output security/surface-report.json

This script enumerates:

• Registered hooks (from `~/.claude/settings.json`) with file paths and event types
• Installed MCP servers (from `~/.claude/mcp.json` and `.mcp.json`)
• Installed skills (from `skills/`) with `allowed-tools` entries
• Any file in `hooks/`, `skills/`, or `agents/` containing `ANTHROPIC_BASE_URL`

**Validate output**:

python3 -c "import json; d=json.load(open('security/surface-report.json')); print('hooks:', len(d.get('hooks',[])), '| skills:', len(d.get('skills',[])), '| mcp_servers:', len(d.get('mcp_servers',[])))"

**Gate (ARTIFACT VALIDATION)**: `security/surface-report.json` must exist, parse as valid JSON, and contain `hooks`, `skills`, and `mcp_servers` keys. A missing directory is handled gracefully with empty arrays. All artifacts are written to `security/` before gating. Do not proceed to Phase 2 until this gate passes.

---

Phase 2: DENY-LIST GENERATION

**Goal**: Produce a concrete deny-list config derived from Phase 1 findings.

Generate the deny-list from the surface report:

python3 scripts/generate-deny-list.py \
    --surface security/surface-report.json \
    --output security/deny-list.json

The script applies these mappings from surface findings to deny rules:

• Hook uses `curl` or `wget` → append `"Bash(curl *)"` and `"Bash(wget *)"`
• Hook uses `ssh` or `scp` → append `"Bash(ssh *)"` and `"Bash(scp *)"`
• Skill `allowed-tools` contains unscoped `Read(*)` or `Write(*)` → add path-scoped deny entries
• Any file contains `ANTHROPIC_BASE_URL` override → append `"Bash(* ANTHROPIC_BASE_URL=*)"`

Always includes static baseline deny rules for credentials and privileged operations:

["Read(~/.ssh/**)", "Read(~/.aws/**)", "Read(**/.env*)",
 "Write(~/.ssh/**)", "Write(~/.aws/**)",
 "Bash(curl * | bash)", "Bash(ssh *)", "Bash(scp *)", "Bash(nc *)",
 "Bash(* ANTHROPIC_BASE_URL=*)"]

**Display deny-list for human review**:

python3 -c "
import json
d = json.load(open('security/deny-list.json'))
print('Deny-list entries to add to settings.json:')
for rule in d['permissions']['deny']:
    print(' ', rule)
print()
print('Review security/deny-list.json before merging.')
"

**Gate (HUMAN APPROVAL REQUIRED)**: The deny-list is produced for human review only — it is never merged automatically. Display the diff and block until the operator confirms review. This gate is the highest-ROI control in the workflow. In `--ci-mode`, skip this gate and proceed to Phase 3. Do not proceed without explicit acknowledgment.

---

Phase 3: SUPPLY-CHAIN AUDIT

**Goal**: Scan all installed hooks, skills, and agents for injection patterns and hidden characters.

Run the supply-chain audit:

python3 scripts/scan-supply-chain.py \
    --scan-dirs hooks/ skills/ agents/ \
    --output security/supply-chain-findings.json

Detection patterns (full regex details in `scripts/scan-supply-chain.py` source): | Pattern | Severity | |---------|----------| | Zero-width + bidi Unicode characters | CRITICAL | | HTML comments and hidden payload blocks | CRITICAL | | `ANTHROPIC_BASE_URL` override in any file | CRITICAL | | Instruction-override and role-hijacking phrases | CRITICAL | | Outbound network commands in hooks/skills | WARNING | | `enableAllProjectMcpServers` setting | WARNING | | Broad permission grants without path scoping | WARNING |

**Check for CRITICAL findings**:

python3 -c "
import json, sys
d = json.load(open('security/supply-chain-findings.json'))
crits = [f for f in d.get('findings', []) if f.get('severity') == 'CRITICAL']
warns = [f for f in d.get('findings', []) if f.get('severity') == 'WARNING']
print(f'CRITICAL: {len(crits)}, WARNING: {len(warns)}')
if crits:
    for c in crits:
        print(f'  CRITICAL: {c[\"file\"]}:{c.get(\"line\",\"?\")} -- {c[\"pattern\"]}')
    sys.exit(1)
"

**Gate (BLOCKING CRITICAL FINDINGS)**: Any CRITICAL finding halts forward progress. All CRITICAL findings must be remediated or explicitly acknowledged before Phase 4 can start. This includes zero-width Unicode, ANTHROPIC_BASE_URL overrides, hidden payloads, and instruction-override phrases. WARNING findings are logged but do not block. Log warnings in the threat model under "Gaps and Recommended Next Controls" with acceptance rationale.

---

Phase 4: LEARNING DB SANITIZATION

**Goal**: Inspect the learning DB for entries that may contain injected content from external sources.

Run the sanitization check in dry-run mode (never mutates