Skip to content

Security Overview — V025-claude-toolkit

Comprehensive security architecture for the VisiTrans Claude Toolkit, covering threat model, attack surfaces, defense layers, and all active controls.

1. Threat Model

1.1 Supply Chain Attacks

Threat: Compromised npm packages or MCP server binaries execute in the agent context with full user permissions.

Attack vectors: - Typosquatted npm package replaces legitimate MCP server - Maintainer account compromise pushes malicious update - Post-install scripts execute arbitrary code during npm install

Controls: - MCP packages pinned to exact versions in setup.sh (SPEC-103) - Integrity hashes verified via setup.sh --verify against configs/security/mcp-package-hashes.yaml - npm ci --ignore-scripts as default install mode - npm audit --audit-level=high required after install

1.2 Prompt Injection

Threat: Malicious content in articles, proposals, or SKILL.md files manipulates agent behavior.

Attack vectors: - Crafted markdown article in intake/inbox/ injects instructions into qualification workflow - Malicious SKILL.md with hidden prompt injection in description or execution steps - External MCP tool results containing injection attempts

Controls: - Intake pipeline validates YAML frontmatter structure before processing (SPEC-103) - Slug generation strips path traversal and shell-dangerous characters - target_skill validated against known skill manifest - SKILL.md frontmatter audited during setup.sh installation with tool declarations logged - System prompt instructs flagging suspected injection in tool results

1.3 Data Exfiltration

Threat: Sensitive data (credentials, internal paths, business logic) leaks to external services via Open Brain capture_thought or other MCP tools.

Attack vectors: - Agent captures thought containing API keys or tokens - Absolute file paths with usernames flow to external services - Environment variable values included in captured thoughts

Controls: - CLAUDE.md Section 10a mandates sanitization before all capture_thought calls (SPEC-103) - Secret-scanner hook (PreToolUse) blocks writes containing credential patterns - Security-lint hook (PostToolUse) scans all file writes - Constitution Principle I enforces sanitization as a constitutional requirement

1.4 Privilege Escalation

Threat: Read-only agents dispatch write-capable sub-agents, or skills execute with more permissions than intended.

Attack vectors: - Research agent spawns general-purpose sub-agent with Bash/Edit/Write access - Compromised skill leverages context: fork to bypass permission checks - Hook script with elevated permissions modifies protected files

Controls: - Skills declare allowed-tools in SKILL.md frontmatter (convention, not enforced by runtime) - setup.sh logs and warns about skills with write-capable tool declarations (SPEC-103) - Constitution Principle IV requires explicit tool declarations for all agents - Enterprise setting allowManagedHooksOnly: true restricts hook sources

2. Attack Surface Map

2.1 MCP Servers

Server Transport Risk Level Controls
azure-devops stdio/npx High Version-pinned @2.5.0, integrity hash verified
taskmaster-ai stdio/npx High Version-pinned @0.43.0, integrity hash verified
github HTTP/OAuth Medium OAuth authentication, no local code execution
plugin:pw Plugin-provided Medium Controlled by compound-engineering plugin
plugin:context7 Plugin-provided Low Documentation lookup only

2.2 Intake Pipeline

Entry Point Risk Level Controls
intake/inbox/ files Medium YAML validation, slug sanitization, path traversal blocking
intake/pending/from-research/ proposals Medium Frontmatter structure validation, target_skill manifest check
intake/pending/from-projects/ proposals Low From registered projects only

2.3 Agent Isolation

Component Isolation Level Gap
Main agent Full user permissions No sandbox — inherits shell environment
Sub-agents (fork) Process isolation Can request tools beyond parent's allowlist
Review agents Read-only by convention Convention-enforced, not runtime-enforced

2.4 Git Workflow

Control Enforcement
No direct commits to main CLAUDE.md rule + pre-commit hook
Feature branch required CLAUDE.md Part 3
Review gate before merge Constitution Principle I
No force push to main CLAUDE.md Part 3

2.5 Open Brain

Data Flow Risk Control
capture_thought Credential leakage Sanitization rule (CLAUDE.md 10a)
ingest_content Content injection Not currently validated
search_thoughts Information disclosure Scoped to user's own data

