Security Governance¶

How the toolkit enforces security across all development work.

Overview¶

The security governance layer operates at three levels:

Deny rules in settings.json — block dangerous tool invocations before they execute
Hook scripts in hooks.json — scan writes for secrets and lint for vulnerabilities
Review agents in /vt-c-4-review — the security-sentinel agent audits all code changes

These layers are cumulative. A deny rule prevents the action entirely; a hook can warn or block; a review agent reports findings for human judgment.

Deny rules¶

Deny rules live in your project's .claude/settings.json under permissions.deny. The toolkit provides a baseline at configs/security/baseline-settings.json covering five attack categories:

Category	Example rules
Network exfiltration	`Bash(curl:)`, `Bash(wget:)`, `WebFetch(:)`
Credential file access	`Read(~/.ssh/)`, `Read(/.env)`
Destructive commands	`Bash(rm -rf /)`, `Bash(sudo:)`
Shell config modification	`Edit(~/.bashrc)`, `Write(~/.zshrc)`
Untrusted package execution	`Bash(npx -y:)`, `Bash(pip install --index-url:)`

To apply the baseline to a new project, copy the deny rules from baseline-settings.json into your project's settings.

Hook scripts¶

Two hooks enforce security on every file write:

secret-scanner (PreToolUse) — blocks writes containing API keys, tokens, or passwords
security-lint (PostToolUse) — scans written files for common vulnerability patterns

These are configured in plugins/core-standards/hooks/hooks.json and activate automatically.

`allowed-tools` in agent frontmatter¶

Agents and skills can restrict their available tools using the allowed-tools field:

---
name: my-analysis-agent
allowed-tools:
  - Read
  - Grep
  - Glob
---

This prevents the agent from using Write, Edit, or Bash, making it read-only by design.

Configuration drift audit¶

Over time, security settings can drift from the agreed baseline. The drift audit (SPEC-046) checks for:

Deny rule drift — rules present in the baseline but missing from the project
MCP server drift — new MCP servers added without security review
Blanket MCP enable — overly permissive MCP configurations
Audit freshness — whether the last security audit is within the agreed interval

Run drift detection with /vt-c-repo-health. If intentional deviations exist, document them in configs/security/drift-waivers.yaml with an optional expiration date.

External repository evaluation¶

Evaluating an unknown external repository for patterns or adoption carries supply-chain risk. The /vt-c-repo-evaluate skill enforces a 4-level safety protocol:

Level	Method	Local execution	Requires approval
1 (default)	`gh api` — no clone	None	No
2	`git clone --no-checkout` + hook inspection	Git only (safe)	Yes
3	Docker container (read-only mount)	Sandboxed	Yes + Docker
4	Dependency audit tools	Audit only	Yes + tools

Level 1 runs by default — it fetches the file tree, README, and dependency manifests via the GitHub API without executing any local code. Risk signals (Makefiles, shell scripts, .github/workflows/) are highlighted before any escalation prompt.

Level 2 requires explicit approval at two gates: once before cloning, and once before checkout. The --no-checkout flag prevents post-clone and post-checkout hooks from firing.

/vt-c-repo-evaluate https://github.com/owner/repo
/vt-c-repo-evaluate owner/repo

Quick reference¶

Check	When it runs	What it does
Deny rules	Every tool invocation	Blocks matching tool calls
secret-scanner	Every Write/Edit	Blocks hardcoded secrets
security-lint	Every Write	Scans for vulnerability patterns
partition-guard	Every Write/Edit	Blocks cross-plugin writes
security-sentinel	`/vt-c-4-review`	Full security audit of changes
Drift audit	`/vt-c-repo-health`	Compares settings against baseline
Repo evaluation	`/vt-c-repo-evaluate`	Safe external repo analysis (Level 1–4)