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

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

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>:

{
  "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:

# From your project root:
cp -r <plugin-root>/skills/ .github/skills/

Or symlink for shared use across projects:

macOS / Linux:

ln -s <plugin-root>/skills .github/skills

Windows (PowerShell, run as admin):

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:

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:

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:

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