open/llm-security
1
0
Fork 0
Code Issues Releases 6 Activity

docs(readme): shorter, concrete value proposition, antivirus alerts for organizations

Browse source 
README goes from 825 to 227 lines. The value proposition comes first
(three concrete outcomes), then install, a first-five-minutes table,
compact hook and command tables, and one section for teams and CI.

New section "Antivirus and EDR alerts": a warning at the top tells
organizations that products such as Microsoft Defender can raise
alerts, what v8.1.0 did about it (and that v8.1.1/v8.1.2 did not touch
it), that nothing has been measured on Windows, what still sits on
disk as readable text, how to report to Microsoft (managed devices via
the Defender portal, single machines via wdsi), and to email
security@fromaitochitta.com so the file can be fixed in a patch.

Corrected claims found by an independent fact-check: the standalone
CLI is not offline (npm audit, pip-audit, DNS, OSV.dev), the secrets
hook has 19 patterns not 30+, /security deep-scan takes no CI flags,
look-alike package names warn rather than block, the Linux bwrap
caveat, and the demo's 85 findings need the LLM half too. Moved to
links: scanner tables, knowledge list, playground, version history.

SECURITY.md: 8.1.x is the active line; antivirus alerts are in scope,
also on knowledge files; the dead README section references fixed.
CLAUDE.md: README section name updated.

repo-standard 22/22, doc-consistency + av-surface 51/0, full suite
2328 / 2322 pass / 0 fail / 6 skipped. Self-scan: README 1 -> 0
findings.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-09-23 09:42:41 +02:00
commit f92ad3f7b3
Signed by: ktg
SSH key fingerprint: SHA256:JakMjO6FTBBzN0Bhfj9saOoEjaFxlSdYuZQQpM/lF9Q
3 changed files with 149 additions and 740 deletions
Download patch file Download diff file Expand all files Collapse all files

946
README.md
View file