2.6 Hook System

Hook Type Risk Control
secret-scanner PreToolUse Low Blocks credential writes
security-lint PostToolUse Low Scans file writes
pre-commit Git Low Runs before commits
Trusted hook checksums configs/security/trusted-hooks.yaml Medium Verified by /repo-audit

3. Defense Layers

The toolkit employs defense in depth with four layers:

Layer 1: Hooks (Automatic, Real-time)
├── secret-scanner — blocks credential writes before they happen
├── security-lint — scans all file modifications after write
└── pre-commit — validates staged changes before commit

Layer 2: Constitution (Declarative, Session-scoped)
├── Principle I — security requirements binding on all agents
├── CLAUDE.md — engineering standards enforced every response
└── SKILL.md frontmatter — tool allowlists per skill

Layer 3: Review (Multi-agent, Pre-merge)
├── security-sentinel — OWASP compliance review
├── implementation-orchestrator — 6 parallel code reviewers
└── .review-gate.md — evidence of completed review

Layer 4: Audit (Periodic, Post-deployment)
├── /repo-audit — integrity scan (hooks, partitions, LFS)
├── /repo-health — quick governance health check
├── setup.sh --verify — MCP package integrity verification
└── npm audit — dependency vulnerability scanning

4. Security Controls Matrix

Control Category Enforcement Automated Added By
Secret scanner hook Data exfiltration Blocks write Yes Toolkit setup
Security lint hook Code quality Warns on write Yes Toolkit setup
MCP version pinning Supply chain Blocks install Yes SPEC-103
MCP hash verification Supply chain Warns on verify Yes SPEC-103
npm --ignore-scripts Supply chain Convention No SPEC-103
npm audit Supply chain Convention No SPEC-103
SKILL.md tool audit Privilege escalation Warns on install Yes SPEC-103
Intake YAML validation Prompt injection Rejects invalid Yes SPEC-103
Slug sanitization Path traversal Strips chars Yes SPEC-103
capture_thought sanitization Data exfiltration Convention No SPEC-103
Review gate enforcement Quality Blocks merge Yes SPEC-002
Branch protection Code integrity Convention No SPEC-103
Constitution compliance All Session-scoped No Constitution v1.1
Repo audit Integrity Manual trigger Yes Setup
Trusted hook checksums Tamper detection Manual trigger Yes Setup

5. Residual Risks (US8)

5.1 Hook Execution Not Sandboxed

Risk: Hook scripts execute with full user permissions. A compromised hook can read/write any file the user can access.

Mitigation: allowManagedHooksOnly: true in enterprise settings restricts hook sources to managed configurations only. Trusted hook checksums in configs/security/trusted-hooks.yaml detect tampered hooks. No runtime sandbox exists.

Recommendation: Enable allowManagedHooksOnly: true for all deployments. Run /repo-audit weekly to verify hook integrity.

5.2 Sub-Agent Privilege Escalation

Risk: A read-only review agent can dispatch a general-purpose sub-agent with full tool access (Bash, Edit, Write). The runtime does not enforce the parent agent's tool restrictions on child agents.

Mitigation: Convention-based — orchestrators should declare maximum sub-agent tool allowlists in their agent definitions. Constitution Principle IV requires explicit tool declarations.

Recommendation: Orchestrators should include a max_subagent_tools declaration in their agent frontmatter. Until runtime enforcement exists, rely on code review to catch violations.

5.3 No Automated Hook Re-verification

Risk: Hooks modified after initial setup are not automatically re-verified. A compromised hook could persist undetected between manual audits.

Mitigation: Periodic /repo-audit checks hook checksums against configs/security/trusted-hooks.yaml.

Recommendation: Schedule weekly /repo-health (quick check) and monthly /repo-audit (full integrity scan). Consider adding a session-start hook that verifies critical hook checksums.

5.4 Enterprise Settings Not Enforced

Risk: Enterprise-level settings like enableAllProjectMcpServers: false and allowManagedHooksOnly: true are recommendations, not enforced defaults.

Recommendation: Document as mandatory in hardening guide. Verify via /repo-health when gh CLI is available.