ktg-plugin-marketplace/plugins/llm-security-copilot/README.md

# LLM Security for GitHub Copilot CLI

Security scanning, auditing, and threat modeling for AI coding agent projects. Port of [claude-code-llm-security](https://git.fromaitochitta.com/open/claude-code-llm-security) v5.1.0 for GitHub Copilot CLI.

5 frameworks: OWASP LLM Top 10 (2025), Agentic AI Top 10 (ASI), Skills Top 10 (AST), MCP Top 10, DeepMind AI Agent Traps.

## Installation

Extract the zip to your Copilot CLI plugins directory, or install from a marketplace:

```bash
copilot plugin install llm-security
```

**Requirements:** Node.js >= 18, GitHub Copilot CLI

## What's Protected (Hooks)

These hooks run automatically on every operation:

| Hook | Event | Purpose |
|------|-------|---------|
| `pre-prompt-inject-scan` | userPromptSubmitted | Block prompt injection, warn on manipulation patterns |
| `pre-edit-secrets` | preToolUse (edit\|create) | Block credentials in file writes |
| `pre-bash-destructive` | preToolUse (bash) | Block rm -rf, curl\|sh, fork bombs, eval injection |
| `pre-install-supply-chain` | preToolUse (bash) | Block compromised packages across 7 ecosystems |
| `pre-write-pathguard` | preToolUse (create) | Block writes to .env, .ssh/, .aws/, credentials |
| `post-mcp-verify` | postToolUse | Scan all tool output for injection and data leakage |
| `post-session-guard` | postToolUse | Runtime trifecta detection, behavioral drift monitoring |
| `update-check` | userPromptSubmitted | Check for newer versions (max 1x/24h) |

## Skills

| Skill | Description |
|-------|-------------|
| `security` | Help index — lists all available skills |
| `security-scan` | Scan files, directories, or repos for security issues |
| `security-deep-scan` | 10 deterministic Node.js scanners |
| `security-audit` | Full project audit with A-F grading |
| `security-posture` | Quick scorecard (< 2 sec) |
| `security-plugin-audit` | Plugin trust assessment before installation |
| `security-mcp-audit` | MCP server configuration audit |
| `security-mcp-inspect` | Live MCP server inspection |
| `security-threat-model` | Interactive STRIDE/MAESTRO session |
| `security-diff` | Compare against stored baseline |
| `security-watch` | Continuous monitoring on interval |
| `security-clean` | Scan and remediate findings |
| `security-supply-check` | Re-audit installed dependencies |
| `security-dashboard` | Machine-wide posture overview |
| `security-harden` | Generate Grade A configuration |
| `security-red-team` | Attack simulation (64 scenarios, 12 categories) |
| `security-pre-deploy` | Pre-deployment checklist |
| `security-registry` | Skill signature registry |

## Agents

| Agent | Role |
|-------|------|
| `skill-scanner` | 7 threat categories for skills/commands/agents |
| `mcp-scanner` | 5-phase MCP server analysis |
| `posture-assessor` | 13-category posture scorecard |
| `deep-scan-synthesizer` | Scanner JSON to human-readable report |
| `threat-modeler` | Interactive STRIDE/MAESTRO interview |
| `cleaner` | Semi-auto remediation proposals |

## Scanners

10 orchestrated deterministic scanners + 5 standalone + 5 supporting. All pure Node.js, zero npm dependencies.

**Orchestrated (via `scan-orchestrator.mjs`):**
Unicode, entropy, permission mapping, dependency audit, taint tracing, git forensics, network mapping, memory poisoning, supply chain recheck, toxic flow analysis.

**Standalone:**
`posture-scanner.mjs`, `mcp-live-inspect.mjs`, `watch-cron.mjs`, `reference-config-generator.mjs`, `dashboard-aggregator.mjs`, `attack-simulator.mjs`

Run any scanner directly:
```bash
node scanners/scan-orchestrator.mjs <target> [--output-file <path>]
node scanners/posture-scanner.mjs [path]
node scanners/attack-simulator.mjs [--adaptive]
```

## Knowledge Base (14 files)

OWASP LLM Top 10, Agentic AI Top 10, Skills Top 10, MCP threat patterns, secret patterns, mitigation matrix, attack scenarios, DeepMind Agent Traps, and more.

## Architecture

```
llm-security-copilot/
├── plugin.json              # Copilot CLI plugin manifest
├── hooks/
│   ├── hooks.json           # Copilot hook registration (v1 format)
│   └── scripts/
│       ├── copilot-hook-runner.mjs  # Protocol translator (Copilot ↔ Claude Code)
│       ├── lib/             # Adapter utilities
│       └── *.mjs            # Original hook scripts (unmodified)
├── skills/                  # 18 skills (SKILL.md format)
├── agents/                  # 6 agent definitions (.agent.md format)
├── scanners/                # 20 Node.js scanners (unchanged)
├── knowledge/               # 14 threat intelligence files (unchanged)
└── templates/               # Report templates (unchanged)
```

### Hook Architecture

The `copilot-hook-runner.mjs` wrapper translates between Copilot CLI and Claude Code hook protocols:

1. **Input normalization (Copilot → Claude Code):**
   - `{ toolName, toolArgs }` → `{ tool_name, tool_input }`
   - `{ toolResult }` → `{ tool_output }`
   - Nested: `{ filePath, newString }` → `{ file_path, new_string }`
   - Prompt events: `{ message: "text" }` → `{ message: { role: "user", content: "text" }, prompt: "text" }`
2. **Execution:** Original hook script runs with normalized input
3. **Output normalization (Claude Code → Copilot):**
   - `{ decision: 'block' }` → `{ permissionDecision: 'deny' }`
   - `{ systemMessage }` → `{ message }`
   - Stderr-only hooks (exit 2): generates `{ permissionDecision: 'deny', message, reason }` from stderr
4. **Exit code:** Preserved (0 = allow, 2 = block)

This means the original hook scripts run **unmodified** — all 1147 tests pass against the same code.

### Verification Tests

Run `node tests/copilot-port-verify.mjs` to verify the port. 17 tests covering:
- Protocol translation (camelCase → snake_case, nested fields)
- Output format (permissionDecision, message, JSON structure)
- All hook blocking categories (secrets, paths, destructive commands, supply chain, prompt injection)
- Copilot-specific prompt field normalization (`message` string → `message.content` object)

## Windows Compatibility

All hooks and scanners are pure Node.js and run on Windows, macOS, and Linux:

- Path handling uses `node:path` (cross-platform)
- Temp files use `os.tmpdir()` (maps to `%TEMP%` on Windows)
- No shell-specific syntax (no bash, no /dev/null)
- `copilot-hook-runner.mjs` uses `process.execPath` to spawn node (no PATH dependency)

**Known limitation:** The `sandbox-exec` git clone sandboxing (macOS-only) and `bubblewrap` (Linux) are not available on Windows. Git clone for remote scanning falls back to git config flags only on Windows.

## Environment Variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `LLM_SECURITY_INJECTION_MODE` | `block` | Prompt injection: block / warn / off |
| `LLM_SECURITY_TRIFECTA_MODE` | `warn` | Session trifecta: block / warn / off |
| `LLM_SECURITY_UPDATE_CHECK` | (enabled) | Set to `off` to disable update checks |

## License

MIT

## Origin

Port of [claude-code-llm-security](https://git.fromaitochitta.com/open/claude-code-llm-security) v5.1.0 by Kjell Tore Guttormsen.