docs(llm-security-copilot): add INSTALL.md with setup instructions
Step-by-step guide for Windows/macOS/Linux: prerequisites, hooks registration, skills/agents setup, scanner CLI usage, env vars, troubleshooting. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen
parent
f418a8fe08
commit
f778558d40
1 changed files with 190 additions and 0 deletions
190
plugins/llm-security-copilot/INSTALL.md
Normal file
190
plugins/llm-security-copilot/INSTALL.md
Normal file
|
|
@ -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\<username>\.copilot\plugins\llm-security\
|
||||
```
|
||||
|
||||
**macOS / Linux:**
|
||||
```
|
||||
~/.copilot/plugins/llm-security/
|
||||
```
|
||||
|
||||
The rest of this guide uses `<plugin-root>` to refer to this directory.
|
||||
|
||||
## Step 2: Verify Node.js scanners work
|
||||
|
||||
```bash
|
||||
node <plugin-root>/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 <plugin-root>
|
||||
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 `<plugin-root>`:
|
||||
|
||||
```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 <plugin-root>/skills/ .github/skills/
|
||||
```
|
||||
|
||||
Or symlink for shared use across projects:
|
||||
|
||||
**macOS / Linux:**
|
||||
```bash
|
||||
ln -s <plugin-root>/skills .github/skills
|
||||
```
|
||||
|
||||
**Windows (PowerShell, run as admin):**
|
||||
```powershell
|
||||
New-Item -ItemType SymbolicLink -Path .github\skills -Target <plugin-root>\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 <plugin-root>/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 <plugin-root>/.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 <plugin-root>/scanners/posture-scanner.mjs /path/to/project
|
||||
|
||||
# Full 10-scanner orchestrated scan
|
||||
node <plugin-root>/scanners/scan-orchestrator.mjs /path/to/project
|
||||
|
||||
# Save results to file
|
||||
node <plugin-root>/scanners/scan-orchestrator.mjs /path/to/project --output-file report.json
|
||||
|
||||
# Red-team attack simulation (64 scenarios)
|
||||
node <plugin-root>/scanners/attack-simulator.mjs
|
||||
|
||||
# Live MCP server inspection
|
||||
node <plugin-root>/scanners/mcp-live-inspect.mjs
|
||||
|
||||
# Machine-wide security dashboard
|
||||
node <plugin-root>/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 `<plugin-root>` 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue