diff --git a/plugins/llm-security-copilot/INSTALL.md b/plugins/llm-security-copilot/INSTALL.md new file mode 100644 index 0000000..bafe073 --- /dev/null +++ b/plugins/llm-security-copilot/INSTALL.md @@ -0,0 +1,190 @@ +# Installation Guide — LLM Security for GitHub Copilot CLI + +## Prerequisites + +- **Node.js >= 18** — verify with `node --version` +- **GitHub Copilot CLI** — verify with `copilot --version` + +## Step 1: Extract + +Extract the zip to a permanent location. Recommended: + +**Windows:** +``` +C:\Users\\.copilot\plugins\llm-security\ +``` + +**macOS / Linux:** +``` +~/.copilot/plugins/llm-security/ +``` + +The rest of this guide uses `` to refer to this directory. + +## Step 2: Verify Node.js scanners work + +```bash +node /scanners/posture-scanner.mjs . +``` + +You should see JSON output with a `scoring.grade` field (A-F). If this works, all 20 scanners will work — they share the same runtime. + +## Step 3: Run the verification tests + +```bash +cd +node tests/copilot-port-verify.mjs +``` + +Expected: **17/17 PASS**. This confirms hooks, protocol translation, and blocking behavior all work correctly on your platform. + +## Step 4: Hooks + +Hooks provide real-time protection — they block dangerous operations before they execute. + +### Option A: Project-level hooks + +Copy `hooks/hooks.json` into your project's Copilot hooks configuration. Adjust the `command` paths to point to ``: + +```json +{ + "version": 1, + "hooks": { + "preToolUse": [ + { + "matcher": "bash", + "hooks": [{ + "type": "command", + "command": "node C:/Users/you/.copilot/plugins/llm-security/hooks/scripts/copilot-hook-runner.mjs pre-bash-destructive.mjs" + }] + } + ] + } +} +``` + +### Option B: Global hooks (all projects) + +If Copilot CLI supports global hook configuration, register `hooks/hooks.json` at the user level. Consult Copilot CLI documentation for the current global hooks path. + +### What the hooks protect + +| Hook | Blocks | +|------|--------| +| `pre-prompt-inject-scan` | Prompt injection patterns (OWASP LLM01) | +| `pre-edit-secrets` | API keys, tokens, passwords in file writes | +| `pre-bash-destructive` | `rm -rf /`, pipe-to-shell, fork bombs | +| `pre-install-supply-chain` | Compromised packages across 7 ecosystems | +| `pre-write-pathguard` | Writes to `.env`, `.ssh/`, `.aws/`, credentials | +| `post-mcp-verify` | Injection and data leakage in tool output | +| `post-session-guard` | Lethal trifecta detection (untrusted input + sensitive data + exfiltration) | +| `update-check` | Version check (max 1x/24h, disable with `LLM_SECURITY_UPDATE_CHECK=off`) | + +## Step 5: Skills + +Skills are interactive commands you invoke from the Copilot CLI prompt. + +Copy the `skills/` directory into your project: + +```bash +# From your project root: +cp -r /skills/ .github/skills/ +``` + +Or symlink for shared use across projects: + +**macOS / Linux:** +```bash +ln -s /skills .github/skills +``` + +**Windows (PowerShell, run as admin):** +```powershell +New-Item -ItemType SymbolicLink -Path .github\skills -Target \skills +``` + +### Key skills + +| Skill | What it does | +|-------|-------------| +| `security-posture` | Quick health check (< 2 sec) | +| `security-scan` | Full security scan | +| `security-audit` | Comprehensive audit with A-F grading | +| `security-deep-scan` | 10 deterministic scanners | +| `security-threat-model` | Interactive STRIDE/MAESTRO session | + +## Step 6: Agents + +Copy the `agents/` directory into your project: + +```bash +cp -r /agents/ .github/agents/ +``` + +Agents are invoked via `@agent-name` in Copilot CLI (e.g., `@skill-scanner`). + +## Step 7: Security instructions (optional) + +Copy the Copilot instructions file to your project: + +```bash +cp /.github/copilot-instructions.md .github/copilot-instructions.md +``` + +This adds security-conscious behavior guidelines to Copilot for your project. + +## Running scanners directly + +All scanners are standalone Node.js CLI tools. No Copilot CLI required: + +```bash +# Quick posture check +node /scanners/posture-scanner.mjs /path/to/project + +# Full 10-scanner orchestrated scan +node /scanners/scan-orchestrator.mjs /path/to/project + +# Save results to file +node /scanners/scan-orchestrator.mjs /path/to/project --output-file report.json + +# Red-team attack simulation (64 scenarios) +node /scanners/attack-simulator.mjs + +# Live MCP server inspection +node /scanners/mcp-live-inspect.mjs + +# Machine-wide security dashboard +node /scanners/dashboard-aggregator.mjs +``` + +## 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 | + +## Windows notes + +Everything is pure Node.js — no bash, no shell-specific syntax. Verified cross-platform: + +- Paths use `node:path` (handles `\` vs `/`) +- Temp files use `os.tmpdir()` (maps to `%TEMP%`) +- Node spawning uses `process.execPath` (no PATH dependency) + +**Known limitation:** OS-level sandbox for git clone (`sandbox-exec` on macOS, `bubblewrap` on Linux) is not available on Windows. Remote repo scanning falls back to git config flags only. + +## Troubleshooting + +**Hooks don't trigger:** +Verify hook registration by intentionally writing a secret pattern. The pre-edit-secrets hook should block it. + +**Scanner fails with module not found:** +Ensure you're running from `` or using absolute paths. Scanners use relative imports to `scanners/lib/`. + +**Permission errors on Windows:** +Run PowerShell as administrator for symlink creation. Regular user permissions are sufficient for everything else. + +**Tests fail:** +Run `node --version` — must be >= 18.0.0. If a specific test fails, check the test output for which hook/scanner is affected.