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

# 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.