shield-llm 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# shield-llm
+
+**Automated red teaming for AI chatbots — from your terminal.**
+
+`shield-llm` scans a chatbot (any HTTP endpoint, or an LLM provider directly)
+against a catalogue of prompt-injection, jailbreak, data-extraction, excessive-
+agency, RAG, supply-chain and multi-turn attacks mapped to the **OWASP LLM Top
+10 (2025)**. It produces a security score, a letter grade, and reports in JSON,
+Markdown, SARIF, or PDF — ready for CI/CD.
+
+## How it works (thin client)
+
+The CLI is a thin client. It authenticates against a Shield LLM backend, pulls
+the plan-filtered attack catalogue, sends each attack prompt to **your** target
+chatbot, and posts the responses back to the backend, which runs an LLM judge
+and scores them. The CLI itself contains no attack payloads and no scoring
+logic — so adding new attacks server-side reaches every install instantly, with
+no upgrade.
+
+> A backend connection is required. Two modes, same binary:
+> - **SaaS** — `https://shield-llm.com` (default)
+> - **License / self-hosted** — your own instance via `--api-url`
+
+## Install
+
+```bash
+npm install -g shield-llm
+# or run once without installing:
+npx shield-llm --help
+```
+
+Requires Node.js >= 22. PDF reports need Puppeteer (installed automatically as
+an optional dependency; set `PUPPETEER_EXECUTABLE_PATH` to use a system Chrome).
+
+## Quick start
+
+```bash
+# 1. Authenticate with your API key (create one in your dashboard → Settings)
+shield-llm login --key sk_shield_xxxxxxxx
+#    self-hosted:
+shield-llm login --key <license-key> --api-url https://shield.your-corp.com
+
+# 2. Generate a config for your chatbot endpoint (interactive)
+shield-llm init
+
+# 3. Scan
+shield-llm scan --preset owasp
+```
+
+## Configuration
+
+`shield-llm init` writes a `shield.config.json` describing your endpoint:
+
+```json
+{
+  "endpoint": {
+    "url": "https://api.example.com/chat",
+    "request": { "method": "POST", "body": { "message": "{{prompt}}" } },
+    "response": { "field": "data.reply" }
+  },
+  "preset": "standard"
+}
+```
+
+- `{{prompt}}` is replaced with each attack. `{{history}}` is available for
+  multi-turn.
+- `response.field` is a dot-path into the JSON response (e.g.
+  `choices[0].message.content`). SSE streams are auto-detected.
+- Auth: `bearer`, `api-key`, or `oauth2` (use `$ENV_VAR` to read secrets from
+  the environment instead of hard-coding them).
+- CLI flags override config values.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `scan` | Run a security scan against a target chatbot |
+| `init` | Interactive wizard → generates `shield.config.json` |
+| `login` / `logout` | Manage your API key credentials |
+| `attacks` | List the live attack catalogue (from your backend) |
+| `presets` | List available scan presets |
+| `tests` | List custom tests (local config and/or `--remote`) |
+| `validate` | Validate a `shield.config.json` without scanning |
+| `report <scanId>` | Fetch a past scan from your dashboard |
+
+## Presets
+
+| Preset | Scope |
+|--------|-------|
+| `dev` | 3 tests — smoke test |
+| `quick` | 7 tests — fast triage |
+| `owasp` | 1 test per OWASP LLM Top 10 category |
+| `standard` | broad coverage |
+| `full` | full catalogue + multi-turn (crescendo / memory) attacks |
+
+Available presets depend on your plan; the backend filters them.
+
+## Key scan flags
+
+```
+--preset <name>            dev | quick | owasp | standard | full
+--endpoint <url>           target URL (overrides config)
+--system-prompt <text>     give the target's system prompt for context
+--crescendo                include multi-turn attacks
+--load-custom-tests        also run your dashboard's custom tests
+--eu-ai-act                print an EU AI Act compliance summary
+-o, --output <format>      json | markdown | sarif | pdf
+--output-file <path>       write the report to a file
+--min-score <n>            fail if score < n
+--fail-on-critical         fail if any CRITICAL finding
+--ci                       JSON to stdout, no spinner (logs to stderr)
+```
+
+## CI/CD
+
+```bash
+shield-llm scan --ci --min-score 80 --fail-on-critical \
+  --output sarif --output-file shield.sarif
+```
+
+Exit codes: `0` passed · `1` threshold violation · `2` config/auth error ·
+`3` runtime/network error. Upload the SARIF to GitHub's Security tab, or use
+`--write-json` to emit a parseable copy alongside any other format.
+
+## License
+
+MIT

package/bin/shield-llm.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.js";