@ -2,7 +2,9 @@
Security scanning, auditing, and threat modeling for Claude Code projects. OWASP LLM Top 10 (2025) and Agentic AI Top 10.
> **Solo-maintained, fork-and-own.** This plugin is a starting point, not a vendor product. Issues are welcome as signals; pull requests are not accepted. See [GOVERNANCE.md](https://git.fromaitochitta.com/open/repo-standard/src/branch/main/GOVERNANCE.md) for the full model and what upstream provides.
**Check skills, plugins and MCP servers before they run with your agent's permissions — and stop secret leaks, destructive commands and prompt injection while you work.**
> **Solo-maintained, fork-and-own.** A starting point, not a vendor product. Issues are welcome as signals; pull requests are not accepted. See [GOVERNANCE.md](https://git.fromaitochitta.com/open/repo-standard/src/branch/main/GOVERNANCE.md).
*AI-generated: all code produced by Claude Code through dialog-driven development. Every change is human-directed, reviewed, and validated before commit. Per Anthropic Consumer Terms §4, ownership of outputs is assigned to the user; this plugin is licensed MIT.*
@ -11,755 +13,126 @@ Security scanning, auditing, and threat modeling for Claude Code projects. OWASP
![Scanners](https://img.shields.io/badge/scanners-22-cyan)
![License](https://img.shields.io/badge/license-MIT-lightgrey)
A Claude Code plugin that provides security scanning, auditing, and threat modeling for agentic AI projects. Built on [OWASP LLM Top 10 (2025)](https://genai.owasp.org/llm-top-10/), [OWASP Agentic AI Top 10 (ASI01-ASI10, 2026 edition)](https://genai.owasp.org/agentic-ai/), OWASP Skills Top 10 (AST01-AST10), MCP Top 10, and the [AI Agent Traps](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6372438) taxonomy (Google DeepMind, 2025), grounded in published research from ToxicSkills, ClawHavoc, MCPTox, Pillar Security, Invariant Labs, GHSL Security Lab, and Operant AI.
> [!WARNING]
> **Rolling this out in an organization?** Antivirus and EDR products such as Microsoft Defender **can** raise alerts on files in this repository, because it contains detection rules and descriptions of attack techniques. Read [Antivirus and EDR alerts](#antivirus-and-edr-alerts) before you deploy, and report any alert to **security@fromaitochitta.com** so it can be fixed.
---
## Why
## Table of Contents
A Claude Code extension does not just run code — it can give your agent instructions. A malicious skill can tell Claude to read `~/.ssh`, post your environment variables to a webhook, or rewrite its own configuration, while presenting itself as a harmless "project health dashboard". This is the npm/PyPI supply-chain problem with LLM agency added.
- [Why this exists](#why-this-exists)
- [Requirements](#requirements)
- [Install](#install)
- [First scan](#first-scan)
- [What's inside](#whats-inside)
- [Commands](#commands)
- [Automated hooks (9)](#automated-hooks-9)
- [Deterministic scanners](#deterministic-scanners)
- [Agents (6)](#agents-6)
- [Knowledge base (22 files)](#knowledge-base-22-files)
- [Coverage at a glance](#coverage-at-a-glance)
- [Compliance & governance](#compliance--governance)
- [Workflow examples](#workflow-examples)
- [Known limitations](#known-limitations)
- [Project scope](#project-scope)
- [Non-goals](#non-goals)
- [Defense philosophy](#defense-philosophy)
- [Compatibility](#compatibility)
- [Migrating to v8.0.0](#migrating-to-v800)
- [Playground (v7.6.0)](#playground-v760)
- [Self-scan](#self-scan)
- [Antivirus false positives](#antivirus-false-positives)
- [Recent versions](#recent-versions)
- [Changelog](#changelog)
- [License & attribution](#license--attribution)
- [Feedback & contributing](#feedback--contributing)
What you get:
## Why this exists
- **Guardrails from the moment you install.** Nine hooks run on every prompt and tool call. Five block: secrets written to files, writes to `.env`/`.ssh`/credentials, destructive shell commands, compromised or typosquatted packages, and prompt injection. Four warn.
- **A verdict before you install anything.** `/security scan <url> --deep` clones a repository into a temp directory (OS-sandboxed on macOS and on Linux with `bwrap`), runs 14 deterministic scanners plus LLM analysis, and returns ALLOW / WARNING / BLOCK — without loading the repository into your session.
- **A grade for your own setup.** `/security posture` scores your Claude Code configuration across 16 posture categories in seconds; `/security audit` gives an A–F report with the fixes.
Claude Code's extensibility model — skills, MCP servers, plugins, hooks, IDE extensions — creates an attack surface that mirrors the npm/PyPI supply chain problem with one critical difference: **extensions run with LLM agency**. A malicious plugin doesn't just execute code in a sandbox. It can instruct the agent to read your SSH keys, exfiltrate environment variables, install persistence mechanisms, and modify its own configuration — all while appearing to be a helpful "Project Health Dashboard."
This is not theoretical. ToxicSkills (Xi'an Jiaotong, 2025), ClawHavoc (Repello AI, 2025), GHSL-class workflow injections, and the November 2024 npm/PyPI typosquat campaigns documented real attack patterns. OWASP, NIST, and the EU AI Act now formalize the controls needed.
This plugin layers three independent kinds of defense — **runtime hooks** that block, **deterministic scanners** that compute, and **LLM-driven advisory commands** that judge — so failures in any one layer are caught by the others.
> [!IMPORTANT]
> **Scan repos remotely before cloning.** A poisoned `CLAUDE.md` injects instructions into the model context the moment you open a cloned repo — before any hook can intervene. `/security scan https://git.fromaitochitta.com/open/llm-security --deep` analyses everything safely via pre-extraction, without loading anything into your session. This is the primary defense against `CLAUDE.md` poisoning.
---
## Requirements
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) v2.x+
- Node.js (any recent LTS — required for hook scripts)
Findings map to [OWASP LLM Top 10 (2025)](https://genai.owasp.org/llm-top-10/), [OWASP Agentic AI Top 10](https://genai.owasp.org/agentic-ai/), OWASP Skills Top 10, MCP Top 10 and the [AI Agent Traps](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6372438) taxonomy (Google DeepMind).
## Install
Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code) v2.x+ and Node.js (any recent LTS).
```bash
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
claude plugin install llm-security@ktg-plugin-marketplace
```
Or enable directly in `~/.claude/settings.json`:
The hooks are active immediately. No configuration is needed.
```json
{
"enabledPlugins": {
"llm-security@ktg-plugin-marketplace": true
}
}
```
## First five minutes
Hooks activate immediately on install. Secret detection, path guarding, prompt-injection scanning, destructive-command blocking, supply-chain guardrails, and runtime trifecta detection start working without any commands.
## First scan
```
> /security posture
┌──────────────────────────────────────────────┐
│ Security Posture: 8/16 [B] 77% │
├──────────────────────────────────────────────┤
│ ✅ Deny-First Config │
│ ✅ Secrets Protection │
│ ⚠️ MCP Server Trust │
│ ✅ Destructive Command Blocking │
│ ⚠️ Sandbox Config │
│ ✅ Prompt Injection Hardening │
│ ⚠️ Rule of Two │
│ ✅ EU AI Act │
│ ⚠️ NIST AI RMF │
│ — ISO 42001 │
├──────────────────────────────────────────────┤
│ 6 findings (1 high, 3 medium, 2 low) │
└──────────────────────────────────────────────┘
```
> [!TIP]
> Start with `/security posture` for a 30-second baseline, then `/security audit` for the full picture, or `/security scan <target>` for supply-chain gating.
| Run | You get |
|-----|---------|
| `/security posture` | Scorecard for this project's Claude Code setup, with the top gaps |
| `/security scan <path\|url> --deep` | ALLOW / WARNING / BLOCK for a skill, plugin, MCP server or repository |
| `/security plugin-audit <path\|url>` | Install / Review / Do Not Install for a plugin |
| `/security audit` | Full A–F audit with a prioritized action plan |
| `/security harden --apply` | Grade A reference config (`settings.json`, `CLAUDE.md`, `.gitignore`), with backup |
> [!IMPORTANT]
> **Opus extended-context users:** subagents inherit the parent session's context limit but do not support extended context, causing API errors. Run `/model Opus` before using security commands to reset to the standard 200 K context window subagents handle correctly.
> **Scan a repository before you clone it.** A poisoned `CLAUDE.md` enters the model's context the moment you open a cloned repository — before any hook can run. `/security scan <url> --deep` inspects it from a pre-extracted evidence package instead.
---
## What runs automatically
## What's inside
| Hook | When | Effect |
|------|------|--------|
| Prompt injection scan | Every prompt | **Blocks** override instructions, spoofed system headers, identity redefinition; decodes obfuscation (Unicode Tag, hex, URL, base64, rot13) first |
| Secret detection | Edit, Write | **Blocks** AWS/Azure/GitHub/npm tokens, PEM keys, database URLs, JWTs, webhook URLs — 19 patterns, extendable in policy |
| Path guard | Edit, Write | **Blocks** writes to `.env*`, `.ssh/`, `.aws/`, `.gnupg/`, credentials, hook scripts, `settings.json` |
| Destructive commands | Bash | **Blocks** `rm -rf /`, pipe-to-shell, fork bombs, `chmod 777`, eval tricks — after undoing shell obfuscation |
| Supply chain | Bash | **Blocks** known-compromised packages (incl. known typosquats), critical CVEs, and brand-new packages (<72 h, few releases); **warns** on look-alike names — npm, pip, brew, docker, go, cargo, gem |
| Output check | After every tool | Warns on injection in tool output and on MCP tool descriptions that drift over time |
| Session guard | After every tool | Warns on the "lethal trifecta": untrusted input + sensitive read + an exfiltration step |
| Pre-compact scan | Before compaction | Warns on injection or credentials about to survive into the compacted context |
| Update check | Once a day | Tells you when a newer version exists (`LLM_SECURITY_UPDATE_CHECK=off` disables it) |
```mermaid
flowchart TB
subgraph Runtime["Runtime defense — 9 hooks"]
direction LR
H1["UserPromptSubmit<br/>injection scan"]
H2["PreToolUse<br/>secrets · paths · bash · supply chain"]
H3["PostToolUse<br/>output verify · session guard"]
H4["PreCompact<br/>transcript scan"]
end
Injection and trifecta modes (`block`/`warn`/`off`) are set per project in `.llm-security/policy.json`; the pre-compact mode via `LLM_SECURITY_PRECOMPACT_MODE`.
subgraph Scanning["Deterministic analysis — 22 scanners"]
direction LR
S1["UNI · ENT · PRM · DEP<br/>TNT · GIT · NET · MEM · SCR · TFA"]
S2["WFL workflow scanner"]
S3["MCI · IDE · PST · BOM<br/>+ standalone CLIs"]
end
## All commands
subgraph Advisory["Advisory analysis — 6 agents · 20 commands"]
direction LR
A1["Skill scanner<br/>7 threat categories"]
A2["MCP scanner<br/>5-phase analysis"]
A3["Posture · audit<br/>16 categories, A-F"]
A4["Threat model<br/>STRIDE × MAESTRO"]
end
subgraph Knowledge["Knowledge base — 22 files"]
direction LR
K1["5 OWASP frameworks<br/>+ DeepMind Agent Traps"]
K2["Threat patterns<br/>skills · MCP · workflows · IDE · secrets"]
K3["Compliance · research<br/>registry · packages"]
end
Runtime -->|"blocks/warns in real time"| User["Claude Code session"]
User -->|"/security scan"| Scanning
User -->|"/security audit"| Advisory
Advisory -.->|"grounded by"| Knowledge
Scanning -->|"enriches"| Advisory
```
Each layer is independent. A failure in one (e.g. an injection that slips past the prompt scanner) gets a second chance from the others (e.g. the trifecta session guard catching the attempted exfiltration step downstream).
---
## Commands
20 slash commands grouped by purpose. All accept `path` or GitHub URL targets unless noted.
### Scanning & assessment
| Command | Description |
|---------|-------------|
| `/security` | Router with quick-start guide |
| `/security scan [path\|url]` | Supply-chain gate — ALLOW/WARNING/BLOCK verdict on skills, MCP servers, directories, or remote repos |
| `/security scan [path\|url] --deep` | Adds 14 deterministic scanners on top of the LLM agents |
| `/security deep-scan [path]` | Run only the 14 orchestrated deterministic scanners. Supports `--fail-on <severity>`, `--compact`, `--format sarif`, `--output-file <path>` |
| `/security audit` | Full project audit, A-F grade, prioritized action plan |
| `/security plugin-audit [path\|url]` | Plugin trust assessment with Install/Review/Do Not Install verdict |
| `/security mcp-audit [--live]` | Audit installed MCP server configs (`--live` adds runtime inspection) |
| `/security mcp-inspect` | Connect to running MCP stdio servers and scan live tool descriptions via JSON-RPC 2.0 |
| `/security mcp-baseline-reset` | Clear cumulative-drift baseline cache after a legitimate MCP server upgrade (E14, v7.3.0) |
| `/security ide-scan [target\|url]` | Scan installed VS Code (+ Cursor, Windsurf, VSCodium, code-server) and JetBrains extensions, OR fetch a remote VSIX from VS Code Marketplace, OpenVSX, direct `.vsix`, or JetBrains Marketplace. 7 VS Code + 7 JetBrains-specific checks plus UNI/ENT/NET/TNT/MEM/SCR per extension |
| `/security posture` | 30-second scorecard across 16 categories incl. EU AI Act, NIST AI RMF, ISO 42001 |
| `/security diff [path]` | Compare scan against stored baseline — new/resolved/unchanged/moved findings |
| `/security watch [path] [--interval 6h]` | Continuous monitoring via `/loop` |
| `/security registry [scan\|search]` | Skill signature registry — view stats, scan-and-register, search known fingerprints |
| `/security supply-check [path]` | Re-audit installed dependencies from lockfiles against blocklists, OSV.dev, and typosquats |
| `/security dashboard` | Cross-project security dashboard — machine-grade aggregation across all projects under `~/` |
### Remediation
| Command | Description |
|---------|-------------|
| `/security clean [path]` | Three-tier remediation pipeline — auto-fix safe issues, confirm semi-auto with the user, report manual findings |
| `/security clean [path] --dry-run` | Preview without modifying files |
| `/security harden [path]` | Generate Grade A reference config (`settings.json`, `CLAUDE.md`, `.gitignore`) |
| `/security harden [path] --apply` | Apply with automatic backup |
### Threat modeling & planning
| Command | Description |
|---------|-------------|
| `/security threat-model` | Interactive STRIDE × MAESTRO 7-layer session, 15-30 min |
| `/security red-team [--category] [--adaptive]` | Attack simulation — 72 scenarios across 12 categories, 100 % block rate. `--adaptive` applies 5 mutation rounds per blocked scenario for evasion testing |
| `/security pre-deploy` | Pre-deployment checklist — 10 automated + 3 manual checks |
### Remote scanning safely
`/security scan` and `/security plugin-audit` accept GitHub and Forgejo URLs directly. The plugin clones to a temp directory inside an OS sandbox, scans, and cleans up.
```
/security scan https://git.fromaitochitta.com/open/llm-security --deep
/security scan https://github.com/<owner>/<repo> --branch dev --deep
```
**Defense-in-depth on the clone path** (v5.1+):
| Layer | Mechanism | Mitigates |
|-------|-----------|-----------|
| Git config hardening | `core.hooksPath=/dev/null`, `core.symlinks=false`, all `filter.lfs.*` neutralized, `protocol.file.allow=never`, `transfer.fsckObjects=true`, plus `GIT_CONFIG_NOSYSTEM=1` and friends | Git hooks at clone, symlink traversal, filter/smudge driver code execution via `.gitattributes` (CVE-2024-32002 class), local-file protocol traversal, malformed objects |
| OS filesystem sandbox | macOS `sandbox-exec` (Seatbelt) or Linux `bwrap` (bubblewrap) restricts writes to the per-clone temp dir | Even if a filter driver bypasses git config hardening, the kernel refuses writes outside the sandbox |
| `.gitattributes` post-clone advisory (E12, v7.3.0) | `scanGitAttributes()` scans for `filter=` / `diff=` / `merge=` driver directives and emits MEDIUM advisories | Surfaces driver-based supply-chain surface that survives even a sandboxed clone |
| Pre-LLM injection strip | `content-extractor.mjs` produces a structured JSON evidence package; `[INJECTION-PATTERN-STRIPPED]` markers are confirmed findings | Agents never see raw poisoned files from untrusted repos |
| Post-clone size cap | 100 MB max | Resource-exhaustion attacks |
**Where the OS sandbox layer actually holds:**
| Platform | Sandbox | How it works | Limitations |
|----------|---------|--------------|-------------|
| **macOS** | [`sandbox-exec`](https://keith.github.io/xcode-man-pages/sandbox-exec.1.html) | Seatbelt profile restricts file writes to only the per-clone temp dir | Deprecated by Apple but still functional; no replacement exists |
| **Linux** | [`bubblewrap`](https://github.com/containers/bubblewrap) (bwrap) | Read-only root bind mount + writable clone dir + namespace isolation | Requires the `bwrap` package. Works on Fedora/Arch; [fails on Ubuntu 24.04+](https://discourse.ubuntu.com/t/understanding-apparmor-user-namespace-restriction/58007) without admin AppArmor configuration |
| **Windows** | None available | Git config hardening only (layer 1) | See the Windows options below |
Sandbox availability is probe-tested at runtime. When none is available the plugin logs a WARN and proceeds with git config hardening only.
**Windows guidance:** Windows ships no CLI-level filesystem sandbox equivalent to `sandbox-exec` or `bwrap`. Every alternative needs either extra software or admin privileges:
| Option | Isolation level | Requirements |
|--------|-----------------|--------------|
| [Windows Sandbox](https://learn.microsoft.com/en-us/windows/security/application-security/application-isolation/windows-sandbox/windows-sandbox-overview) | Full VM (Hyper-V) | Windows Pro/Enterprise with Hyper-V enabled. GUI-oriented, not scriptable |
| [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) | Container | Docker install. Best option for automated isolation |
| [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) | Linux VM | WSL2 install. `bwrap` is available inside it, subject to the Ubuntu 24.04+ caveat above |
| [AppContainer](https://learn.microsoft.com/en-us/windows/win32/secauthz/appcontainer-isolation) | Process sandbox | A native C++ helper binary — not practical to ship in a Node.js plugin |
Run Claude Code inside WSL2 or Docker Desktop for full coverage. The git config hardening alone is sufficient against all known `.gitattributes` attack vectors on every platform.
> **Why not Node.js `--permission`?** Node's [permission model](https://nodejs.org/api/permissions.html) restricts `fs` access *within* the Node process. It does not sandbox child processes, and `git` runs as a separate OS process — so it does not address this threat at all.
---
## Automated hooks (9)
Hooks run on every operation — no commands needed. They activate the moment the plugin is installed.
| Hook | Event | What it does |
|------|-------|--------------|
| **Prompt injection scan** | UserPromptSubmit | Blocks direct injection (override instructions, spoofed system headers, identity redefinition) and warns on subtle signals (leetspeak, homoglyphs, zero-width chars, multi-language). Decodes obfuscated payloads (Unicode Tag, hex, URL, base64, rot13) before matching. Mode: policy key `injection.mode` = `block\|warn\|off` (default block) |
| **Secret detection** | Edit, Write | Blocks AWS keys, Azure tokens, GitHub PATs, npm tokens, PEM keys, database URLs, Bearer tokens, and 30+ other secret patterns |
| **Path guarding** | Write | Blocks writes to `.env*` (multi-segment-suffix-safe), `.ssh/`, `.aws/`, `.gnupg/`, credentials files, hook scripts, `/etc/`, `settings.json` |
| **Destructive commands** | Bash | Blocks `rm -rf /`, `chmod 777`, pipe-to-shell, fork bombs, eval-with-substitution, T8 base64-pipe-shell loaders. Bash-normalize T1-T9 collapses obfuscation (empty quotes, `${IFS}`, ANSI-C hex, process substitution, eval-via-variable) before pattern matching |
| **Supply-chain guardrail** | Bash | Blocks known-compromised npm/pip packages, Levenshtein typosquats, age-gated installs (<72 h), OSV.dev CVE checks. Covers npm, pip, brew, docker, go, cargo, gem. v7.3.0: npm scope-hop typosquat advisory (E13) — `@evil/lodash`-class catches scope-jumping when the unscoped name matches a popular package |
| **Output verification** | All tools (post) | Advisory: scans ALL tool output for indirect injection (LLM01) and HITL traps (DeepMind kat. 6). Bash-specific: leaked secrets, unexpected URLs, oversized MCP responses. v7.3.0: per-update MCP description drift AND cumulative drift vs sticky baseline (E14) — slow-burn rug-pulls that stay under per-update thresholds but cumulatively diverge ≥25% emit `mcp-cumulative-drift` MEDIUM |
| **Session guard** | All tools (post) | Advisory: monitors tool-call sequences for the lethal trifecta (untrusted input + sensitive read + exfiltration sink). 20-call sliding window + 100-call long-horizon window. Mode: policy key `trifecta.mode` = `block\|warn\|off`. Sub-agent delegation tracking via Task/Agent tools surfaces escalation-after-input as a separate advisory |
| **Pre-compact scan** | PreCompact | Scans transcript tail (max 512 KB, <500 ms) for injection patterns + credentials before context compaction. Prevents poisoned content from surviving in compact form. Mode: `LLM_SECURITY_PRECOMPACT_MODE=block\|warn\|off` (default warn) |
| **Update check** | UserPromptSubmit | Checks for newer plugin versions max 1× / 24 h, cached. Disable: `LLM_SECURITY_UPDATE_CHECK=off` |
All hooks are Node.js `.mjs` for cross-platform compatibility (macOS, Linux, Windows).
> [!IMPORTANT]
> Five hooks are **blocking** (prompt injection, secrets, path guarding, destructive commands, supply chain). Four are **advisory** (output verification, session guard, pre-compact, update check). Blocking modes can be downgraded via env-vars or `policy.json` for security research or staged rollouts.
---
## Deterministic scanners
22 scanners. Zero external dependencies. All output JSON.
### Orchestrated (14) — run via `node scanners/scan-orchestrator.mjs <target>` or `/security deep-scan`
| Scanner | Prefix | Detects | OWASP |
|---------|--------|---------|-------|
| `unicode-scanner.mjs` | UNI | Zero-width chars, Unicode Tag steganography (incl. PUA-A/B), BIDI overrides, Cyrillic/Greek homoglyphs (NFKC fold) | LLM01 |
| `entropy-scanner.mjs` | ENT | High-entropy strings, base64/hex blobs, encoded payloads via Shannon entropy. Two-stage context classification suppresses GLSL/CSS/inline-SVG/markdown-CDN false positives | LLM01, LLM03 |
| `permission-mapper.mjs` | PRM | Purpose-vs-tools mismatch, ghost hooks, haiku on sensitive agents, overprivileged components | LLM06 |
| `dep-auditor.mjs` | DEP | CVEs (npm/pip audit + OSV.dev), Levenshtein + token-overlap typosquats, malicious install scripts, unpinned versions | LLM03 |
| `taint-tracer.mjs` | TNT | Source-to-sink data flow (process.env / req.body → eval / exec / fetch / writeFile), 3-pass analysis, destructuring + spread support | LLM01, LLM02 |
| `git-forensics.mjs` | GIT | Force pushes, description drift, hook modifications, new outbound URLs, author changes | LLM03 |
| `network-mapper.mjs` | NET | Undisclosed URLs, suspicious domains (ngrok, webhook.site), IP-based URLs, DNS analysis | LLM02, LLM03 |
| `memory-poisoning-scanner.mjs` | MEM | Injection patterns, shell commands, credential paths, permission expansion, suspicious URLs in `CLAUDE.md` / memory / `.claude/rules` / `.claude/agents/*.md` | LLM01, ASI02 |
| `supply-chain-recheck.mjs` | SCR | Re-audit installed deps from lockfiles against blocklists, OSV.dev batch API, typosquats | LLM03 |
| `toxic-flow-analyzer.mjs` | TFA | Lethal trifecta correlation across prior scanner output (runs last) | ASI01, ASI02, ASI05 |
### Workflow & live (3, run independently)
| Scanner | Prefix | Detects | OWASP |
|---------|--------|---------|-------|
| `workflow-scanner.mjs` (E11, v7.3.0) | WFL | GitHub Actions and Forgejo Actions injection — dangerous `${{ <field> }}` interpolations inside `run:` blocks across a 23-field GHSL+GlueStack-class blacklist; sink-restricted (only `run:` is a shell sink); severity matrix grades by trigger privilege; tracks env-block re-interpolation (Appsmith GHSL-2024-277 stealth pattern); flags `actor == bot[bot]` auth-bypass (Synacktiv 2023 Dependabot class) | LLM02, LLM06 |
| `mcp-live-inspect.mjs` | MCI | Connects to running MCP servers via JSON-RPC 2.0 and scans live tool descriptions for injection, shadowing, drift | LLM01, LLM02 |
| `ide-extension-scanner.mjs` | IDE | VS Code (+ forks) and JetBrains plugin prescan: blocklist, theme-with-code, sideload, broad activation, typosquat, extension-pack expansion, dangerous uninstall hooks; `Premain-Class` instrumentation; native binaries; nested-jar inspection | LLM01-03, LLM06, ASI02, ASI04 |
### Standalone utilities (10)
| Scanner | Purpose |
| Command | Purpose |
|---------|---------|
| `posture-scanner.mjs` | Deterministic posture assessment, 16 categories, <50 ms |
| `attack-simulator.mjs` | Red-team harness: 72 scenarios, 12 categories, fixed + adaptive modes, benchmark output |
| `ai-bom-generator.mjs` | CycloneDX 1.6 AI Bill of Materials |
| `dashboard-aggregator.mjs` | Cross-project security dashboard with weakest-link machine grade |
| `reference-config-generator.mjs` | Grade A config generation based on posture gaps |
| `mcp-baseline-reset.mjs` | Clear cumulative-drift baseline cache (`--list` / `--target <tool>` / clear-all) |
| `auto-cleaner.mjs` | Remediation engine — 16 fix operations, atomic writes, post-fix validation |
| `content-extractor.mjs` | Pre-extracts evidence from untrusted repos and strips injection patterns before LLM exposure |
| `watch-cron.mjs` | Cron wrapper for background scanning |
| `scan-orchestrator.mjs` | Entry point that runs all 14 orchestrated scanners |
**Why deterministic?** LLMs are powerful at semantic analysis — intent, social engineering, context. They cannot reliably calculate Shannon entropy, measure Levenshtein distance between package names, trace taint flow across function boundaries, or detect individual Unicode codepoints. These scanners fill that gap.
### MCP cumulative drift baseline (E14, v7.3.0)
`scanners/lib/mcp-description-cache.mjs` anchors a sticky `baseline` description per MCP tool plus a rolling 10-event history. Cumulative drift = `levenshtein(current, baseline) / max(|current|, |baseline|)`. When the ratio crosses `mcp.cumulative_drift_threshold` (default 0.25), `post-mcp-verify.mjs` emits a MEDIUM `mcp-cumulative-drift` advisory — independent of the existing per-update >10% drift signal. Slow-burn rug-pulls that keep each update under the per-update threshold but cumulatively diverge from baseline are now caught.
The baseline survives the 7-day TTL purge so detection persists across the full window. After a legitimate MCP server upgrade, run `/security mcp-baseline-reset` (or `node scanners/mcp-baseline-reset.mjs --target <tool>`) to clear the stale baseline. The next call seeds a fresh baseline; description, firstSeen, lastSeen, and history are preserved across reset for audit. `LLM_SECURITY_MCP_CACHE_FILE` overrides the cache path for testing.
---
## Agents (6)
Specialized analysts spawned by commands. Read-only by default; `clean` and `harden` grant Edit/Write under explicit user confirmation.
| Agent | Role | Spawned by |
|-------|------|------------|
| `skill-scanner-agent` | 7 threat categories (injection, exfiltration, privilege escalation, scope creep, hidden instructions, toolchain manipulation, persistence) for skills/commands/agents | `scan`, `audit`, `plugin-audit` |
| `mcp-scanner-agent` | 5-phase MCP analysis (tool descriptions, source code, dependencies, configuration, rug pull detection) | `scan`, `mcp-audit` |
| `posture-assessor-agent` | Full audit narrative with PASS/PARTIAL/FAIL scoring and A-F grading (the deterministic `posture-scanner.mjs` handles quick mode) | `audit`, `posture` |
| `threat-modeler-agent` | Interactive STRIDE × MAESTRO interview, 5-phase workflow | `threat-model` |
| `deep-scan-synthesizer-agent` | Interprets deterministic scanner JSON into a human-readable report with executive summary + prioritized recommendations | `deep-scan`, `scan --deep` |
| `cleaner-agent` | Generates semi-auto remediation proposals for findings requiring human judgment (returns JSON proposals; `clean.md` performs the edits after user approval) | `clean` |
All agents run on Opus and reference the knowledge base for grounding. Agents are spawned sequentially to avoid burst rate limits.
---
## Knowledge base (22 files)
All analysis is grounded in published threat intelligence. The knowledge files are read by agents at scan time, not loaded preemptively.
| Category | Files |
|----------|-------|
| **OWASP frameworks** | `owasp-llm-top10.md`, `owasp-agentic-top10.md`, `owasp-skills-top10.md`, `mcp-threat-patterns.md` (9 categories), `mitigation-matrix.md` |
| **Threat patterns** | `skill-threat-patterns.md` (7 categories from ToxicSkills/ClawHavoc), `secrets-patterns.md` (30+ regex), `ide-extension-threat-patterns.md` (10 categories with 2024-2026 case studies), `workflow-injection-patterns.md` (23-field blacklist + Forgejo divergences) |
| **Research** | `prompt-injection-research-2025-2026.md` (7 papers), `deepmind-agent-traps.md` (6 categories, 43 techniques), `attack-scenarios.json` (72 red-team scenarios), `attack-mutations.json` (synonym tables for adaptive testing) |
| **Compliance** | `compliance-mapping.md` (EU AI Act, NIST AI RMF, ISO 42001, MITRE ATLAS), `norwegian-context.md` (Datatilsynet, NSM, Digitaliseringsdirektoratet) |
| **Reference data** | `top-packages.json` (top 200 npm + 100 PyPI), `top-vscode-extensions.json`, `top-jetbrains-plugins.json`, `typosquat-allowlist.json`, `marketplace-api-notes.md`, `jetbrains-marketplace-api-notes.md`, `skill-registry.json` |
---
## Coverage at a glance
**OWASP LLM Top 10 (2025) — control-count coverage from `knowledge/mitigation-matrix.md`:**
| Category | Hooks | Scanners | Commands | Coverage |
|----------|:-----:|:--------:|:--------:|:--------:|
| LLM01 Prompt Injection | ✅ | UNI + ENT + TNT | scan, audit | 95 % |
| LLM02 Sensitive Info Disclosure | ✅ | TNT + NET | audit | 83 % |
| LLM03 Supply Chain | ◐ | ENT + DEP + GIT + NET | scan, plugin-audit, mcp-audit, supply-check | 60 % |
| LLM04 Data Poisoning | — | — | threat-model | 40 % |
| LLM05 Improper Output Handling | ✅ | — | audit | 83 % |
| LLM06 Excessive Agency | ✅ | PRM + WFL | posture | 100 % |
| LLM07 System Prompt Leakage | — | — | audit | 60 % |
| LLM08 Vector/Embedding Weaknesses | — | — | threat-model | 40 % |
| LLM09 Misinformation | — | — | advisory | 50 % |
| LLM10 Unbounded Consumption | — | — | pre-deploy | 83 % |
Average ~69 %. Strongest at prompt injection (95 % with input + output scanning + obfuscation decoders) and agency controls (100 %). Weakest at LLM04/08, which are better addressed at the model-provider or platform level. `/security threat-model` and `/security pre-deploy` surface the gaps advisorily.
**Agentic and skill frameworks** — full ASI01-ASI10 and AST01-AST10 mapping in `knowledge/owasp-agentic-top10.md` and `knowledge/owasp-skills-top10.md`.
---
## Compliance & governance
| Capability | Detail |
|------------|--------|
| **Compliance mapping** | EU AI Act (Art. 9, 15, 17), NIST AI RMF (Map / Measure / Manage / Govern), ISO 42001 (Annex A), MITRE ATLAS techniques. Posture categories 14-16 assess readiness |
| **Norwegian context** | Datatilsynet DPIA-for-AI guidance, NSM basic security principles, Digitaliseringsdirektoratet — relevant for Norwegian public-sector deployments |
| **SARIF 2.1.0 output** | `--format sarif` on scan / deep-scan produces OASIS SARIF for CI/CD ingestion (GitHub Advanced Security, Azure DevOps, SonarQube) |
| **Structured audit trail** | JSONL events with ISO 8601 timestamps and OWASP category tags (`audit.log_path` policy key) — SIEM-ready |
| **AI-BOM** | CycloneDX 1.6 BOM for AI components — models, MCP servers, plugins, knowledge files, hooks (`llm-security audit-bom <target>`) |
| **Policy-as-code** | `.llm-security/policy.json` ships hook configuration with the team — the only source for injection, trifecta, and audit configuration since v8.0.0 removed the overlapping env-vars |
| **Standalone CLI** | `node bin/llm-security.mjs scan <target>` — runs scanners without Claude Code. Subcommands: `scan`, `deep-scan`, `posture`, `audit-bom`, `benchmark`. Schrems II compatible in default offline mode (optional OSV.dev enrichment is the only network call and is opt-in) |
| **CI/CD integration** | `--fail-on <severity>` for threshold-based exit codes, `--compact` for one-liner output. Templates for GitHub Actions, Azure DevOps, GitLab CI in `ci/`. Guide: `docs/ci-cd-guide.md` |
### Benchmarks
`/security red-team` (also `llm-security benchmark`) tests hook defenses with 72 crafted scenarios across 12 categories. Adaptive mode applies 5 mutation rounds per blocked scenario (homoglyph substitution, encoding wrapping, zero-width injection, case alternation, synonym replacement). Current block rate: 100 % fixed mode.
---
## Workflow examples
### 1 — pre-installation gate
```
/security scan path/to/plugin # ALLOW/WARNING/BLOCK
/security plugin-audit path/to/plugin # Install/Review/Do Not Install
# Remote — scans without installing
/security scan https://git.fromaitochitta.com/open/llm-security --deep
/security plugin-audit https://github.com/<owner>/<repo>
```
### 2 — monthly review
```
/security posture # 30-second baseline
/security audit # full A-F grade with action items
# → fix critical/high
/security posture # verify improvement
```
### 3 — track over time
```
/security diff path/to/project # first run creates baseline
/security watch path/to/project # continuous, runs diff every 6h via /loop
```
### 4 — deep threat analysis
```
/security threat-model # 15-30 min STRIDE × MAESTRO interview
/security audit # verify current controls vs identified threats
/security pre-deploy # 10 automated + 3 manual checks
```
### 5 — remediation
```
/security clean path/to/project --dry-run # preview
/security clean path/to/project # auto + semi-auto + manual report
/security harden path/to/project --apply # Grade A reference config
```
---
## Known limitations
| Area | Why | Alternative |
|------|-----|-------------|
| Post-clone `CLAUDE.md` poisoning | Once a repo is cloned, `CLAUDE.md` loads into the system prompt *before* any hook runs. Platform limitation, no hook-based fix. | **Always scan repos remotely before cloning** with `/security scan <url> --deep`. For repos already cloned: review `CLAUDE.md` before opening |
| ML-based injection classification | Regex patterns cannot catch novel phrasings or adversarial paraphrasing. Joint paper (14 researchers, 2025) reports 95-100 % ASR against all 12 tested defenses for motivated adaptive attackers | Use [parry-guard](https://github.com/vaporif/parry) (DeBERTa v3 + Llama Prompt Guard 2) alongside this plugin. No conflict |
| Enterprise SSO / SCIM | Platform-level configuration | Anthropic Admin Console |
| RAG infrastructure | Vector DB / embedding pipeline security | Dedicated RAG security tools |
| LLM gateway / proxy | Network infrastructure layer | API gateway solutions |
| SIEM integration | Organization security stack | Splunk, Sentinel, etc. — but the JSONL audit trail is SIEM-ready |
| General agent scheming detection | The session guard catches the lethal trifecta as a known sequence; novel hidden-goal pursuit remains fundamentally hard for any tool. | Trifecta + delegation tracking provide partial coverage; full scheming detection requires monitoring + human oversight |
These gaps are surfaced advisorily through `/security threat-model` and `/security pre-deploy`.
### Complementary tools
| Tool | What it adds |
|------|--------------|
| [parry-guard](https://github.com/vaporif/parry) | ML injection classification (DeBERTa v3 + Llama Prompt Guard 2 86M, Rust, fail-closed). Catches what regex misses |
| [Lasso claude-hooks](https://github.com/lasso-security/claude-hooks) | Different philosophy: 96 patterns across 5 categories, warn-and-continue. Both can run in the same hook chain |
| [Snyk agent-scan](https://github.com/snyk/agent-scan) | Commercial skills/MCP scanning with a larger training set (3 984 skills analyzed) |
> [!TIP]
> Recommended combo: **llm-security** (breadth — static + supply chain + audit + posture + threat modeling) + **parry-guard** (depth — ML injection classification). Different layers, no conflict.
---
## Project scope
This is a **solo open-source project in stabilization mode** as of 2026-05-01.
The current feature set (5 frameworks, 22 scanners, 9 hooks, 6 agents,
20 commands, 22 knowledge files, 2045+ tests including a dedicated end-to-end suite) is the natural plateau for
what a deterministic + advisory plugin can defend against without crossing
into commercial-grade territory. Going forward, work focuses on:
- **Bug fixes** and security patches
- **Compatibility** with new Claude Code releases
- **Knowledge-base refresh** (OWASP updates, new published research, new attack patterns)
- **Deprecation cleanup** — v8.0.0 removed the four `LLM_SECURITY_*` mode env vars and `riskScoreV1`, both deprecated in v7.3.0 (see [Migration](#migrating-to-v800)). The notice period this follows is stated in [`SECURITY.md`](SECURITY.md#deprecation-notice-period)
- **Opportunistic small additions** that fit the existing deterministic architecture
## Non-goals
The following are **explicitly out of scope — fork the repo and own them**
under your organization's name. The MIT license permits this and the project
is architected to be forkable. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for
the fork-and-own guide.
| Out of scope | Why | Where to look instead |
|--------------|-----|------------------------|
| Web dashboard / fleet policy server | Multi-tenant UX + ongoing infra work | Snyk, Lakera Cloud |
| Runtime prompt firewall (real-time blocking proxy) | Inline gateway architecture | Lakera Guard, Protect AI Rebuff, [parry-guard](https://github.com/vaporif/parry) |
| IDE real-time LSP scanning | IDE integration + always-on perf budget | Snyk IDE, Semgrep IDE |
| Compliance PDF/DOCX evidence pack | Auditor-formatted reports as a product | Vanta, Drata, Secureframe |
| Enterprise ticketing / chat connectors (Jira, ServiceNow, Slack, Teams, PagerDuty) | Per-vendor SDK + auth + ongoing API drift | Splunk SOAR, Tines, custom integration |
| Multi-tenancy / centralized plugin runtime / fleet state | Hosted-product surface area | Build it on a fork |
| ML-based detectors requiring model hosting | Model-serving infra (training, eval, drift) | parry-guard (DeBERTa v3 + Llama Prompt Guard 2) |
| Marketplace UI / web catalog | Frontend product | This is not that kind of project |
| SSO / SCIM / RBAC | Platform-level enterprise concerns | Anthropic Admin Console + your IdP |
If you need any of the above and your organization has the headcount to
maintain it, **fork freely**. The maintainer encourages it. Issues and
support flow back to the fork, not here.
---
## Defense philosophy
Prompt injection is **structurally unsolvable** with current architectures (joint paper, 14 researchers, 2025: 95-100 % ASR against all 12 tested defenses by motivated red-teamers). v5.0+ does not claim to "prevent" injection. It implements defense-in-depth:
- **Broader detection** — MEDIUM advisories for obfuscation signals (leetspeak, homoglyphs, zero-width chars, multi-language); Unicode Tag and PUA-A/B steganography; bash expansion evasion T1-T9; rot13 hidden imperatives in comments
- **Increased attack cost** — Rule-of-Two trifecta detection (configurable block/warn/off, default warn), bash normalization before gate matching, MCP cumulative-drift baseline catching slow-burn rug-pulls
- **Longer monitoring windows** — 100-call long-horizon alongside 20-call sliding window; slow-burn trifecta detection (legs >50 calls apart); Jensen-Shannon behavioral drift; sub-agent delegation tracking
- **Architectural constraints** — opportunistic byte-fingerprint matching for output→input lineage (first 200 bytes, SHA-256/16-hex tag — not semantic capability tracking; trivially bypassed by mutation, but raises the cost of casual exfil)
- **Honest documentation** — known limitations are surfaced, not hidden
**System-card alignment (Opus 4.7):** §5.2.1 documents that multi-layer defenses outperform single-layer against adaptive attacks; this plugin's posture matches. §6.3.1.1 documents that Opus 4.7 follows agent instructions more literally — stacked imperatives are less useful than tool-level enforcement, and agent files have been updated accordingly. Full mapping in `docs/security-hardening-guide.md` §5.
**What v5.0+ cannot do:** prevent adaptive attacks from motivated human red-teamers, fix `CLAUDE.md` loading before hooks (platform limitation), detect novel NL indirection without ML, prevent long-horizon attacks without detectable patterns, provide formal worst-case guarantees.
---
## Compatibility
- **Claude Code:** v2.x+
- **Platform:** macOS, Linux, Windows (all hooks are Node.js `.mjs`)
- **Node.js:** any recent LTS for hook scripts and CLI
- **Overlap with `claude-code-essentials`:** safe to run both. This plugin extends with path guarding, MCP verification, and runtime trifecta detection. Duplicate blocking is harmless — hooks run sequentially
---
## Migrating to v8.0.0
v8.0.0 removes the four `LLM_SECURITY_*` configuration env-vars deprecated in
v7.3.0. Configuration moved to `.llm-security/policy.json`, which travels with
the repository instead of living in whoever's shell happened to launch Claude
Code.
**A removed variable is now inert.** It does not warn and it does not
configure — a project that relied on `LLM_SECURITY_INJECTION_MODE=off` silently
returns to the `block` default. Check for these before upgrading:
```bash
env | grep '^LLM_SECURITY_\(INJECTION_MODE\|TRIFECTA_MODE\|ESCALATION_WINDOW\|AUDIT_LOG\|DEPRECATION_QUIET\)='
grep -rn 'LLM_SECURITY_\(INJECTION_MODE\|TRIFECTA_MODE\|ESCALATION_WINDOW\|AUDIT_LOG\)' \
~/.zshenv ~/.bashrc .envrc .github/workflows/ 2>/dev/null
```
| Removed env-var | Policy key | Default |
|-----------------|------------|---------|
| `LLM_SECURITY_INJECTION_MODE` | `injection.mode` | `block` |
| `LLM_SECURITY_TRIFECTA_MODE` | `trifecta.mode` | `warn` |
| `LLM_SECURITY_ESCALATION_WINDOW` | `trifecta.escalation_window` | `5` |
| `LLM_SECURITY_AUDIT_LOG` | `audit.log_path` | unset (audit trail off) |
| `LLM_SECURITY_DEPRECATION_QUIET` | *(none)* | removed with the warning it silenced |
Translate each one you find into `.llm-security/policy.json`:
```json
{
"injection": { "mode": "block" },
"trifecta": { "mode": "warn", "escalation_window": 5 },
"audit": { "log_path": "/var/log/llm-security/audit.jsonl" }
}
```
**Unaffected.** Env-vars with no policy equivalent keep working and are not
part of this change: `LLM_SECURITY_PRECOMPACT_MODE`,
`LLM_SECURITY_PRECOMPACT_MAX_BYTES`, `LLM_SECURITY_UPDATE_CHECK`,
`LLM_SECURITY_MCP_CACHE_FILE`, `LLM_SECURITY_IDE_ROOTS`.
**Also removed:** `riskScoreV1()` in `scanners/lib/severity.mjs`, the v1
sum-and-cap scoring formula `@deprecated` since v7.0.0 and kept for reference
only. It had no callers in code or tests. `riskScore()` (v2, severity-dominated)
is unchanged, so no score, band, or verdict moves.
---
## Playground (v7.6.0)
A single-file SPA at `playground/llm-security-playground.html` provides
an interactive surface for onboarding, command discovery and report demos
**without requiring Claude Code installation**. Open the file directly in
a browser (Chrome/Firefox/Safari over `file://`) — no build step, no
network calls, no npm install. Theme-bootstrap with FOUC-prevention; state
persisted in IndexedDB primary + localStorage fallback.
**v7.6.0 Tier 3 reference case:** The playground is now a visually and
structurally complete reference for the `shared/playground-design-system/`
Tier 3 supplement. 8 new DS components integrated into the 18 report
renderers: `tfa-flow` (lethal trifecta chain), `mat-ladder` (maturity
ladder), `suppressed-group` (narrative audit), `codepoint-reveal` (Unicode
steganography), `top-risks` (ranked top findings), `recommendation-card
[data-severity]` (severity-tinted advisory), `risk-meter` (band
visualization 0-100), `card--severity-{level}` (severity-color findings
cards). Plus `badge--scope-security`, `verdict-pill-lg`, and
`form-progress`+`fp-step` from wave 1.
**Layout:**
```
playground/
├── llm-security-playground.html ← single-file SPA (~10 700 lines)
├── vendor/
│ └── playground-design-system/ ← synced from shared/, checksum-locked
├── test-fixtures/ ← markdown fixtures (one per command)
├── screenshots/v7.5.0/ ← Playwright-generated demo images (12)
├── screenshots/v7.6.0/ ← v7.6.0 demo images (12, hand-generated)
└── A11Y-RAPPORT.md ← WCAG 2.1 AA verification + Tier 3 ARIA
```
**What the playground covers:**
- **Onboarding (5 groups):** organization, scope, profile, platform,
compliance. Values persist as `shared` state and prefill every command
form automatically.
- **Home:** project grid, fleet tracks for posture/scan/red-team. The
"Load demo data" button activates 3 projects, including
`dft-komplett-demo` with all 18 reports parsed in advance.
- **Catalog:** all 20 commands grouped into 5 categories. Search filters
cards, and the "Open form" button builds a ready-to-paste pipeline
string for the terminal.
- **Project surface:** 4 screens (Overview / Reports / Context / Export).
The Reports tab has category tabs (discover / posture / findings-ops /
hardening / adversarial / mcp-ops) and paste-import for every report
command.
**Parser/renderer architecture:** Every `produces_report=true` command in
`CATALOG` has a parser (markdown → structure) and a renderer (structure
→ DS components). 18 archetypes are supported: `findings`,
`findings-grade`, `risk-score-meter`, `posture-cards`, `dashboard-fleet`,
`red-team-results`, `diff-report`, `kanban-buckets`, `matrix-risk`. The
parser contract is `{ ok: true, data: {...} } | { ok: false, errors:
[...] }`. The test fixtures under `playground/test-fixtures/` are the
contract anchor — one markdown file per command, mirroring the
`templates/unified-report.md` format.
**Exposed testing/automation globals:** `__store`, `__navigate`,
`__loadDemoState`, `__scheduleRender`, `__PARSERS`, `__RENDERERS`,
`__CATALOG`, `__inferVerdict`, `__inferKeyStats`, `__renderPageShell`,
`__handlePasteImport`. They enable Playwright-driven navigation and
programmatic parser/renderer tests against the fixture catalog.
**Limitations:** The SPA is a paste-in surface — it does not run any
scanners itself. Output must come from Claude Code (`/security scan
...`), the CLI (`node scanners/...`), or stub fixtures. Demo state only
contains the 3 inline projects; new projects are per-user and stored
locally.
---
## Self-scan
### Test suite
The whole suite runs from a clean clone with one command, and no CI runs it for
you — this forge has no Actions runner, so the only run that exists is the one
you start:
```bash
npm test # node --test 'tests/**/*.test.mjs'
```
Running `node scanners/scan-orchestrator.mjs .` on a fresh clone produces **WARNING 61/100 with 58 findings** (0 critical, 5 high, 15 medium, 2 low, 36 info; measured 2026-09-22 on the release commit), after `.llm-security-ignore` suppresses the rest. Without the ignore file the same run reports BLOCK 95/100. The number of suppressed findings is not given because it changes with every commit: `git-forensics` looks at the last 50 commits. A security plugin that documents attack patterns, ships a malicious demo, and tests against deliberately evil code triggers its own scanners; every suppression is explained in the file. What is left is reported on purpose: high-entropy strings in docs and the HTML report renderer, example and research domains in docs, three CLI tools that write to a path given on the command line, and memory findings on `CLAUDE.md` — it documents the hooks, but it is the file a poisoning would target, so it is not suppressed. Remove the ignore file and re-run to see the unsuppressed picture.
The `examples/malicious-skill-demo/` directory contains a deliberately malicious "Project Health Dashboard" plugin and a [full security assessment](examples/malicious-skill-demo/security-assessment.md). The combined LLM + deterministic pipeline produced **85 findings** (24 critical, 24 high, 20 medium, 6 low, 11 info) and verdict **BLOCK 100/100** — both layers independently maxed the risk score. A human reviewing the plugin's `README.md` and `SKILL.md` would likely miss most of them; the Unicode Tag steganography is literally invisible.
```bash
DEMO="$(node examples/malicious-skill-demo/materialize.mjs)" # writes the demo to a temp dir, prints the path
node scanners/scan-orchestrator.mjs "$DEMO" # ~5s
rm -rf "$(dirname "$DEMO")" # when you are done
```
For the full pipeline, materialize the same way and run `/security scan <printed path> --deep` in Claude Code.
### Other runnable examples
The `examples/` directory contains additional self-contained
demonstrations — each with `README.md`, fixture, run script, and
`expected-findings.md`:
- **`prompt-injection-showcase/`** — 61 payloads across 19 categories
fed to `pre-prompt-inject-scan`, `post-mcp-verify`, and
`pre-bash-destructive`. Run: `node examples/prompt-injection-showcase/run-showcase.mjs`
- **`lethal-trifecta-walkthrough/`** — 5-step Rule-of-Two demonstration
(WebFetch → Read .env → Bash curl POST + suppression follow-ups)
showing `post-session-guard` advisory firing on leg 3. State-isolated
via run-script PID. Run: `node examples/lethal-trifecta-walkthrough/run-trifecta.mjs`
- **`mcp-rug-pull/`** — 8-stage MCP description drift, each step under
the 10% per-update threshold but cumulatively >25% from baseline.
Demonstrates the v7.3.0 cumulative-drift advisory (E14, OWASP MCP05).
Cache isolated via `LLM_SECURITY_MCP_CACHE_FILE`. Run:
`node examples/mcp-rug-pull/run-rug-pull.mjs`
- **`supply-chain-attack/`** — two-layer demonstration: PreToolUse
hook blocks compromised `event-stream@3.3.6` and advises on
scope-hopping `@evilcorp/lodash`; offline `dep-auditor` flags 5
typosquats + a `postinstall: curl ... | sh` vector in the fixture
`package.json`. Run:
`node examples/supply-chain-attack/run-supply-chain.mjs`
- **`poisoned-claude-md/`** — 6 memory-poisoning detectors fire on a
fixture `CLAUDE.md` + agent file (E15 surface). Demonstrates
injection, shell-command, suspicious-URL, credential-path,
permission-expansion, and base64-encoded-payload detection. Run:
`node examples/poisoned-claude-md/run-memory-poisoning.mjs`
- **`bash-evasion-gallery/`** — one disguised variant per T-tag
(T1-T9) fed through `pre-bash-destructive`, verified BLOCK after
`bash-normalize` strips the evasion. T8 has its own BLOCK_RULE.
Run:
`node examples/bash-evasion-gallery/run-evasion-gallery.mjs`
- **`toxic-agent-demo/`** — single-component lethal trifecta detected
by the `toxic-flow-analyzer` (TFA). A fixture agent with
`tools: [Bash, Read, WebFetch]` covers all three trifecta legs
(untrusted input + sensitive data access + exfil sink), and the
fixture deliberately ships no `hooks/hooks.json` so TFA emits a
CRITICAL `Lethal trifecta:` finding without mitigation downgrade.
Uses `plugin.fixture.json` as the plugin marker so the example
doesn't trip `pre-write-pathguard` on `.claude-plugin/`. Maps to
ASI01 / ASI02 / ASI05 / LLM01 / LLM02 / LLM06. Run:
`node examples/toxic-agent-demo/run-toxic-flow.mjs`
- **`pre-compact-poisoning/`** — `pre-compact-scan` PreCompact hook
detecting both an injection pattern and a credential-shaped string
in a synthetic transcript across all three modes (off / warn /
block). The transcript is generated at runtime in a per-invocation
tempdir; the AWS-shaped key uses the same `'AK' + 'IA' + ...`
fragmentation idiom as `tests/e2e/attack-chain.test.mjs`, so the
source contains no literal credentials. Includes a benign-transcript
control case in block mode to prove the gate is not a brick wall.
Maps to LLM01 / LLM02 / ASI01 / AT-1 / AT-3. Run:
`node examples/pre-compact-poisoning/run-pre-compact-poisoning.mjs`
---
## Antivirus false positives
This repository is a security tool, so it contains detection rules and descriptions of attack
techniques: signature tables (regular expressions for known-bad code), knowledge files that explain
how prompt injection, exfiltration and persistence attacks work, and a demo of a malicious plugin.
Since v8.1.0 no payload sits on disk as a file that would run it. Test fixtures and the demo are
stored encoded or built from fragments, and exist only in a temp directory while a test or the demo
runs; `tests/av-surface.test.mjs` fails the suite if one comes back.
An antivirus product can still flag a file. Microsoft Defender Antivirus does not only match known
samples: it also uses local and cloud-based machine-learning models, behavior analysis and
heuristics ([Next-generation protection overview](https://learn.microsoft.com/defender-endpoint/next-generation-protection)).
A text file that explains many attack techniques in one place can be flagged although nothing in it
runs — a plain `SKILL.md` in another security repository was quarantined as
`Trojan:Script/Wacatac.H!ml`.
If Defender quarantines a file from this repository:
1. **Restore it:** Windows Security → Virus & threat protection → Protection history, select the
item, then **Restore** ([Restore quarantined files](https://learn.microsoft.com/defender-endpoint/restore-quarantined-files-microsoft-defender-antivirus)).
2. **Report the false positive** to Microsoft at <https://www.microsoft.com/wdsi/filesubmission>, so
Microsoft can review and correct the detection.
3. Open an issue in the marketplace repository with the file path and the detection name.
Excluding the folder is not recommended here, and Microsoft advises against it as a fix: "Every
exclusion is a protection gap that lowers your defenses, so use exclusions sparingly"
([Exclusions in Microsoft Defender Antivirus](https://learn.microsoft.com/defender-endpoint/microsoft-defender-antivirus-exclusions-overview)).
If you only want the scanners and hooks, a sparse checkout leaves knowledge files, tests, examples
and docs off disk (measured 2026-09-22: 285 of 677 files):
| `/security` | List the sub-commands |
| `/security scan [path\|url]` | Supply-chain gate; `--deep` adds the 14 deterministic scanners |
| `/security deep-scan [path]` | The 14 deterministic scanners only, with a synthesized report |
| `/security plugin-audit [path\|url]` | Plugin trust assessment |
| `/security mcp-audit [--live]` | Audit installed MCP server configs |
| `/security mcp-inspect` | Connect to running MCP servers and scan their live tool descriptions |
| `/security mcp-baseline-reset` | Reset the MCP drift baseline after a legitimate server upgrade |
| `/security ide-scan [target\|url]` | Scan VS Code (and forks) and JetBrains extensions, installed or by URL |
| `/security supply-check [path]` | Re-audit installed dependencies against blocklists, OSV.dev and typosquats |
| `/security posture` | Quick scorecard, 16 categories |
| `/security audit` | Full audit, A–F |
| `/security dashboard` | Posture across every project on the machine |
| `/security diff [path]` | New / resolved / unchanged findings against a baseline |
| `/security watch [path]` | Run `diff` on an interval |
| `/security registry` | Skill fingerprint registry |
| `/security clean [path]` | Fix what is safe to fix, ask about the rest (`--dry-run` to preview) |
| `/security harden [path]` | Generate a Grade A config |
| `/security threat-model` | Guided STRIDE × MAESTRO session, 15–30 min |
| `/security red-team` | 72 attack scenarios against the hooks |
| `/security pre-deploy` | Pre-deployment checklist |
Every report command also writes a self-contained HTML version and prints a link to it. Scanner-by-scanner detail: [`docs/scanner-reference.md`](docs/scanner-reference.md).
## For teams and CI
- **Policy as code** — `.llm-security/policy.json` travels with the repository: hook modes, thresholds, audit log path. A scanned *foreign* repository's own policy and ignore file are not applied, so it cannot suppress its findings. Known exceptions — a tarball or `git archive` export under your working directory, a Python venv, a `vendor/` folder — are listed under 8.1.2 in the changelog.
- **Runs without Claude Code** — `node bin/llm-security.mjs scan <target>` (also `deep-scan`, `posture`, `ide-scan`, `audit-bom`, `benchmark`); no API key needed. It is **not** air-gapped: OSV.dev lookups (package names and versions), `npm audit`/`pip-audit`, and DNS checks on URLs it finds reach the network, with no switch to turn them off. Block egress at the network layer if you need an offline run.
- **CI gates** — `--fail-on <severity>` exit codes, `--compact` output, SARIF 2.1.0. Templates for GitHub Actions, Azure DevOps and GitLab CI in [`ci/`](ci/); guide in [`docs/ci-cd-guide.md`](docs/ci-cd-guide.md).
- **Evidence** — JSONL audit trail with OWASP tags for your SIEM, CycloneDX 1.6 AI bill of materials, and posture checks mapped to EU AI Act, NIST AI RMF and ISO 42001.
## Antivirus and EDR alerts
This is a security tool. It ships regular expressions for known-bad code, knowledge files that explain how injection, exfiltration and persistence attacks work, and an encoded demo of a malicious plugin. Nothing in it is malware, but products that use machine learning and heuristics — Microsoft Defender among them ([next-generation protection](https://learn.microsoft.com/defender-endpoint/next-generation-protection)) — can still flag such text. A plain `SKILL.md` in another security repository has been quarantined as `Trojan:Script/Wacatac.H!ml`.
What still sits on disk as readable text, and is therefore the likeliest to be flagged: the regex signature tables in `scanners/commons/` (some name hacking tools as plain words), the attack descriptions in `knowledge/`, and the injection phrases and sample commands the examples feed to the hooks.
### What v8.0 → v8.1.2 did about it
All antivirus work landed in **v8.1.0**; v8.1.1 and v8.1.2 did not touch it. (v8.0.0 moved the detection tables, including the malware signatures, into the vendored `scanners/commons/` data that ships with the plugin.)
| Change (v8.1.0) | Effect |
|-----------------|--------|
| Test payloads are built at test time in a temp directory, from split strings or rot13 | No runnable malicious fixture is stored in the repository |
| The malicious-plugin demo and the poisoned `CLAUDE.md` example ship as encoded archives | They exist in decoded form only in a temp directory while you run them |
| Skill-scanner detection lists moved from an agent file to `knowledge/`; runnable one-liners in `knowledge/*.md` rewritten as descriptions | A quarantined knowledge file does not break the plugin; a quarantined agent file would |
| Download-into-shell literals removed from hook source | The hook that blocks these commands no longer contains one |
| Gate: [`tests/av-surface.test.mjs`](tests/av-surface.test.mjs) | The suite fails if a runnable payload file, a base64 shell-command blob, hidden Unicode (outside the commons conformance corpus), a known payload tree, or a payload literal in agents/commands/hooks returns to disk |
Detection is unchanged: the signature tables and the golden baseline are identical before and after.
**Not measured:** no clone or install has been tested against Defender on a Windows machine. "No alerts" is the design goal, not a verified result.
### If you get an alert
1. **Do not exclude the folder.** Microsoft advises against exclusions as a fix: "Every exclusion is a protection gap" ([exclusions overview](https://learn.microsoft.com/defender-endpoint/microsoft-defender-antivirus-exclusions-overview)).
2. **Report it to Microsoft as a false positive.**
- *Managed devices (Defender for Endpoint / Defender XDR):* your security team submits the file in the Defender portal under **Submissions → Files**, classified as **Clean (false positive)** ([how](https://learn.microsoft.com/defender-endpoint/admin-submissions-mde)).
- *Single machine:* restore it under Windows Security → Protection history ([how](https://learn.microsoft.com/defender-endpoint/restore-quarantined-files-microsoft-defender-antivirus)) and submit it at <https://www.microsoft.com/wdsi/filesubmission>.
3. **Email security@fromaitochitta.com** with the file path, the detection name, the plugin version (or commit), and the antivirus product and its signature version. The alert is handled as a bug: the goal is a patch release in which the file no longer trips the product, with the gate above extended so it stays that way. There is no SLA (see [`SECURITY.md`](SECURITY.md)).
If you only need the scanners and hooks, a sparse checkout keeps knowledge files, tests, examples and docs off disk:
```bash
git clone --filter=blob:none --no-checkout https://git.fromaitochitta.com/open/llm-security.git
@ -768,58 +141,87 @@ git sparse-checkout set scanners hooks
git checkout main
```
Cone mode also checks out the files at the repository root. Some scanners read data from
`knowledge/` (the typosquat lists, the attack simulator's scenarios); add `knowledge` to the `set`
line if you run those. A sparse checkout of your own clone does not change what
`claude plugin install` puts in the plugin cache.
The hooks do not need `knowledge`; add it to the `set` line for the typosquat checks, `ide-scan`, the skill registry and `red-team`. This affects your own clone only — not what `claude plugin install` puts in the plugin cache.
---
## Known limitations
## Recent versions
Prompt injection cannot be fully prevented with today's model architectures; motivated adaptive attackers defeat every published defense. This plugin raises the cost of an attack with independent layers — it does not guarantee against one.
| Version | Date | Highlights |
|---------|------|------------|
| **8.1.2** | 2026-09-22 | **Installed packages and plugin copies are foreign.** A target reached through a `node_modules` folder below the working directory, or one under the Claude Code plugin directory (`$CLAUDE_CONFIG_DIR/plugins`, default `~/.claude/plugins`), no longer counts as the caller's own tree, so its `.llm-security-ignore` and `.llm-security/policy.json` are ignored. The posture scanner gives NIST "Govern" credit for a `policy.json` only when the scan would honour it. Known open: a `git archive` export or unpacked tarball under the working directory, and install locations the rule does not name (a Python virtual environment, a `vendor/` folder), still count as own. Detection tables and hooks unchanged. 2328 tests, 0 fail. |
| **8.1.1** | 2026-09-22 | **Own-tree rule narrowed, v8.1.0 follow-ups.** A clone, submodule or worktree that sits *under* the working directory no longer counts as the caller's own tree, so its `.llm-security-ignore` and `.llm-security/policy.json` (incl. custom SIG rules) are ignored — the target must share the working directory's git root. `ci.failOn` / `ci.compact` in `policy.json` now have a real test. The README no longer states self-scan counts that change with every commit. Windows/Defender quarantine is still not measured. Detection tables and hooks unchanged. 2306 tests, 0 fail. |
| **8.1.0** | 2026-09-22 | **Antivirus surface.** Clone and install on Windows without Defender quarantining a file, with detection unchanged. No payload sits on disk as a file that would run it: test fixtures are built in a temp directory at test time, the malicious-skill demo ships encoded and is materialized on demand, and `tests/av-surface.test.mjs` fails the suite if a payload comes back. Skill-scanner detection lists moved from the agent file to `knowledge/`. New section [Antivirus false positives](#antivirus-false-positives). Scope fixes: a scanned repository's own `.llm-security-ignore` and `.llm-security/policy.json` are honoured only when it is your own working tree, so a foreign clone cannot suppress its findings or raise its thresholds. Remote scans accept HTTPS URLs on any host. Signature tables and golden baseline untouched. 2286 tests. |
| **8.0.0** | 2026-09-18 | **Breaking cleanup + detection tables on vendored commons data.** BREAKING: the four `LLM_SECURITY_*` mode env-vars deprecated in v7.3.0 are removed (`.llm-security/policy.json` is the only source; a removed variable is inert) and `riskScoreV1()` is deleted — see [Migrating to v8.0.0](#migrating-to-v800). The injection lexicon (83 patterns), codepoint carriers, `OWASP_MAP`, the 19 fixed secret shapes and the 7 SIG signatures are now built from the pull-only `scanners/commons/` subtree, each swap proven content-identical against a golden baseline; an unresolvable lexicon fails loudly on stderr instead of scanning with zero patterns. Fixes: `<script>` recall hole, two quadratic `hybrid-xss` patterns (whole-table ReDoS gate added), Yarn Berry + nested lockfile-v1 misses in `supply-check`, a second-occurrence strip miss in `content-extractor.mjs`, bare legacy OpenAI keys, a malformed-SIG-rule false-positive matcher, SARIF multi-OWASP tags. Commons conformance spec 1.1 implemented. 2253 tests. |
| **7.8.3** | 2026-07-18 | **Completion-review MEDIUM sweep — 47 verified fixes, no CRITICAL/HIGH.** 52 findings triaged (48 confirmed; 3 feature-requests + 1 non-defect scoped out; the #11 persistence detector and #27 AST-taint f-string recall deferred to v8). Supply-chain gate bypasses (npm bare-install blocklist skip, nested-key name derivation, yarn.lock false-BLOCK + Yarn Berry miss, `pip audit` no-op). Hook coverage (pathguard now `Edit|Write`; trifecta window no longer diluted by markers; pipe-to-shell interposition; bare provider-key patterns). Scanner robustness (HTML-pattern ReDoS 28s to 4ms; MCP-stdout memory exhaustion; VSIX redirect loop; scalar-policy TypeError; atomic cache writes). False positives/negatives (toxic-flow substring trifectas, TRG scoped-phrase FPs, leading-BOM HIGH, bare-`if:` Dependabot-spoof FN, reflog `reset` FP, diff duplicate-fingerprint mislabel, hex double-report). Parser divergence (YAML block-scalar key leak + indicators, ANSI-C octal/unicode, embedded-base64 to SIG, `.env.local` discovery). Docs consistency (scanner count 14, posture 16, red-team 72, SARIF version, dangling `ROADMAP.md`). Plus a live-protocol fix: `post-mcp-verify` now reads the PostToolUse `tool_response` field, so MCP-output injection scanning fires in live sessions. 2013 tests, 0 fail. |
| **7.8.2** | 2026-07-18 | **Silent-failure fixes from the completion review (HIGH).** Five defects, four sharing one failure mode: the check reported success without running. `hooks/scripts/pre-bash-destructive.mjs` did not block `rm -rf /` or `rm -rf ~` — the target alternation ended in a `\b` that cannot hold after a non-word character, so the bare forms the rule is named for fell through to WARN (exit 0, command executed) while `/etc` and `$HOME` blocked normally. `scanners/entropy-scanner.mjs` matched its test/fixture suppression against the **absolute** path, so any ancestor directory named `test`/`spec`/`fixture`/`mock` silenced every finding in the target and still returned status `ok`. `scanners/ide-extension-scanner.mjs` guarded only `parseVSCodeExtension`'s bare-`null` failure signal, not `parseIntelliJPlugin`'s truthy `{ manifest: null }`, so any malformed JetBrains plugin threw a TypeError that escaped `mapConcurrent`'s unguarded `Promise.all` and aborted the scan of every other extension. `scanners/content-extractor.mjs` detected obfuscated injections but did not remove them: a decoded-only `match[0]` never occurs in the raw text, so the literal replace was a no-op and the payload reached the LLM agent verbatim through `sanitized_content` — removal is now line-level, with unattributable multi-line payloads flagged `unstripped`. `scanners/lib/ide-extension-parser.mjs` emptied any plugin.xml field containing a character reference above `0x10FFFF`. No feature changes. 1901 tests, 0 fail. |
| **7.8.1** | 2026-07-18 | **Auto-cleaner command-injection fix (CRITICAL).** `scanners/auto-cleaner.mjs` syntax-checked candidate `.mjs`/`.js`/`.cjs` content via ``execSync(`node --check "${tmpPath}"`)``, where `tmpPath` derives from the untrusted scanned-repo **filename**. The v7.8.0 F-2 guard checks path containment but does not strip or quote shell metacharacters, so a file named ``x";<command>;".mjs`` closes the interpolated quote and injects a command — and `/security clean` runs live by default, making a hostile repository sufficient for arbitrary local command execution. Reproduced with a live PoC before the fix. Both subprocess sites (syntax check + the CLI scan-orchestrator fallback) now use `spawnSync` with an argv array, so no shell parses a path. Defense-in-depth: `applyFixes()` refuses findings whose `file` carries shell/control metacharacters, reported as `skipped`. Regression coverage is split across both layers so the guard cannot mask a re-introduced shell in the sink. No feature changes. 1865 tests, 0 fail. |
| **7.8.0** | 2026-06-20 | **TRG/SIG/AST deep-scan scanners.** Three new deterministic deep-scan scanners targeting the skills/agents attack surface, each with its own finding prefix, OWASP/AST mapping, policy block, and graceful-skip behaviour. **TRG** (`scanners/trigger-scanner.mjs`) inspects command/agent/skill `name` + `description` frontmatter for activation-surface abuse: `TRG-shadow` (name collides with a built-in and intercepts it), `TRG-baiting` (maximally-activating phrases that bait indiscriminate invocation), `TRG-broad` (generic name + universal-applicability claim); descriptions pass the decode pipeline first so obfuscated baiting still trips (LLM06/AST04). **SIG** (`scanners/signature-scanner.mjs`) is a pure-Node known-malware *identity* engine (webshells, reverse shells, cryptominers, hacktools) that tests each signature against both raw bytes and the decode pipeline (base64/hex/url/entity/unicode, homoglyph fold, rot13), so obfuscated known-malware a byte-matcher misses is still caught; rules ship in `knowledge/signatures.json` (LLM03/LLM02). **AST** (`scanners/ast-taint-scanner.mjs`) shells out to a PARSE-ONLY `python3` helper (`scanners/lib/py-ast-taint.py`) for variable-level, scope-aware Python taint analysis — higher recall than the ~70% regex `taint-tracer.mjs` — and falls back to the regex tracer when `python3` is unavailable, so the scan never hard-fails; the helper only `ast.parse`s the target and never executes it (LLM01/LLM02/AST02). Built behind a security-fix gate (F-1/F-2/F-3 shell-injection + path-traversal fixes landed first). 1863 tests, 0 fail. |
| **7.7.2** | 2026-05-19 | **Language consistency pass.** Norwegian had crept into surface text across v7.5-v7.7. Per the `~/.claude/CLAUDE.md` convention (English for code and documentation, Norwegian for dialog only), this release translates: the HTML Report-step appended by all 18 skill commands, the canonical CLI renderer `scripts/lib/report-renderers.mjs` (display strings + JS comments), the playground UI strings, the `skill-scanner-agent` and `mcp-scanner-agent` system prompts, the Recent versions table and playground architecture prose in this README, the v7.7.x highlights in `CLAUDE.md`, and the llm-security entries in the marketplace root `README.md` + `CLAUDE.md`, plus six table cells in `docs/scanner-reference.md`. Demo-state fixture content for the `dft-komplett-demo` project (intentional Norwegian persona) and regex alternations that match Norwegian-language report markdown (`/^high\|^høy/`, `/resolution\|løsning/`) were preserved. No scanner, hook, or behavior changes — purely surface text. |
| **7.7.1** | 2026-05-18 | **Playground UX strip.** Operator feedback immediately after v7.7.0: the home surface led with three project tracks (Re-onboard / New project / Command catalog) even though the catalog was the important entry point. Minimum strip delivered as three atomic commits (`b732eee` + `2a6f73f` + `81b7beb`): (1) the router always forces `activeSurface = 'catalog'` (the onboarding/home/project render functions are preserved in source but no longer routable); (2) the topbar `Home` and `Re-onboard` buttons removed, `Catalog` retained; (3) the breadcrumb org-name (`shared.organization.name` from demo state) replaced with a static `llm-security` neutral scope anchor. Fix: the hardcoded `'Plugin v7.6.1'` on line 6933 of `renderHome` (template literal not caught by the v7.7.0 grep) was synced. The onboarding concept is documented as a v7.8.0 candidate (per-command context injection). No scanner or hook behavior changes. |
| **7.7.0** | 2026-05-18 | **HTML report for all 18 skill commands.** Every `/security <cmd>` that produces a report now prints a clickable `file://` link to a self-contained HTML version. Delivered across 5 sessions. (1) Playground catalog list-view + builder-pane with a copy button. (2) Playground project-surface cleanup (stub-screen handling, topbar split). (3) The 18 inline parsers + renderers in the playground HTML were moved to a canonical ESM module `scripts/lib/report-renderers.mjs` (the playground keeps a bit-identical inline copy since ESM `import` does not work from `file://`). (4) New zero-dep CLI `scripts/render-report.mjs` — stdin/file/stdout mode, kebab→camel commandId routing, inlines 6 DS stylesheets + a local `.report-table` CSS, ~140 KB self-contained HTML, system-font fallback, absolute `file://` paths for Ghostty cmd-click. (5) All 18 skills wired (4 in session 4: scan/audit/posture/deep-scan; 14 in session 5: plugin-audit/mcp-audit/mcp-inspect/ide-scan/supply-check/dashboard/pre-deploy/diff/watch/registry/clean/harden/threat-model/red-team). Output: `reports/<command>-<YYYYMMDD-HHmmss>.html` relative to CWD. No scanner or hook behavior changes — purely additive. |
| **7.6.1** | 2026-05-06 | **Playground v7.6.0 visual patch.** Six bugs caught during maintainer verification in the browser. All were mismatches between DS classes and renderer usage (or missing DS implementations the playground assumed existed). (1) `renderFindingsBlock` used the `.findings` outer class, which is the DS 2-column list+detail grid → replaced with `<section class="report-meta">` + the correct `findings__list > findings__group` pattern. (2) `.report-table` was missing entirely from the DS but used in 7+ renderers → local CSS implementation in the playground HTML. (3) `renderPreDeploy` traffic-lights used `.sm-card__grade` (28×28 px for one A-F letter) for "PASS"/"PASS-WITH-NOTES"/"FAIL" → replaced with a width-adapting status pill. (4) Threat-model matrix bubbles were not clickable → `<button>` with `data-threat-id` + click handler that scrolls to the Threats table. (5) Radar labels overlapped at 6+ axes → SVG 280→380, R 105→125, dynamic `text-anchor` (start/end/middle) based on horizontal position. (6) `recommendation-card__body` overflow on long text → `overflow-wrap: anywhere`. 4/4 fix-specific smoke tests + 18/18 renderer regression passing. No scanner or hook behavior changes — purely additive surface. |
| **7.6.0** | 2026-05-06 | **Playground Tier 3 reference case.** The playground (`playground/llm-security-playground.html`) raised to a visually and structurally complete reference for the `shared/playground-design-system/` Tier 3 supplement. 8 new DS components integrated into the 18 report renderers: `tfa-flow` + `tfa-leg` + `tfa-arrow` (lethal trifecta chain with `<button>` elements + ARIA), `mat-ladder` + `mat-step` (5-step maturity ladder with thresholds 0/25/50/75/95% PASS), `suppressed-group` (narrative audit from `summary.narrative_audit.suppressed_findings`), `codepoint-reveal` + `cp-tag`/`cp-zw`/`cp-bidi` (Unicode steganography side-by-side), `top-risks` + `top-risk[data-severity]` (ranked top-findings listing, semantic `<ol>`), `recommendation-card[data-severity]` (severity-tinted advisory on `clean`/`harden`/`audit`/`posture`/`pre-deploy`/`plugin-audit`), `risk-meter` (0-100 band visualization across 5 archetypes), `card--severity-{level}` (severity-color modifier on findings cards). Wave 1: `badge--scope-security` (identity chip), `verdict-pill-lg` (DS Tier 3 pill), `form-progress` + `fp-step` (onboarding wizard). Removed ~30 duplicate CSS declarations (DS wins the cascade). 5 new DS helpers + `mapSeverityToCardLevel` + `parseNarrativeAudit`. File size 10209 → 10677 lines. Delivered across 5 sessions, atomic commits. A11Y report updated. No scanner or hook behavior changes — purely additive surface. |
| **7.5.0** | 2026-05-05 | **Playground.** Single-file SPA at `playground/llm-security-playground.html` (~10 200 lines) for onboarding, demos and workshop use without a Claude Code installation. Parsers + renderers for all 18 `produces_report=true` commands (Phase 2: 10 high-priority + Phase 3: 8 remaining: mcp-inspect, supply-check, pre-deploy, diff, watch, registry, clean, threat-model). 18 markdown test fixtures under `playground/test-fixtures/` as contract anchors. The complete demo project `dft-komplett-demo` has all 18 reports parsed inline. Vendor-synced design-system under `playground/vendor/` (checksum-locked). 9 Playwright-generated screenshots under `playground/screenshots/v7.5.0/`. 11 new `window` globals for testing/automation. 2 new `KEY_STATS_CONFIG` archetypes (`kanban-buckets`, `matrix-risk`). Bug-fix: `normalizeVerdictText` regex order updated so GO-WITH-CONDITIONS / CONDITIONAL / BETINGET no longer collapse to ALLOW. No scanner or hook behavior changes — purely additive surface. |
| **7.4.0** | 2026-05-05 | **Examples + e2e suite.** Seven runnable demonstration walkthroughs under `examples/` (`prompt-injection-showcase`, `lethal-trifecta-walkthrough`, `mcp-rug-pull`, `supply-chain-attack`, `poisoned-claude-md`, `bash-evasion-gallery`, `toxic-agent-demo`, `pre-compact-poisoning`) — each with `README.md`, runtime-isolated fixture, single-command run-script, and `expected-findings.md` testable contract. Three new `tests/e2e/` suites (attack-chain 17 tests + multi-session 9 tests + scan-pipeline 19 tests = +45 tests, total 1822) prove the framework works as a coordinated system, not just isolated units. No scanner or hook behavior changes — purely additive surface. Scanner `VERSION` constants synced across `dashboard-aggregator.mjs`, `posture-scanner.mjs`, `ide-extension-scanner.mjs`. |
| **7.3.1** | 2026-05-01 | **Stabilization patch.** Project repositioned as solo, stabilization-only, with explicit "fork & own" stance for enterprise features. New public docs: `CONTRIBUTING.md` (fork-and-own model), README "Project scope" section (out-of-scope table with commercial alternatives), updated `SECURITY.md` (v7.3.x supported, v7.0–v7.2 best-effort, < v7.0 EOL). Coherence: `package.json` files whitelist + `bugs` URL + repo URL fix; scanner `VERSION` constants synced across `dashboard-aggregator.mjs`, `posture-scanner.mjs`, `ide-extension-scanner.mjs`. Test ceiling raised on flaky pre-compact-scan timing test (500 ms → 1000 ms; design target unchanged). No behavior changes. |
| **7.3.0** | 2026-05-01 | **Batch C release.** Wave A (T7-T9 bash normalization + rot13 comment-block decoder), Wave B (`.gitattributes` post-clone advisory + npm scope-hop typosquat + GitHub/Forgejo workflow-scanner with 23-field blacklist + re-interpolation tracking + auth-bypass detection), Wave C (MCP cumulative-drift baseline + `/security mcp-baseline-reset`), Wave D (riskScoreV1 `@deprecated`; sandbox-architecture rationale docs; env-var deprecation runway to v8.0.0; CLAUDE.md hooks count + consistency test). 1665+ → 1777 tests. Wave E (additional attack-simulator scenarios) deferred indefinitely |
| **7.2.0** | 2026-04-29 | **Batch B release.** Critical-review B-tier scanner defects + v7.2.0 evasion-arsenal (PUA-A/B Unicode coverage, NFKC homoglyph fold, escalation-after-input window, markdown link-title + SVG `<desc>`/`<foreignObject>` + HTML comment extractors). Two-stage entropy context classification. v1→v2 risk-formula constants unified across docs. 8 new red-team scenarios (64 → 72). 1522 → 1665 tests |
| **7.1.0** | 2026-04-29 | **Critical-review patch.** Pathguard regex hole closed (`.env.production.local.backup`-class). Distributed-trifecta block-mode AND-gate removed. CaMeL claim toned down to honest "byte-fingerprint matching". Documentation honesty-sweep across 7 overclaim sites. 1487 → 1511 tests |
| Limit | What to do |
|-------|------------|
| A cloned repository's `CLAUDE.md` loads before any hook runs | Scan remotely first: `/security scan <url> --deep` |
| Regex cannot catch every novel phrasing of an injection | Add an ML classifier such as [parry-guard](https://github.com/vaporif/parry); they run side by side |
| Remote-scan clones run without an OS sandbox on Windows, and on Linux where `bwrap` is missing or blocked (Ubuntu 24.04+ by default) — only a warning is printed | Git hardening still applies; on Windows run Claude Code in WSL2 or Docker, on Ubuntu allow `bwrap` in AppArmor |
| RAG pipelines, LLM gateways, SSO/SCIM are outside a plugin's reach | Use platform or infrastructure tooling |
| Opus with extended context: subagents do not support it and fail | Run `/model Opus` before the security commands |
Design rationale: [`docs/defense-philosophy.md`](docs/defense-philosophy.md). Hardening guide: [`docs/security-hardening-guide.md`](docs/security-hardening-guide.md).
## Project scope
A solo open-source project in **stabilization mode** since 2026-05-01: bug and security fixes, Claude Code compatibility, knowledge-base refresh.
## Non-goals
Out of scope — fork and own them under MIT if you need them: web dashboards or fleet servers, an inline prompt firewall, real-time IDE scanning, compliance evidence packs, ticketing/chat connectors, hosted ML detectors, SSO/RBAC. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the fork-and-own guide.
## Verify it yourself
No CI runs the tests for you — this forge has no Actions runner. From a clean clone:
```bash
npm test # the full suite
node scanners/scan-orchestrator.mjs . # the plugin scanning itself
```
The self-scan is not clean on purpose: a tool that documents attacks and tests against hostile code trips its own scanners. `.llm-security-ignore` suppresses the expected findings and explains each one; delete it to see everything.
The encoded malicious-plugin demo is a realistic attack. LLM agents and deterministic scanners together find 85 issues and return BLOCK 100/100 (see its [assessment](examples/malicious-skill-demo/security-assessment.md)). The commands below run the deterministic half:
```bash
DEMO="$(node examples/malicious-skill-demo/materialize.mjs)" # decodes into a temp dir, prints the path
node scanners/scan-orchestrator.mjs "$DEMO"
rm -rf "$(dirname "$DEMO")"
```
For the full pipeline, run `/security scan <printed path> --deep` in Claude Code before removing the directory.
More runnable demonstrations — injection showcase, trifecta walkthrough, MCP rug pull, supply-chain attack, bash evasion — are in [`examples/`](examples/).
## Upgrading from v7
v8.0.0 removed four environment variables. A removed variable is **silently ignored** — `LLM_SECURITY_INJECTION_MODE=off` no longer turns anything off. Find them before you upgrade:
```bash
env | grep '^LLM_SECURITY_\(INJECTION_MODE\|TRIFECTA_MODE\|ESCALATION_WINDOW\|AUDIT_LOG\|DEPRECATION_QUIET\)='
grep -rn 'LLM_SECURITY_\(INJECTION_MODE\|TRIFECTA_MODE\|ESCALATION_WINDOW\|AUDIT_LOG\)' \
~/.zshenv ~/.bashrc .envrc .github/workflows/ 2>/dev/null
```
Move each one into `.llm-security/policy.json`:
| Removed env var | Policy key | Default |
|-----------------|------------|---------|
| `LLM_SECURITY_INJECTION_MODE` | `injection.mode` | `block` |
| `LLM_SECURITY_TRIFECTA_MODE` | `trifecta.mode` | `warn` |
| `LLM_SECURITY_ESCALATION_WINDOW` | `trifecta.escalation_window` | `5` |
| `LLM_SECURITY_AUDIT_LOG` | `audit.log_path` | unset (off) |
`LLM_SECURITY_DEPRECATION_QUIET` is gone with the warning it silenced. Details in [`CHANGELOG.md`](CHANGELOG.md) under 8.0.0.
## Changelog
See [`CHANGELOG.md`](CHANGELOG.md) for the full history.
- **8.1.2** (2026-09-22) — Installed packages (`node_modules`) and Claude Code's plugin directory count as foreign, so their ignore and policy files are not applied.
- **8.1.1** (2026-09-22) — A clone, submodule or worktree *under* your working directory counts as foreign.
- **8.1.0** (2026-09-22) — Antivirus surface (see above); a scanned foreign repository's own ignore and policy files are no longer applied.
- **8.0.0** (2026-09-18) — Breaking cleanup (see [Upgrading from v7](#upgrading-from-v7)); detection tables built from shared, versioned data.
---
Full history: [`CHANGELOG.md`](CHANGELOG.md).
## License & attribution
## License and contact
MIT. See [`LICENSE`](LICENSE).
MIT — see [`LICENSE`](LICENSE). Built on published research from OWASP, ToxicSkills, ClawHavoc, MCPTox, Pillar Security, Invariant Labs, GHSL Security Lab, Operant AI and Google DeepMind; sources are cited in `knowledge/`.
Built on published research from OWASP, ToxicSkills (Xi'an Jiaotong, 2025), ClawHavoc (Repello AI, 2025), MCPTox, Pillar Security, Invariant Labs, GHSL Security Lab, Operant AI, and Google DeepMind's AI Agent Traps taxonomy. Threat patterns and case studies in `knowledge/` are cited inline.
---
## Feedback & contributing
- **Bug reports + feature requests:** open an issue on Forgejo
- **Pull requests:** not accepted on this repo (solo project, dialog-driven
development with Claude Code). For larger changes, see
[`CONTRIBUTING.md`](CONTRIBUTING.md) and the **fork-and-own** model
- **Security disclosures:** see [`SECURITY.md`](SECURITY.md) — please email,
do not open a public issue
- **Project scope:** see "Project scope" section above for what is and
isn't on the roadmap, and what to fork for instead
- **Security vulnerabilities and antivirus alerts:** security@fromaitochitta.com — not a public issue. See [`SECURITY.md`](SECURITY.md).
- **Bugs and feature requests:** open an issue in the [marketplace repository](https://git.fromaitochitta.com/open/ktg-plugin-marketplace).
- **Pull requests:** not accepted; see [`CONTRIBUTING.md`](CONTRIBUTING.md).