fullcourtdefense-cli 1.7.22 → 1.7.24

package/README.md

@@ -1,690 +1,690 @@
-# FullCourtDefense CLI
-
-[Full Court Defense](https://fullcourtdefense.ai/) is an AI agent security platform and runtime firewall for teams shipping LLM apps, agentic workflows, MCP tools, and RAG systems. We help builders find and block prompt injection, jailbreaks, data exfiltration, unsafe tool use, and poisoned retrieval content before those failures reach production.
-
-The FullCourtDefense CLI brings that security workflow to your terminal. It can run hosted CI/CD scans against public agents, or local in-organization scans against private APIs, MCP servers, RAG document corpora, and live RAG services. Local scans execute from your machine or VPN, then send captured content outbound to your Shield for verdicts and saved web reports.
-
-## Install
-
-```bash
-npm install -g fullcourtdefense-cli
-# or run directly
-npx fullcourtdefense-cli scan
-```
-
-## Quick Start
-
-```bash
-# Show onboarding help
-fullcourtdefense help
-
-# 1. Check outbound HTTPS from the customer machine
-fullcourtdefense doctor
-
-# 2. Save Shield ID and Shield key
-fullcourtdefense configure
-
-# 3. Run an in-organization local scan with guided questions
-fullcourtdefense scan --local
-
-# 4. Run a detailed MCP report
-fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ./server.js --mcp-tool all --mode full --format report
-
-# Hosted CI/CD scan, if using an API key instead of local Shield scan
-fullcourtdefense scan --api-key YOUR_KEY --endpoint https://my-agent.com/chat --description "My chatbot"
-
-# Check remaining credits
-fullcourtdefense credits --api-key YOUR_KEY
-
-# Generate a config file
-fullcourtdefense init
-```
-
-## Command Guide
-
-- `fullcourtdefense help` — shows the full onboarding flow and command reference.
-- `fullcourtdefense doctor` — confirms outbound HTTPS to FullCourtDefense is open before scanning.
-- `fullcourtdefense configure` — saves Shield ID, Shield key, and API URL to `.fullcourtdefense.yml`.
-- `fullcourtdefense scan --local` — runs inside the customer network and asks whether to scan endpoint, MCP, or RAG.
-- `fullcourtdefense scan --local --type mcp ...` — launches a local stdio MCP server, calls tools, and sends tool responses to Shield.
-- `fullcourtdefense scan --local --type rag ...` — scans local RAG files/directories or a live RAG HTTP service.
-- `fullcourtdefense scan --local --type endpoint ...` — scans an internal HTTP/OpenAI-compatible endpoint.
-- `fullcourtdefense install-cursor-mcp-gateway ...` — registers the protected MCP gateway in Cursor.
-- `fullcourtdefense install-claude-code-mcp-gateway ...` — registers the protected MCP gateway in Claude Code.
-- `fullcourtdefense install-claude-desktop-mcp-gateway ...` — registers the protected MCP gateway in Claude Desktop.
-- `fullcourtdefense credits` — checks hosted scan credits for CI/CD API-key scans.
-- `fullcourtdefense discover` — scans local MCP client configs and reports risk; `--upload` sends desktop inventory to AI Inventory.
-- `fullcourtdefense init` — creates a starter config file.
-
-## Shadow AI / Desktop Discovery
-
-Find MCP servers configured on developer machines without reading chat history or spawning stdio servers by default:
-
-```bash
-# Scan this machine and print results
-fullcourtdefense discover
-
-# JSON output (includes host fingerprint + servers)
-fullcourtdefense discover --json
-
-# Upload to AI Inventory (requires CI/CD API key with audit:write)
-fullcourtdefense discover --upload --api-key YOUR_KEY
-
-# Live-probe HTTP/SSE MCP servers for tools/list (stdio stays config-only)
-fullcourtdefense discover --deep
-
-# Fleet / MDM script — silent upload with user attribution
-fullcourtdefense discover --upload --silent --user-email you@company.com --api-key YOUR_KEY
-
-# Daily automatic scan on this laptop (uses API key from env or ~/.fullcourtdefense.yml)
-fullcourtdefense discover --schedule daily --user-email you@company.com
-
-# Remove daily schedule
-fullcourtdefense discover --unschedule true
-
-# Scan an extra config path
-fullcourtdefense discover --path /path/to/mcp.json
-```
-
-Each upload includes host metadata (`machineId`, `hostname`, `platform`, `user`) so the same MCP server on different laptops appears as separate desktop inventory rows. The CLI is also available as `fcd` or `botguard` after global install.
-
-## Config File
-
-Create a `.fullcourtdefense.yml` to avoid passing flags every time:
-
-```yaml
-apiKey: ${FULLCOURTDEFENSE_API_KEY}
-apiUrl: https://api.fullcourtdefense.ai
-shieldId: sh_your_shield_id
-# shieldKey: shsk_optional_if_locked
-scan:
-  endpoint: https://my-agent.com/chat
-  description: "Customer support chatbot"
-  categories: [jailbreak, prompt_injection, data_extraction]
-  failThreshold: 80
-  format: table
-```
-
-Then just run:
-
-```bash
-fullcourtdefense scan
-```
-
-## Modes
-
-Hosted scans use a CI/CD API key and scan a public or reachable agent endpoint through the FullCourtDefense backend.
-
-| Mode | Use When | Behavior |
-|---|---|---|
-| `--mode sync` | Small hosted scans from CI or a terminal | Waits for the hosted scan result before exiting. |
-| `--mode async` | Longer hosted scans | Starts a hosted job, polls until complete, then prints the result. |
-
-Local scans run from the customer machine or VPN and only send captured text outbound to Shield for verdicts.
-
-| Mode | Use When | Behavior |
-|---|---|---|
-| `--mode quick` | Smoke test before a demo or install handoff | Runs a small default attack set. |
-| `--mode full` | Real evidence report | Runs the bundled 229+ attack corpus. |
-| `--mode targeted` | You know what the agent protects | Runs default plus targeted attacks and appends `--description` as focus context. |
-| `--mode deep` | Stress and broad regression testing | Runs the broad corpus plus deeper multi-step/stress cases. |
-
-## Full Option Reference
-
-### Global
-
-| Flag | Applies To | Description | Default |
-|---|---|---|---|
-| `--help`, `-h` | all commands | Show help. | — |
-| `--version`, `-v` | all commands | Print package version. | — |
-| `--config <path>` | scan/config | Path to `.fullcourtdefense.yml`, `.fullcourtdefense.yaml`, or legacy `.botguard.yml`. | auto-detect |
-| `--api-url <url>` | doctor/configure/scan | FullCourtDefense backend URL. | `https://api.fullcourtdefense.ai` |
-
-### Shield And Hosted API
-
-| Flag | Applies To | Description | Default |
-|---|---|---|---|
-| `--api-key <key>` | hosted scan/credits | Hosted scan API key. Can also use `FULLCOURTDEFENSE_API_KEY` or legacy `BOTGUARD_API_KEY`. | config/env |
-| `--shield-id <id>` | local scan | Shield ID from the Shield Integrate tab. Can also use `FULLCOURTDEFENSE_SHIELD_ID`, `FCD_SHIELD_ID`, or `AGENTGUARD_SHIELD_ID`. | config/env/prompt |
-| `--shield-key <key>` | local scan | Optional Shield key for locked Shields. Can also use `FULLCOURTDEFENSE_SHIELD_KEY`, `FCD_SHIELD_KEY`, or `AGENTGUARD_SHIELD_KEY`. | config/env/prompt |
-
-### Hosted Scan
-
-| Flag | Applies To | Description | Default |
-|---|---|---|---|
-| `--endpoint <url>` | hosted scan | Public/reachable AI agent API URL. | config |
-| `--description <text>` | hosted scan/local targeted | Agent description. For `--mode targeted`, also used as local focus context. | config |
-| `--system-prompt <text-or-path>` | hosted scan | System prompt text or path to a file. | config |
-| `--categories <list>` | hosted scan | Comma-separated attack categories. | all |
-| `--attack-count <n>` | hosted/local | Limit number of attacks. Useful for smoke tests. | mode default |
-| `--webhook-format <fmt>` | hosted scan | Webhook format: `n8n`, `make`, `zapier`, or `custom`. Legacy alias for local request format. | — |
-
-### Local Target Selection
-
-| Flag | Applies To | Description | Default |
-|---|---|---|---|
-| `--local` | scan | Run from this machine, inside the customer's network/VPN. | false |
-| `--type <type>` | local scan | Local target type: `endpoint`, `mcp`, or `rag`. | prompt |
-
-### Local HTTP API Endpoint
-
-| Flag | Applies To | Description | Default |
-|---|---|---|---|
-| `--endpoint <url>` | `--type endpoint` | Internal HTTP API URL, for example `http://agent.local/chat`. | prompt |
-| `--method <GET|POST>` | endpoint/rag-url | HTTP method. | prompt/`POST` |
-| `--request-format <fmt>` | endpoint/rag-url | Request body shape: `custom` or `openai`. | prompt/`custom` |
-| `--input-field <field>` | endpoint/rag-url | Request field that receives the attack prompt, for example `message`, `query`, `question`, or `input`. | `message` |
-| `--output-field <field>` | endpoint/rag-url | Response field containing the bot answer, for example `answer`, `response`, `text`, or `choices.0.message.content`. | auto-detect |
-| `--auth-type <type>` | endpoint/rag-url | HTTP auth type: `none`, `bearer`, `basic`, or `api-key`. | `none` |
-| `--username <user>` | endpoint/rag-url basic auth | Basic auth username. | prompt |
-| `--password <pass>` | endpoint/rag-url basic auth | Basic auth password. | prompt |
-| `--token <token>` | endpoint/rag-url bearer auth | Bearer token. | prompt |
-| `--api-key-header <header>` | endpoint/rag-url API-key auth | API key header name, for example `X-API-Key`. | `X-API-Key` |
-| `--endpoint-api-key <key>` | endpoint/rag-url API-key auth | API key value for the scanned endpoint. | prompt |
-
-### MCP
-
-| Flag | Applies To | Description | Default |
-|---|---|---|---|
-| `--mcp-command <cmd>` | stdio MCP | Command that starts the MCP server, for example `node`, `python`, or `npx.cmd`. | prompt |
-| `--mcp-args <args>` | stdio MCP | Args passed to `--mcp-command`, for example `.\dist\server.js`. JSON array strings are also supported. | empty |
-| `--mcp-url <url>` | HTTP/SSE MCP | Already-running MCP URL, for example `https://internal.company.com/mcp`. | prompt |
-| `--mcp-transport <t>` | MCP | Transport: `stdio`, `http`, or `sse`. HTTP/SSE can usually be inferred from `--mcp-url`. | inferred |
-| `--mcp-tool <tool>` | MCP | Tool to scan, or `all` to scan every listed tool. | `all` when destination is provided |
-| `--mcp-tool-args <json>` | MCP | Tool args JSON. Use `{{attack}}` anywhere the current attack prompt should be inserted. | `{}` |
-| `--mcp-auth-type <type>` | HTTP/SSE MCP | Auth type: `none`, `bearer`, `basic`, or `api-key`. | `none` |
-| `--mcp-token <token>` | HTTP/SSE MCP bearer auth | Bearer token. | prompt |
-| `--mcp-username <user>` | HTTP/SSE MCP basic auth | Basic auth username. | prompt |
-| `--mcp-password <pass>` | HTTP/SSE MCP basic auth | Basic auth password. | prompt |
-| `--mcp-api-key-header <header>` | HTTP/SSE MCP API-key auth | API key header name. | `X-API-Key` |
-| `--mcp-api-key <key>` | HTTP/SSE MCP API-key auth | API key value. | prompt |
-| `--progress <mode>` | MCP | Console progress: `verbose`, `compact`, or `silent`. | `verbose` |
-| `--server-name <name>` | MCP gateway installers | MCP server name to write into the client config. | `agentguard-gateway` |
-| `--developer-name <name>` | MCP gateway installers | Runtime identity used for user-scoped Action Policies. Auto-detected from `FCD_DEVELOPER_NAME`, git email, npm username, or OS username. | auto |
-| `--agent-name <name>` | MCP gateway installers | Runtime agent name shown in AI Users. Auto-generated from runtime identity plus client, e.g. `boaz.lautman-claude-desktop`. | auto |
-| `--scope <scope>` | Claude Code gateway installer | Claude Code MCP scope: `local`, `project`, or `user`. | `local` |
-| `--config-path <path>` | Claude Desktop gateway installer | Override path to `claude_desktop_config.json`. | OS default |
-
-### RAG
-
-| Flag | Applies To | Description | Default |
-|---|---|---|---|
-| `--rag-path <path>` | `--type rag` | Local RAG file or directory to scan as a corpus. Supports `.txt`, `.md`, `.json`, `.csv`, and `.html`. | prompt |
-| `--rag-url <url>` | `--type rag` | Live RAG HTTP endpoint to scan like an app. Uses the same HTTP flags as endpoint scans. | — |
-
-### Output And CI
-
-| Flag | Applies To | Description | Default |
-|---|---|---|---|
-| `--mode <mode>` | scan | Hosted: `sync`, `async`. Local: `quick`, `full`, `targeted`, `deep`. | hosted `sync`, local `quick` |
-| `--format <fmt>` | scan | Output: `table`, `summary`, `report`, `full-report`, or `json`. | hosted `table`, local `summary` |
-| `--fail-threshold <n>` | scan | Exit with code 1 if score is below this 0-100 threshold. | `0` |
-
-## Realistic Command Examples
-
-### First-Time Setup
-
-Run these on the same machine that can reach the customer's private agent, MCP server, or RAG service:
-
-```powershell
-fullcourtdefense doctor
-fullcourtdefense configure
-fullcourtdefense scan --local
-```
-
-Expected `doctor` output:
-
-```text
-BotGuard outbound diagnostic
-Target: https://api.fullcourtdefense.ai
-
-PASS outbound HTTPS open (200, 487ms)
-Checked: https://api.fullcourtdefense.ai/api/health/ping
-```
-
-### Hosted CI/CD Scan
-
-Use hosted scans when the agent endpoint is reachable by FullCourtDefense and you have a CI/CD API key.
-
-```powershell
-$env:FULLCOURTDEFENSE_API_KEY = "bg_live_..."
-fullcourtdefense scan --endpoint "https://support-bot.example.com/chat" --description "Customer support chatbot" --mode sync --format summary --fail-threshold 80
-```
-
-Async hosted scan for a longer job:
-
-```powershell
-fullcourtdefense scan --api-key "bg_live_..." --endpoint "https://agent.example.com/chat" --description "Production sales assistant" --mode async --format report
-```
-
-### Local Modes
-
-Use quick mode first:
-
-```powershell
-fullcourtdefense scan --local --type endpoint --endpoint "http://localhost:3000/chat" --method POST --request-format custom --input-field message --output-field response --mode quick --format report
-```
-
-Use full mode for evidence:
-
-```powershell
-fullcourtdefense scan --local --type endpoint --endpoint "http://localhost:3000/chat" --method POST --request-format custom --input-field message --output-field response --mode full --format report
-```
-
-Use targeted mode when you know the protected domain:
-
-```powershell
-fullcourtdefense scan --local --type endpoint --endpoint "http://localhost:3000/chat" --method POST --request-format custom --input-field message --output-field response --mode targeted --description "Healthcare support bot with patient records and billing data" --format report
-```
-
-Use deep mode for broad regression:
-
-```powershell
-fullcourtdefense scan --local --type endpoint --endpoint "http://localhost:3000/chat" --method POST --request-format custom --input-field message --output-field response --mode deep --format full-report
-```
-
-### Local API Endpoint Examples
-
-Typical Express/FastAPI app:
-
-```powershell
-fullcourtdefense scan --local --type endpoint --endpoint "http://127.0.0.1:8000/chat" --method POST --request-format custom --input-field message --output-field answer --mode full --format report
-```
-
-Query-style endpoint:
-
-```powershell
-fullcourtdefense scan --local --type endpoint --endpoint "http://127.0.0.1:8000/query" --method POST --request-format custom --input-field query --output-field result --mode full --format report
-```
-
-OpenAI-compatible endpoint:
-
-```powershell
-fullcourtdefense scan --local --type endpoint --endpoint "http://127.0.0.1:8000/v1/chat/completions" --method POST --request-format openai --mode full --format report
-```
-
-### MCP Examples
-
-Local stdio MCP server built from your repo:
-
-```powershell
-fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ".\dist\mcp-server.js" --mcp-tool all --mode full --format report
-```
-
-Filesystem MCP over `npx.cmd` on Windows:
-
-```powershell
-fullcourtdefense scan --local --type mcp --mcp-command npx.cmd --mcp-args "-y @modelcontextprotocol/server-filesystem C:\company\docs" --mcp-tool all --mode full --format report
-```
-
-Single MCP tool with attack inserted into an argument:
-
-```powershell
-fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ".\dist\mcp-server.js" --mcp-tool search_docs --mcp-tool-args '{ "query": "{{attack}}", "limit": 5 }' --mode quick --format report
-```
-
-Already-running HTTP MCP:
-
-```powershell
-fullcourtdefense scan --local --type mcp --mcp-url "http://127.0.0.1:5066/mcp" --mcp-tool all --mode full --format report
-```
-
-Secured HTTP MCP:
-
-```powershell
-fullcourtdefense scan --local --type mcp --mcp-url "https://mcp.internal.company.com/mcp" --mcp-auth-type bearer --mcp-token "mcp_token_..." --mcp-tool all --mode full --format report
-```
-
-### MCP Gateway Install Examples
-
-Use the MCP gateway when you want Cursor, Claude Code, or Claude Desktop tool calls checked against AgentGuard runtime/action policies before they reach the real MCP server.
-
-Cursor project install:
-
-```powershell
-fullcourtdefense install-cursor-mcp-gateway --project true --shield-id "sh_..." --shield-key "shsk_..." --mcp-command npm --mcp-args "run mcp"
-```
-
-Claude Code local install, private to you in the current project:
-
-```powershell
-fullcourtdefense install-claude-code-mcp-gateway --scope local --shield-id "sh_..." --shield-key "shsk_..." --mcp-command npm --mcp-args "run mcp"
-```
-
-Claude Code project install, shared through `.mcp.json`:
-
-```powershell
-fullcourtdefense install-claude-code-mcp-gateway --scope project --shield-id "sh_..." --mcp-command npm --mcp-args "run mcp"
-```
-
-Claude Desktop install:
-
-```powershell
-fullcourtdefense install-claude-desktop-mcp-gateway --shield-id "sh_..." --shield-key "shsk_..." --mcp-command npm --mcp-args "run mcp"
-```
-
-The gateway auto-detects runtime identity when `--developer-name` is omitted. Detection order is `FCD_DEVELOPER_NAME`, `FULLCOURTDEFENSE_DEVELOPER_NAME`, `AGENTGUARD_DEVELOPER_NAME`, `USER_EMAIL`, `git config user.email`, `npm whoami`, then OS username. Use `--developer-name` only when you want to override the detected employee/runtime identity.
-
-Direct gateway run for debugging:
-
-```powershell
-fullcourtdefense mcp-gateway --agent-client claude-code --shield-id "sh_..." --mcp-command npm --mcp-args "run mcp"
-```
-
-### RAG Examples
-
-Scan local documents before ingestion:
-
-```powershell
-fullcourtdefense scan --local --type rag --rag-path "C:\company\kb-docs" --mode full --format report
-```
-
-Scan one suspicious file:
-
-```powershell
-fullcourtdefense scan --local --type rag --rag-path ".\docs\release-notes.md" --mode quick --format report
-```
-
-Scan a live RAG service:
-
-```powershell
-fullcourtdefense scan --local --type rag --rag-url "http://127.0.0.1:5065/chat" --method POST --request-format custom --input-field message --output-field answer --mode full --format report
-```
-
-Scan an OpenAI-compatible RAG service:
-
-```powershell
-fullcourtdefense scan --local --type rag --rag-url "http://127.0.0.1:5065/v1/chat/completions" --method POST --request-format openai --mode full --format report
-```
-
-### Auth Examples
-
-Bearer auth for an internal agent:
-
-```powershell
-fullcourtdefense scan --local --type endpoint --endpoint "https://agent.internal/chat" --method POST --request-format custom --input-field message --output-field answer --auth-type bearer --token "eyJ..." --mode full --format report
-```
-
-Basic auth:
-
-```powershell
-fullcourtdefense scan --local --type endpoint --endpoint "https://agent.internal/chat" --method POST --request-format custom --input-field message --output-field answer --auth-type basic --username "scanner" --password "scanner-password" --mode full --format report
-```
-
-API key header:
-
-```powershell
-fullcourtdefense scan --local --type endpoint --endpoint "https://agent.internal/chat" --method POST --request-format custom --input-field message --output-field answer --auth-type api-key --api-key-header X-Internal-Key --endpoint-api-key "internal_key_..." --mode full --format report
-```
-
-### CI Gate Examples
-
-Fail the build if score is below 80:
-
-```powershell
-fullcourtdefense scan --api-key "$env:FULLCOURTDEFENSE_API_KEY" --endpoint "https://agent.example.com/chat" --description "Production support agent" --mode sync --format summary --fail-threshold 80
-```
-
-Local CI against a service started earlier in the job:
-
-```powershell
-fullcourtdefense scan --local --type endpoint --endpoint "http://127.0.0.1:3000/chat" --method POST --request-format custom --input-field message --output-field response --mode quick --format summary --fail-threshold 80
-```
-
-## In-Organization Local Scan
-
-Use local scan when the AI endpoint, MCP server, RAG service, or RAG corpus is only reachable from inside your organization. The CLI executes the local target, then sends the captured content outbound to your FullCourtDefense Shield for the real verdict.
-
-```bash
-fullcourtdefense scan --local
-```
-
-On first local scan, the CLI asks for your Shield ID and saves it to `.fullcourtdefense.yml`. You can also pass it directly:
-
-```bash
-fullcourtdefense scan --local --shield-id sh_your_shield_id
-```
-
-The CLI asks what to scan:
-
-- `endpoint` — internal HTTP API or OpenAI-compatible endpoint.
-- `mcp` — MCP destination. For stdio MCP, the destination is the command plus args needed to launch the server, for example `node ./mcp-server.js` or `npx.cmd -y @modelcontextprotocol/server-filesystem C:\data`. For an already-running HTTP/HTTPS or legacy SSE MCP server, the destination is `--mcp-url`.
-- `rag` — local file/directory of RAG documents/chunks, or a live RAG HTTP endpoint via `--rag-url`.
-
-### Recommended Flow
-
-1. Run `doctor` first from the customer machine. This confirms outbound HTTPS to FullCourtDefense works before you try a scan.
-2. Run `configure` once. Paste the Shield ID and Shield key from the web app's Shield Integrate tab.
-3. Pick the target type: API endpoint, MCP, RAG corpus, or live RAG service.
-4. Use `--mode quick` for a smoke test, then `--mode full --format report` for evidence and web history.
-
-```powershell
-fullcourtdefense doctor
-fullcourtdefense configure
-```
-
-With a Shield key configured, local scans are saved to the web Reports history automatically.
-
-### API Endpoint Scan
-
-Use this when the AI agent is a normal HTTP API, for example `/chat`, `/ask`, `/query`, or an OpenAI-compatible `/v1/chat/completions` route.
-
-For custom JSON APIs, tell the CLI which request field receives the attack prompt and which response field contains the bot answer:
-
-```powershell
-fullcourtdefense scan --local --type endpoint --endpoint "http://internal-agent.local/chat" --method POST --request-format custom --input-field message --output-field response --mode quick --format report
-```
-
-Common custom field mappings:
-
-```powershell
-# Request: { "query": "..." }, response: { "answer": "..." }
-fullcourtdefense scan --local --type endpoint --endpoint "http://localhost:8080/query" --method POST --request-format custom --input-field query --output-field answer --mode full --format report
-
-# GET endpoint: /ask?q=...
-fullcourtdefense scan --local --type endpoint --endpoint "http://localhost:8080/ask" --method GET --request-format custom --input-field q --output-field answer --mode quick --format report
-```
-
-For OpenAI-compatible APIs:
-
-```powershell
-fullcourtdefense scan --local --type endpoint --endpoint "http://localhost:8080/v1/chat/completions" --method POST --request-format openai --mode full --format report
-```
-
-Authenticated API examples:
-
-```powershell
-# Bearer token
-fullcourtdefense scan --local --type endpoint --endpoint "https://agent.internal/chat" --method POST --request-format custom --input-field message --output-field response --auth-type bearer --token YOUR_TOKEN --mode full --format report
-
-# API key header
-fullcourtdefense scan --local --type endpoint --endpoint "https://agent.internal/chat" --method POST --request-format custom --input-field message --output-field response --auth-type api-key --api-key-header X-API-Key --endpoint-api-key YOUR_KEY --mode full --format report
-```
-
-### MCP Scan
-
-Use this when the target exposes tools through the Model Context Protocol. The CLI calls the tool with attack prompts, captures the tool response, sends that response to Shield, and saves the report to history.
-
-For stdio MCP servers:
-
-```powershell
-fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ".\dist\server.js" --mcp-tool all --mode full --format report
-```
-
-For a single stdio tool with fixed args:
-
-```powershell
-fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ".\dist\server.js" --mcp-tool search_docs --mcp-tool-args '{ "query": "{{attack}}" }' --mode quick --format report
-```
-
-For already-running HTTP MCP servers:
-
-```powershell
-fullcourtdefense scan --local --type mcp --mcp-url "http://mcp.internal.company.com/mcp" --mcp-tool all --mode full --format report
-```
-
-For secured MCP servers:
-
-```powershell
-# Bearer auth
-fullcourtdefense scan --local --type mcp --mcp-url "https://internal.company.com/mcp" --mcp-auth-type bearer --mcp-token YOUR_TOKEN --mcp-tool all --mode full --format report
-
-# Basic auth
-fullcourtdefense scan --local --type mcp --mcp-url "https://internal.company.com/mcp" --mcp-auth-type basic --mcp-username USER --mcp-password PASS --mcp-tool all --mode full --format report
-
-# API key header
-fullcourtdefense scan --local --type mcp --mcp-url "https://internal.company.com/mcp" --mcp-auth-type api-key --mcp-api-key-header X-API-Key --mcp-api-key YOUR_KEY --mcp-tool all --mode full --format report
-```
-
-For legacy SSE MCP:
-
-```powershell
-fullcourtdefense scan --local --type mcp --mcp-transport sse --mcp-url "https://internal.company.com/sse" --mcp-tool all --mode full --format report
-```
-
-MCP progress controls:
-
-```powershell
-fullcourtdefense scan --local --type mcp --mcp-url "https://internal.company.com/mcp" --mcp-tool all --mode full --progress verbose --format report
-fullcourtdefense scan --local --type mcp --mcp-url "https://internal.company.com/mcp" --mcp-tool all --mode full --progress compact --format summary
-```
-
-### RAG Corpus Scan
-
-Use this when you have local documents or chunks before they are indexed. The CLI reads `.txt`, `.md`, `.json`, `.csv`, and `.html` files, sends chunks to the RAG Shield endpoint, and saves the report as a RAG scan.
-
-```powershell
-fullcourtdefense scan --local --type rag --rag-path ".\docs" --mode quick --format report
-fullcourtdefense scan --local --type rag --rag-path ".\docs" --mode full --format full-report
-```
-
-Use corpus scan to find poisoned files before ingestion. Use live RAG scan when you need to test the actual retrieval service behavior.
-
-### Live RAG Service Scan
-
-Use this when RAG is a running service, not just files. This is common for retrieval APIs that accept a question and return an answer with retrieved context.
-
-```powershell
-fullcourtdefense scan --local --type rag --rag-url "http://rag.internal.company.com/chat" --method POST --request-format custom --input-field message --output-field answer --mode quick --format report
-```
-
-Common live RAG shapes:
-
-```powershell
-# Request: { "question": "..." }, response: { "answer": "..." }
-fullcourtdefense scan --local --type rag --rag-url "http://localhost:5065/chat" --method POST --request-format custom --input-field question --output-field answer --mode full --format report
-
-# Request: { "query": "..." }, response: { "result": "..." }
-fullcourtdefense scan --local --type rag --rag-url "http://localhost:5065/query" --method POST --request-format custom --input-field query --output-field result --mode full --format report
-
-# OpenAI-compatible RAG endpoint
-fullcourtdefense scan --local --type rag --rag-url "http://localhost:5065/v1/chat/completions" --method POST --request-format openai --mode full --format report
-```
-
-The web report will show `Agent Tested: Local full RAG endpoint scan: ...` and is saved with `scanType: rag`.
-
-### Local Demo RAG Server
-
-This repository includes a deliberately vulnerable RAG service for testing the CLI flow:
-
-```powershell
-$env:PORT = "5065"
-node samples\rag\rag-server.js
-```
-
-In another terminal:
-
-```powershell
-fullcourtdefense scan --local --type rag --rag-url "http://127.0.0.1:5065/chat" --method POST --request-format custom --input-field message --output-field answer --mode quick --format report
-```
-
-The demo should fail because it echoes raw poisoned retrieved context. That is expected and proves the scanner is catching RAG poisoning.
-
-### Older Compact Examples
-
-```bash
-# Internal web API
-fullcourtdefense scan --local --type endpoint --endpoint http://internal-agent.local/chat --method POST --shield-id sh_your_shield_id
-
-# Internal OpenAI-compatible endpoint
-fullcourtdefense scan --local --type endpoint --endpoint http://localhost:8080/v1/chat/completions --webhook-format openai --shield-id sh_your_shield_id
-
-# MCP stdio server
-fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ./dist/index.js --mcp-tool search_docs --mcp-tool-args '{"query":"security policy"}' --shield-id sh_your_shield_id
-
-# Already-running HTTP or HTTPS MCP server
-fullcourtdefense scan --local --type mcp --mcp-url http://mcp.internal.company.com/mcp
-fullcourtdefense scan --local --type mcp --mcp-url http://mcp.internal.company.com/mcp --mcp-tool all --mode full --format report --shield-id sh_your_shield_id
-fullcourtdefense scan --local --type mcp --mcp-url https://internal.company.com/mcp --mcp-tool all --mode full --format report --shield-id sh_your_shield_id
-
-# Legacy SSE MCP server
-fullcourtdefense scan --local --type mcp --mcp-transport sse --mcp-url https://internal.company.com/sse --mcp-tool all --mode full --format report --shield-id sh_your_shield_id
-
-# Secured HTTP MCP server with bearer auth
-fullcourtdefense scan --local --type mcp --mcp-url https://internal.company.com/mcp --mcp-auth-type bearer --mcp-token YOUR_TOKEN --mcp-tool all --mode full --format report --shield-id sh_your_shield_id
-
-# Secured HTTP MCP server with basic auth
-fullcourtdefense scan --local --type mcp --mcp-url https://internal.company.com/mcp --mcp-auth-type basic --mcp-username USER --mcp-password PASS --mcp-tool all --mode full --format report --shield-id sh_your_shield_id
-
-# Secured HTTP MCP server with API-key auth
-fullcourtdefense scan --local --type mcp --mcp-url https://internal.company.com/mcp --mcp-auth-type api-key --mcp-api-key-header X-API-Key --mcp-api-key YOUR_KEY --mcp-tool all --mode full --format report --shield-id sh_your_shield_id
-
-# MCP full scan: all tools x bundled 229+ web attacks
-fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ./dist/index.js --mcp-tool all --mode full --shield-id sh_your_shield_id
-
-# MCP smoke test with same full corpus, limited to 10 attacks per tool
-fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ./dist/index.js --mcp-tool all --mode full --attack-count 10 --shield-id sh_your_shield_id
-
-# MCP evidence report: includes each attack sent, captured tool response, and Shield verdict
-fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ./dist/index.js --mcp-tool all --mode full --attack-count 10 --format report --shield-id sh_your_shield_id
-
-# MCP full scan with per-attack live progress
-fullcourtdefense scan --local --type mcp --mcp-url https://internal.company.com/mcp --mcp-tool all --mode full --progress verbose --format report --shield-id sh_your_shield_id
-
-# RAG documents
-fullcourtdefense scan --local --type rag --rag-path ./docs --format table --shield-id sh_your_shield_id
-
-# Live RAG HTTP service
-fullcourtdefense scan --local --type rag --rag-url http://rag.internal.company.com/chat --method POST --request-format custom --input-field message --output-field answer --mode full --format report --shield-id sh_your_shield_id
-```
-
-Local scans run from the machine executing the CLI, so they can reach private/VPN/internal targets without opening inbound firewall access. The only required network path is outbound HTTPS to your FullCourtDefense backend. With a Shield key configured, the CLI saves the completed scan into the same web Reports history used by hosted scans. The web report keeps every test row with bounded evidence text; use `--format report` or `--format json` locally for the full raw evidence artifact.
-
-When an MCP destination is provided (`--mcp-url` or `--mcp-command`), the CLI defaults to a full all-tools report scan with per-attack live progress. Use `--progress compact` for shorter logs, or `--progress silent` for CI logs.
-
-## Outbound Diagnostic
-
-Use `doctor` before local scans to confirm the customer environment can reach the FullCourtDefense backend over outbound HTTPS:
-
-```bash
-fullcourtdefense doctor
-fullcourtdefense doctor --api-url https://api.fullcourtdefense.ai
-```
-
-It checks `GET /api/health/ping` and reports whether outbound TCP 443/HTTPS is open.
-
-## CI/CD Usage
-
-The CLI returns exit code 1 when the score is below `--fail-threshold`, making it CI-friendly:
-
-```bash
-fullcourtdefense scan --fail-threshold 80 --format summary
-```
-
-For GitHub Actions, use [botguardai/security-scan](https://github.com/botguardai/security-scan) which wraps this CLI with PR comments and check status.
-
-## Get Your API Key
-
-1. Sign up at [fullcourtdefense.ai](https://fullcourtdefense.ai)
-2. Go to **Account > API Keys**
-3. Create a CI/CD key
-
-## Related
-
-- [BotGuard](https://fullcourtdefense.ai) — Automated red-teaming & real-time firewall for AI agents
-- [GitHub Action](https://github.com/botguardai/security-scan) — CI/CD security scanning
-- [Attack Library](https://github.com/botguardai/llm-attacks) — 229+ open-source LLM attack templates
-
-## License
-
-MIT
+# FullCourtDefense CLI
+
+[Full Court Defense](https://fullcourtdefense.ai/) is an AI agent security platform and runtime firewall for teams shipping LLM apps, agentic workflows, MCP tools, and RAG systems. We help builders find and block prompt injection, jailbreaks, data exfiltration, unsafe tool use, and poisoned retrieval content before those failures reach production.
+
+The FullCourtDefense CLI brings that security workflow to your terminal. It can run hosted CI/CD scans against public agents, or local in-organization scans against private APIs, MCP servers, RAG document corpora, and live RAG services. Local scans execute from your machine or VPN, then send captured content outbound to your Shield for verdicts and saved web reports.
+
+## Install
+
+```bash
+npm install -g fullcourtdefense-cli
+# or run directly
+npx fullcourtdefense-cli scan
+```
+
+## Quick Start
+
+```bash
+# Show onboarding help
+fullcourtdefense help
+
+# 1. Check outbound HTTPS from the customer machine
+fullcourtdefense doctor
+
+# 2. Save Shield ID and Shield key
+fullcourtdefense configure
+
+# 3. Run an in-organization local scan with guided questions
+fullcourtdefense scan --local
+
+# 4. Run a detailed MCP report
+fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ./server.js --mcp-tool all --mode full --format report
+
+# Hosted CI/CD scan, if using an API key instead of local Shield scan
+fullcourtdefense scan --api-key YOUR_KEY --endpoint https://my-agent.com/chat --description "My chatbot"
+
+# Check remaining credits
+fullcourtdefense credits --api-key YOUR_KEY
+
+# Generate a config file
+fullcourtdefense init
+```
+
+## Command Guide
+
+- `fullcourtdefense help` — shows the full onboarding flow and command reference.
+- `fullcourtdefense doctor` — confirms outbound HTTPS to FullCourtDefense is open before scanning.
+- `fullcourtdefense configure` — saves Shield ID, Shield key, and API URL to `.fullcourtdefense.yml`.
+- `fullcourtdefense scan --local` — runs inside the customer network and asks whether to scan endpoint, MCP, or RAG.
+- `fullcourtdefense scan --local --type mcp ...` — launches a local stdio MCP server, calls tools, and sends tool responses to Shield.
+- `fullcourtdefense scan --local --type rag ...` — scans local RAG files/directories or a live RAG HTTP service.
+- `fullcourtdefense scan --local --type endpoint ...` — scans an internal HTTP/OpenAI-compatible endpoint.
+- `fullcourtdefense install-cursor-mcp-gateway ...` — registers the protected MCP gateway in Cursor.
+- `fullcourtdefense install-claude-code-mcp-gateway ...` — registers the protected MCP gateway in Claude Code.
+- `fullcourtdefense install-claude-desktop-mcp-gateway ...` — registers the protected MCP gateway in Claude Desktop.
+- `fullcourtdefense credits` — checks hosted scan credits for CI/CD API-key scans.
+- `fullcourtdefense discover` — scans local MCP client configs and reports risk; `--upload` sends desktop inventory to AI Inventory.
+- `fullcourtdefense init` — creates a starter config file.
+
+## Shadow AI / Desktop Discovery
+
+Find MCP servers configured on developer machines without reading chat history or spawning stdio servers by default:
+
+```bash
+# Scan this machine and print results
+fullcourtdefense discover
+
+# JSON output (includes host fingerprint + servers)
+fullcourtdefense discover --json
+
+# Upload to AI Inventory (requires CI/CD API key with audit:write)
+fullcourtdefense discover --upload --api-key YOUR_KEY
+
+# Live-probe HTTP/SSE MCP servers for tools/list (stdio stays config-only)
+fullcourtdefense discover --deep
+
+# Fleet / MDM script — silent upload with user attribution
+fullcourtdefense discover --upload --silent --user-email you@company.com --api-key YOUR_KEY
+
+# Daily automatic scan on this laptop (uses API key from env or ~/.fullcourtdefense.yml)
+fullcourtdefense discover --schedule daily --user-email you@company.com
+
+# Remove daily schedule
+fullcourtdefense discover --unschedule true
+
+# Scan an extra config path
+fullcourtdefense discover --path /path/to/mcp.json
+```
+
+Each upload includes host metadata (`machineId`, `hostname`, `platform`, `user`) so the same MCP server on different laptops appears as separate desktop inventory rows. The CLI is also available as `fcd` or `botguard` after global install.
+
+## Config File
+
+Create a `.fullcourtdefense.yml` to avoid passing flags every time:
+
+```yaml
+apiKey: ${FULLCOURTDEFENSE_API_KEY}
+apiUrl: https://api.fullcourtdefense.ai
+shieldId: sh_your_shield_id
+# shieldKey: shsk_optional_if_locked
+scan:
+  endpoint: https://my-agent.com/chat
+  description: "Customer support chatbot"
+  categories: [jailbreak, prompt_injection, data_extraction]
+  failThreshold: 80
+  format: table
+```
+
+Then just run:
+
+```bash
+fullcourtdefense scan
+```
+
+## Modes
+
+Hosted scans use a CI/CD API key and scan a public or reachable agent endpoint through the FullCourtDefense backend.
+
+| Mode | Use When | Behavior |
+|---|---|---|
+| `--mode sync` | Small hosted scans from CI or a terminal | Waits for the hosted scan result before exiting. |
+| `--mode async` | Longer hosted scans | Starts a hosted job, polls until complete, then prints the result. |
+
+Local scans run from the customer machine or VPN and only send captured text outbound to Shield for verdicts.
+
+| Mode | Use When | Behavior |
+|---|---|---|
+| `--mode quick` | Smoke test before a demo or install handoff | Runs a small default attack set. |
+| `--mode full` | Real evidence report | Runs the bundled 229+ attack corpus. |
+| `--mode targeted` | You know what the agent protects | Runs default plus targeted attacks and appends `--description` as focus context. |
+| `--mode deep` | Stress and broad regression testing | Runs the broad corpus plus deeper multi-step/stress cases. |
+
+## Full Option Reference
+
+### Global
+
+| Flag | Applies To | Description | Default |
+|---|---|---|---|
+| `--help`, `-h` | all commands | Show help. | — |
+| `--version`, `-v` | all commands | Print package version. | — |
+| `--config <path>` | scan/config | Path to `.fullcourtdefense.yml`, `.fullcourtdefense.yaml`, or legacy `.botguard.yml`. | auto-detect |
+| `--api-url <url>` | doctor/configure/scan | FullCourtDefense backend URL. | `https://api.fullcourtdefense.ai` |
+
+### Shield And Hosted API
+
+| Flag | Applies To | Description | Default |
+|---|---|---|---|
+| `--api-key <key>` | hosted scan/credits | Hosted scan API key. Can also use `FULLCOURTDEFENSE_API_KEY` or legacy `BOTGUARD_API_KEY`. | config/env |
+| `--shield-id <id>` | local scan | Shield ID from the Shield Integrate tab. Can also use `FULLCOURTDEFENSE_SHIELD_ID`, `FCD_SHIELD_ID`, or `AGENTGUARD_SHIELD_ID`. | config/env/prompt |
+| `--shield-key <key>` | local scan | Optional Shield key for locked Shields. Can also use `FULLCOURTDEFENSE_SHIELD_KEY`, `FCD_SHIELD_KEY`, or `AGENTGUARD_SHIELD_KEY`. | config/env/prompt |
+
+### Hosted Scan
+
+| Flag | Applies To | Description | Default |
+|---|---|---|---|
+| `--endpoint <url>` | hosted scan | Public/reachable AI agent API URL. | config |
+| `--description <text>` | hosted scan/local targeted | Agent description. For `--mode targeted`, also used as local focus context. | config |
+| `--system-prompt <text-or-path>` | hosted scan | System prompt text or path to a file. | config |
+| `--categories <list>` | hosted scan | Comma-separated attack categories. | all |
+| `--attack-count <n>` | hosted/local | Limit number of attacks. Useful for smoke tests. | mode default |
+| `--webhook-format <fmt>` | hosted scan | Webhook format: `n8n`, `make`, `zapier`, or `custom`. Legacy alias for local request format. | — |
+
+### Local Target Selection
+
+| Flag | Applies To | Description | Default |
+|---|---|---|---|
+| `--local` | scan | Run from this machine, inside the customer's network/VPN. | false |
+| `--type <type>` | local scan | Local target type: `endpoint`, `mcp`, or `rag`. | prompt |
+
+### Local HTTP API Endpoint
+
+| Flag | Applies To | Description | Default |
+|---|---|---|---|
+| `--endpoint <url>` | `--type endpoint` | Internal HTTP API URL, for example `http://agent.local/chat`. | prompt |
+| `--method <GET|POST>` | endpoint/rag-url | HTTP method. | prompt/`POST` |
+| `--request-format <fmt>` | endpoint/rag-url | Request body shape: `custom` or `openai`. | prompt/`custom` |
+| `--input-field <field>` | endpoint/rag-url | Request field that receives the attack prompt, for example `message`, `query`, `question`, or `input`. | `message` |
+| `--output-field <field>` | endpoint/rag-url | Response field containing the bot answer, for example `answer`, `response`, `text`, or `choices.0.message.content`. | auto-detect |
+| `--auth-type <type>` | endpoint/rag-url | HTTP auth type: `none`, `bearer`, `basic`, or `api-key`. | `none` |
+| `--username <user>` | endpoint/rag-url basic auth | Basic auth username. | prompt |
+| `--password <pass>` | endpoint/rag-url basic auth | Basic auth password. | prompt |
+| `--token <token>` | endpoint/rag-url bearer auth | Bearer token. | prompt |
+| `--api-key-header <header>` | endpoint/rag-url API-key auth | API key header name, for example `X-API-Key`. | `X-API-Key` |
+| `--endpoint-api-key <key>` | endpoint/rag-url API-key auth | API key value for the scanned endpoint. | prompt |
+
+### MCP
+
+| Flag | Applies To | Description | Default |
+|---|---|---|---|
+| `--mcp-command <cmd>` | stdio MCP | Command that starts the MCP server, for example `node`, `python`, or `npx.cmd`. | prompt |
+| `--mcp-args <args>` | stdio MCP | Args passed to `--mcp-command`, for example `.\dist\server.js`. JSON array strings are also supported. | empty |
+| `--mcp-url <url>` | HTTP/SSE MCP | Already-running MCP URL, for example `https://internal.company.com/mcp`. | prompt |
+| `--mcp-transport <t>` | MCP | Transport: `stdio`, `http`, or `sse`. HTTP/SSE can usually be inferred from `--mcp-url`. | inferred |
+| `--mcp-tool <tool>` | MCP | Tool to scan, or `all` to scan every listed tool. | `all` when destination is provided |
+| `--mcp-tool-args <json>` | MCP | Tool args JSON. Use `{{attack}}` anywhere the current attack prompt should be inserted. | `{}` |
+| `--mcp-auth-type <type>` | HTTP/SSE MCP | Auth type: `none`, `bearer`, `basic`, or `api-key`. | `none` |
+| `--mcp-token <token>` | HTTP/SSE MCP bearer auth | Bearer token. | prompt |
+| `--mcp-username <user>` | HTTP/SSE MCP basic auth | Basic auth username. | prompt |
+| `--mcp-password <pass>` | HTTP/SSE MCP basic auth | Basic auth password. | prompt |
+| `--mcp-api-key-header <header>` | HTTP/SSE MCP API-key auth | API key header name. | `X-API-Key` |
+| `--mcp-api-key <key>` | HTTP/SSE MCP API-key auth | API key value. | prompt |
+| `--progress <mode>` | MCP | Console progress: `verbose`, `compact`, or `silent`. | `verbose` |
+| `--server-name <name>` | MCP gateway installers | MCP server name to write into the client config. | `agentguard-gateway` |
+| `--developer-name <name>` | MCP gateway installers | Runtime identity used for user-scoped Action Policies. Auto-detected from `FCD_DEVELOPER_NAME`, git email, npm username, or OS username. | auto |
+| `--agent-name <name>` | MCP gateway installers | Runtime agent name shown in AI Users. Auto-generated from runtime identity plus client, e.g. `boaz.lautman-claude-desktop`. | auto |
+| `--scope <scope>` | Claude Code gateway installer | Claude Code MCP scope: `local`, `project`, or `user`. | `local` |
+| `--config-path <path>` | Claude Desktop gateway installer | Override path to `claude_desktop_config.json`. | OS default |
+
+### RAG
+
+| Flag | Applies To | Description | Default |
+|---|---|---|---|
+| `--rag-path <path>` | `--type rag` | Local RAG file or directory to scan as a corpus. Supports `.txt`, `.md`, `.json`, `.csv`, and `.html`. | prompt |
+| `--rag-url <url>` | `--type rag` | Live RAG HTTP endpoint to scan like an app. Uses the same HTTP flags as endpoint scans. | — |
+
+### Output And CI
+
+| Flag | Applies To | Description | Default |
+|---|---|---|---|
+| `--mode <mode>` | scan | Hosted: `sync`, `async`. Local: `quick`, `full`, `targeted`, `deep`. | hosted `sync`, local `quick` |
+| `--format <fmt>` | scan | Output: `table`, `summary`, `report`, `full-report`, or `json`. | hosted `table`, local `summary` |
+| `--fail-threshold <n>` | scan | Exit with code 1 if score is below this 0-100 threshold. | `0` |
+
+## Realistic Command Examples
+
+### First-Time Setup
+
+Run these on the same machine that can reach the customer's private agent, MCP server, or RAG service:
+
+```powershell
+fullcourtdefense doctor
+fullcourtdefense configure
+fullcourtdefense scan --local
+```
+
+Expected `doctor` output:
+
+```text
+BotGuard outbound diagnostic
+Target: https://api.fullcourtdefense.ai
+
+PASS outbound HTTPS open (200, 487ms)
+Checked: https://api.fullcourtdefense.ai/api/health/ping
+```
+
+### Hosted CI/CD Scan
+
+Use hosted scans when the agent endpoint is reachable by FullCourtDefense and you have a CI/CD API key.
+
+```powershell
+$env:FULLCOURTDEFENSE_API_KEY = "bg_live_..."
+fullcourtdefense scan --endpoint "https://support-bot.example.com/chat" --description "Customer support chatbot" --mode sync --format summary --fail-threshold 80
+```
+
+Async hosted scan for a longer job:
+
+```powershell
+fullcourtdefense scan --api-key "bg_live_..." --endpoint "https://agent.example.com/chat" --description "Production sales assistant" --mode async --format report
+```
+
+### Local Modes
+
+Use quick mode first:
+
+```powershell
+fullcourtdefense scan --local --type endpoint --endpoint "http://localhost:3000/chat" --method POST --request-format custom --input-field message --output-field response --mode quick --format report
+```
+
+Use full mode for evidence:
+
+```powershell
+fullcourtdefense scan --local --type endpoint --endpoint "http://localhost:3000/chat" --method POST --request-format custom --input-field message --output-field response --mode full --format report
+```
+
+Use targeted mode when you know the protected domain:
+
+```powershell
+fullcourtdefense scan --local --type endpoint --endpoint "http://localhost:3000/chat" --method POST --request-format custom --input-field message --output-field response --mode targeted --description "Healthcare support bot with patient records and billing data" --format report
+```
+
+Use deep mode for broad regression:
+
+```powershell
+fullcourtdefense scan --local --type endpoint --endpoint "http://localhost:3000/chat" --method POST --request-format custom --input-field message --output-field response --mode deep --format full-report
+```
+
+### Local API Endpoint Examples
+
+Typical Express/FastAPI app:
+
+```powershell
+fullcourtdefense scan --local --type endpoint --endpoint "http://127.0.0.1:8000/chat" --method POST --request-format custom --input-field message --output-field answer --mode full --format report
+```
+
+Query-style endpoint:
+
+```powershell
+fullcourtdefense scan --local --type endpoint --endpoint "http://127.0.0.1:8000/query" --method POST --request-format custom --input-field query --output-field result --mode full --format report
+```
+
+OpenAI-compatible endpoint:
+
+```powershell
+fullcourtdefense scan --local --type endpoint --endpoint "http://127.0.0.1:8000/v1/chat/completions" --method POST --request-format openai --mode full --format report
+```
+
+### MCP Examples
+
+Local stdio MCP server built from your repo:
+
+```powershell
+fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ".\dist\mcp-server.js" --mcp-tool all --mode full --format report
+```
+
+Filesystem MCP over `npx.cmd` on Windows:
+
+```powershell
+fullcourtdefense scan --local --type mcp --mcp-command npx.cmd --mcp-args "-y @modelcontextprotocol/server-filesystem C:\company\docs" --mcp-tool all --mode full --format report
+```
+
+Single MCP tool with attack inserted into an argument:
+
+```powershell
+fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ".\dist\mcp-server.js" --mcp-tool search_docs --mcp-tool-args '{ "query": "{{attack}}", "limit": 5 }' --mode quick --format report
+```
+
+Already-running HTTP MCP:
+
+```powershell
+fullcourtdefense scan --local --type mcp --mcp-url "http://127.0.0.1:5066/mcp" --mcp-tool all --mode full --format report
+```
+
+Secured HTTP MCP:
+
+```powershell
+fullcourtdefense scan --local --type mcp --mcp-url "https://mcp.internal.company.com/mcp" --mcp-auth-type bearer --mcp-token "mcp_token_..." --mcp-tool all --mode full --format report
+```
+
+### MCP Gateway Install Examples
+
+Use the MCP gateway when you want Cursor, Claude Code, or Claude Desktop tool calls checked against AgentGuard runtime/action policies before they reach the real MCP server.
+
+Cursor project install:
+
+```powershell
+fullcourtdefense install-cursor-mcp-gateway --project true --shield-id "sh_..." --shield-key "shsk_..." --mcp-command npm --mcp-args "run mcp"
+```
+
+Claude Code local install, private to you in the current project:
+
+```powershell
+fullcourtdefense install-claude-code-mcp-gateway --scope local --shield-id "sh_..." --shield-key "shsk_..." --mcp-command npm --mcp-args "run mcp"
+```
+
+Claude Code project install, shared through `.mcp.json`:
+
+```powershell
+fullcourtdefense install-claude-code-mcp-gateway --scope project --shield-id "sh_..." --mcp-command npm --mcp-args "run mcp"
+```
+
+Claude Desktop install:
+
+```powershell
+fullcourtdefense install-claude-desktop-mcp-gateway --shield-id "sh_..." --shield-key "shsk_..." --mcp-command npm --mcp-args "run mcp"
+```
+
+The gateway auto-detects runtime identity when `--developer-name` is omitted. Detection order is `FCD_DEVELOPER_NAME`, `FULLCOURTDEFENSE_DEVELOPER_NAME`, `AGENTGUARD_DEVELOPER_NAME`, `USER_EMAIL`, `git config user.email`, `npm whoami`, then OS username. Use `--developer-name` only when you want to override the detected employee/runtime identity.
+
+Direct gateway run for debugging:
+
+```powershell
+fullcourtdefense mcp-gateway --agent-client claude-code --shield-id "sh_..." --mcp-command npm --mcp-args "run mcp"
+```
+
+### RAG Examples
+
+Scan local documents before ingestion:
+
+```powershell
+fullcourtdefense scan --local --type rag --rag-path "C:\company\kb-docs" --mode full --format report
+```
+
+Scan one suspicious file:
+
+```powershell
+fullcourtdefense scan --local --type rag --rag-path ".\docs\release-notes.md" --mode quick --format report
+```
+
+Scan a live RAG service:
+
+```powershell
+fullcourtdefense scan --local --type rag --rag-url "http://127.0.0.1:5065/chat" --method POST --request-format custom --input-field message --output-field answer --mode full --format report
+```
+
+Scan an OpenAI-compatible RAG service:
+
+```powershell
+fullcourtdefense scan --local --type rag --rag-url "http://127.0.0.1:5065/v1/chat/completions" --method POST --request-format openai --mode full --format report
+```
+
+### Auth Examples
+
+Bearer auth for an internal agent:
+
+```powershell
+fullcourtdefense scan --local --type endpoint --endpoint "https://agent.internal/chat" --method POST --request-format custom --input-field message --output-field answer --auth-type bearer --token "eyJ..." --mode full --format report
+```
+
+Basic auth:
+
+```powershell
+fullcourtdefense scan --local --type endpoint --endpoint "https://agent.internal/chat" --method POST --request-format custom --input-field message --output-field answer --auth-type basic --username "scanner" --password "scanner-password" --mode full --format report
+```
+
+API key header:
+
+```powershell
+fullcourtdefense scan --local --type endpoint --endpoint "https://agent.internal/chat" --method POST --request-format custom --input-field message --output-field answer --auth-type api-key --api-key-header X-Internal-Key --endpoint-api-key "internal_key_..." --mode full --format report
+```
+
+### CI Gate Examples
+
+Fail the build if score is below 80:
+
+```powershell
+fullcourtdefense scan --api-key "$env:FULLCOURTDEFENSE_API_KEY" --endpoint "https://agent.example.com/chat" --description "Production support agent" --mode sync --format summary --fail-threshold 80
+```
+
+Local CI against a service started earlier in the job:
+
+```powershell
+fullcourtdefense scan --local --type endpoint --endpoint "http://127.0.0.1:3000/chat" --method POST --request-format custom --input-field message --output-field response --mode quick --format summary --fail-threshold 80
+```
+
+## In-Organization Local Scan
+
+Use local scan when the AI endpoint, MCP server, RAG service, or RAG corpus is only reachable from inside your organization. The CLI executes the local target, then sends the captured content outbound to your FullCourtDefense Shield for the real verdict.
+
+```bash
+fullcourtdefense scan --local
+```
+
+On first local scan, the CLI asks for your Shield ID and saves it to `.fullcourtdefense.yml`. You can also pass it directly:
+
+```bash
+fullcourtdefense scan --local --shield-id sh_your_shield_id
+```
+
+The CLI asks what to scan:
+
+- `endpoint` — internal HTTP API or OpenAI-compatible endpoint.
+- `mcp` — MCP destination. For stdio MCP, the destination is the command plus args needed to launch the server, for example `node ./mcp-server.js` or `npx.cmd -y @modelcontextprotocol/server-filesystem C:\data`. For an already-running HTTP/HTTPS or legacy SSE MCP server, the destination is `--mcp-url`.
+- `rag` — local file/directory of RAG documents/chunks, or a live RAG HTTP endpoint via `--rag-url`.
+
+### Recommended Flow
+
+1. Run `doctor` first from the customer machine. This confirms outbound HTTPS to FullCourtDefense works before you try a scan.
+2. Run `configure` once. Paste the Shield ID and Shield key from the web app's Shield Integrate tab.
+3. Pick the target type: API endpoint, MCP, RAG corpus, or live RAG service.
+4. Use `--mode quick` for a smoke test, then `--mode full --format report` for evidence and web history.
+
+```powershell
+fullcourtdefense doctor
+fullcourtdefense configure
+```
+
+With a Shield key configured, local scans are saved to the web Reports history automatically.
+
+### API Endpoint Scan
+
+Use this when the AI agent is a normal HTTP API, for example `/chat`, `/ask`, `/query`, or an OpenAI-compatible `/v1/chat/completions` route.
+
+For custom JSON APIs, tell the CLI which request field receives the attack prompt and which response field contains the bot answer:
+
+```powershell
+fullcourtdefense scan --local --type endpoint --endpoint "http://internal-agent.local/chat" --method POST --request-format custom --input-field message --output-field response --mode quick --format report
+```
+
+Common custom field mappings:
+
+```powershell
+# Request: { "query": "..." }, response: { "answer": "..." }
+fullcourtdefense scan --local --type endpoint --endpoint "http://localhost:8080/query" --method POST --request-format custom --input-field query --output-field answer --mode full --format report
+
+# GET endpoint: /ask?q=...
+fullcourtdefense scan --local --type endpoint --endpoint "http://localhost:8080/ask" --method GET --request-format custom --input-field q --output-field answer --mode quick --format report
+```
+
+For OpenAI-compatible APIs:
+
+```powershell
+fullcourtdefense scan --local --type endpoint --endpoint "http://localhost:8080/v1/chat/completions" --method POST --request-format openai --mode full --format report
+```
+
+Authenticated API examples:
+
+```powershell
+# Bearer token
+fullcourtdefense scan --local --type endpoint --endpoint "https://agent.internal/chat" --method POST --request-format custom --input-field message --output-field response --auth-type bearer --token YOUR_TOKEN --mode full --format report
+
+# API key header
+fullcourtdefense scan --local --type endpoint --endpoint "https://agent.internal/chat" --method POST --request-format custom --input-field message --output-field response --auth-type api-key --api-key-header X-API-Key --endpoint-api-key YOUR_KEY --mode full --format report
+```
+
+### MCP Scan
+
+Use this when the target exposes tools through the Model Context Protocol. The CLI calls the tool with attack prompts, captures the tool response, sends that response to Shield, and saves the report to history.
+
+For stdio MCP servers:
+
+```powershell
+fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ".\dist\server.js" --mcp-tool all --mode full --format report
+```
+
+For a single stdio tool with fixed args:
+
+```powershell
+fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ".\dist\server.js" --mcp-tool search_docs --mcp-tool-args '{ "query": "{{attack}}" }' --mode quick --format report
+```
+
+For already-running HTTP MCP servers:
+
+```powershell
+fullcourtdefense scan --local --type mcp --mcp-url "http://mcp.internal.company.com/mcp" --mcp-tool all --mode full --format report
+```
+
+For secured MCP servers:
+
+```powershell
+# Bearer auth
+fullcourtdefense scan --local --type mcp --mcp-url "https://internal.company.com/mcp" --mcp-auth-type bearer --mcp-token YOUR_TOKEN --mcp-tool all --mode full --format report
+
+# Basic auth
+fullcourtdefense scan --local --type mcp --mcp-url "https://internal.company.com/mcp" --mcp-auth-type basic --mcp-username USER --mcp-password PASS --mcp-tool all --mode full --format report
+
+# API key header
+fullcourtdefense scan --local --type mcp --mcp-url "https://internal.company.com/mcp" --mcp-auth-type api-key --mcp-api-key-header X-API-Key --mcp-api-key YOUR_KEY --mcp-tool all --mode full --format report
+```
+
+For legacy SSE MCP:
+
+```powershell
+fullcourtdefense scan --local --type mcp --mcp-transport sse --mcp-url "https://internal.company.com/sse" --mcp-tool all --mode full --format report
+```
+
+MCP progress controls:
+
+```powershell
+fullcourtdefense scan --local --type mcp --mcp-url "https://internal.company.com/mcp" --mcp-tool all --mode full --progress verbose --format report
+fullcourtdefense scan --local --type mcp --mcp-url "https://internal.company.com/mcp" --mcp-tool all --mode full --progress compact --format summary
+```
+
+### RAG Corpus Scan
+
+Use this when you have local documents or chunks before they are indexed. The CLI reads `.txt`, `.md`, `.json`, `.csv`, and `.html` files, sends chunks to the RAG Shield endpoint, and saves the report as a RAG scan.
+
+```powershell
+fullcourtdefense scan --local --type rag --rag-path ".\docs" --mode quick --format report
+fullcourtdefense scan --local --type rag --rag-path ".\docs" --mode full --format full-report
+```
+
+Use corpus scan to find poisoned files before ingestion. Use live RAG scan when you need to test the actual retrieval service behavior.
+
+### Live RAG Service Scan
+
+Use this when RAG is a running service, not just files. This is common for retrieval APIs that accept a question and return an answer with retrieved context.
+
+```powershell
+fullcourtdefense scan --local --type rag --rag-url "http://rag.internal.company.com/chat" --method POST --request-format custom --input-field message --output-field answer --mode quick --format report
+```
+
+Common live RAG shapes:
+
+```powershell
+# Request: { "question": "..." }, response: { "answer": "..." }
+fullcourtdefense scan --local --type rag --rag-url "http://localhost:5065/chat" --method POST --request-format custom --input-field question --output-field answer --mode full --format report
+
+# Request: { "query": "..." }, response: { "result": "..." }
+fullcourtdefense scan --local --type rag --rag-url "http://localhost:5065/query" --method POST --request-format custom --input-field query --output-field result --mode full --format report
+
+# OpenAI-compatible RAG endpoint
+fullcourtdefense scan --local --type rag --rag-url "http://localhost:5065/v1/chat/completions" --method POST --request-format openai --mode full --format report
+```
+
+The web report will show `Agent Tested: Local full RAG endpoint scan: ...` and is saved with `scanType: rag`.
+
+### Local Demo RAG Server
+
+This repository includes a deliberately vulnerable RAG service for testing the CLI flow:
+
+```powershell
+$env:PORT = "5065"
+node samples\rag\rag-server.js
+```
+
+In another terminal:
+
+```powershell
+fullcourtdefense scan --local --type rag --rag-url "http://127.0.0.1:5065/chat" --method POST --request-format custom --input-field message --output-field answer --mode quick --format report
+```
+
+The demo should fail because it echoes raw poisoned retrieved context. That is expected and proves the scanner is catching RAG poisoning.
+
+### Older Compact Examples
+
+```bash
+# Internal web API
+fullcourtdefense scan --local --type endpoint --endpoint http://internal-agent.local/chat --method POST --shield-id sh_your_shield_id
+
+# Internal OpenAI-compatible endpoint
+fullcourtdefense scan --local --type endpoint --endpoint http://localhost:8080/v1/chat/completions --webhook-format openai --shield-id sh_your_shield_id
+
+# MCP stdio server
+fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ./dist/index.js --mcp-tool search_docs --mcp-tool-args '{"query":"security policy"}' --shield-id sh_your_shield_id
+
+# Already-running HTTP or HTTPS MCP server
+fullcourtdefense scan --local --type mcp --mcp-url http://mcp.internal.company.com/mcp
+fullcourtdefense scan --local --type mcp --mcp-url http://mcp.internal.company.com/mcp --mcp-tool all --mode full --format report --shield-id sh_your_shield_id
+fullcourtdefense scan --local --type mcp --mcp-url https://internal.company.com/mcp --mcp-tool all --mode full --format report --shield-id sh_your_shield_id
+
+# Legacy SSE MCP server
+fullcourtdefense scan --local --type mcp --mcp-transport sse --mcp-url https://internal.company.com/sse --mcp-tool all --mode full --format report --shield-id sh_your_shield_id
+
+# Secured HTTP MCP server with bearer auth
+fullcourtdefense scan --local --type mcp --mcp-url https://internal.company.com/mcp --mcp-auth-type bearer --mcp-token YOUR_TOKEN --mcp-tool all --mode full --format report --shield-id sh_your_shield_id
+
+# Secured HTTP MCP server with basic auth
+fullcourtdefense scan --local --type mcp --mcp-url https://internal.company.com/mcp --mcp-auth-type basic --mcp-username USER --mcp-password PASS --mcp-tool all --mode full --format report --shield-id sh_your_shield_id
+
+# Secured HTTP MCP server with API-key auth
+fullcourtdefense scan --local --type mcp --mcp-url https://internal.company.com/mcp --mcp-auth-type api-key --mcp-api-key-header X-API-Key --mcp-api-key YOUR_KEY --mcp-tool all --mode full --format report --shield-id sh_your_shield_id
+
+# MCP full scan: all tools x bundled 229+ web attacks
+fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ./dist/index.js --mcp-tool all --mode full --shield-id sh_your_shield_id
+
+# MCP smoke test with same full corpus, limited to 10 attacks per tool
+fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ./dist/index.js --mcp-tool all --mode full --attack-count 10 --shield-id sh_your_shield_id
+
+# MCP evidence report: includes each attack sent, captured tool response, and Shield verdict
+fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ./dist/index.js --mcp-tool all --mode full --attack-count 10 --format report --shield-id sh_your_shield_id
+
+# MCP full scan with per-attack live progress
+fullcourtdefense scan --local --type mcp --mcp-url https://internal.company.com/mcp --mcp-tool all --mode full --progress verbose --format report --shield-id sh_your_shield_id
+
+# RAG documents
+fullcourtdefense scan --local --type rag --rag-path ./docs --format table --shield-id sh_your_shield_id
+
+# Live RAG HTTP service
+fullcourtdefense scan --local --type rag --rag-url http://rag.internal.company.com/chat --method POST --request-format custom --input-field message --output-field answer --mode full --format report --shield-id sh_your_shield_id
+```
+
+Local scans run from the machine executing the CLI, so they can reach private/VPN/internal targets without opening inbound firewall access. The only required network path is outbound HTTPS to your FullCourtDefense backend. With a Shield key configured, the CLI saves the completed scan into the same web Reports history used by hosted scans. The web report keeps every test row with bounded evidence text; use `--format report` or `--format json` locally for the full raw evidence artifact.
+
+When an MCP destination is provided (`--mcp-url` or `--mcp-command`), the CLI defaults to a full all-tools report scan with per-attack live progress. Use `--progress compact` for shorter logs, or `--progress silent` for CI logs.
+
+## Outbound Diagnostic
+
+Use `doctor` before local scans to confirm the customer environment can reach the FullCourtDefense backend over outbound HTTPS:
+
+```bash
+fullcourtdefense doctor
+fullcourtdefense doctor --api-url https://api.fullcourtdefense.ai
+```
+
+It checks `GET /api/health/ping` and reports whether outbound TCP 443/HTTPS is open.
+
+## CI/CD Usage
+
+The CLI returns exit code 1 when the score is below `--fail-threshold`, making it CI-friendly:
+
+```bash
+fullcourtdefense scan --fail-threshold 80 --format summary
+```
+
+For GitHub Actions, use [botguardai/security-scan](https://github.com/botguardai/security-scan) which wraps this CLI with PR comments and check status.
+
+## Get Your API Key
+
+1. Sign up at [fullcourtdefense.ai](https://fullcourtdefense.ai)
+2. Go to **Account > API Keys**
+3. Create a CI/CD key
+
+## Related
+
+- [BotGuard](https://fullcourtdefense.ai) — Automated red-teaming & real-time firewall for AI agents
+- [GitHub Action](https://github.com/botguardai/security-scan) — CI/CD security scanning
+- [Attack Library](https://github.com/botguardai/llm-attacks) — 229+ open-source LLM attack templates
+
+## License
+
+MIT