Documentation

Shield LLM grades your chatbot's defenses against real-world attacks, right from your terminal. You'll need an account and an API key (the CLI is a Pro feature); grab the key from your dashboard under Settings. Prefer to stay hands-off? Ask the coding agent you already use to run these steps for you.

1. 1
   Install the CLI

   Install Shield LLM globally with npm: `npm install -g shield-llm`.
2. 2
   Authenticate

   Run `shield-llm login --key sk_shield_...` with the API key from your dashboard. You'll see your plan and scans remaining, so you know you're connected.
3. 3
   Initialize the config

   Run `shield-llm init` to generate a shield.config.json describing your chatbot endpoint.
4. 4
   Run your first scan

   Run `shield-llm scan` to launch a security audit against your chatbot. Results stream to your dashboard.

Scan chatbot APIs directly from the command line: REST endpoints, SSE streaming, custom HTTP shapes. The CLI is a thin client. Authentication, the attack catalogue, judging and scoring all live on the backend (SaaS or self-hosted License). New attacks reach existing CI installations on the next scan, with no upgrade.

Installation

npm install -g shield-llm

# Or use without installing:
npx shield-llm scan --help

Quick Start

# 1. Authenticate (SaaS or License instance)
shield-llm login --key sk_shield_xxx

# 2. Generate a config for your chatbot
shield-llm init

# 3. Run a scan
shield-llm scan -c shield.config.json

# 4. (CI mode) JSON to stdout, status to stderr, exit-code policy
shield-llm scan -c shield.config.json --ci --min-score 75

Commands

{
  "endpoint": {
    "url": "https://api.mycompany.com/chatbot",
    "request": {
      "body": { "message": "{{prompt}}" }
    },
    "response": {
      "field": "response"
    }
  }
}

Architecture: thin client

Each scan walks through four steps. The CLI never holds an LLM key, never decides what is vulnerable, and never bundles the attack catalogue: the backend is the single source of truth.

1. 1
   Authenticate

   shield-llm login stores an API key (SaaS) or license key + URL (self-hosted) in ~/.shield-llm/credentials.json. Every subsequent call carries the Bearer token.
2. 2
   Fetch the attack catalogue

   GET /api/cli/attacks?preset=… returns the attacks the user's plan is allowed to run, plus an optional set of custom tests. The CLI ships no attacks of its own, so a backend connection is required.
3. 3
   Send attacks to the target

   For each attack, the CLI POSTs the prompt to the configured endpoint (HTTP, SSE, multi-turn). The target only sees a request shaped like its production traffic.
4. 4
   Backend judges & persists

   Captured responses go to /api/cli/evaluate. The backend runs regex + LLM judge using its own credentials, scores the run, persists it to the dashboard, and returns the verdict. The CLI prints the result and exits.

Output Formats & CI/CD

Exit codes: 0 passed · 1 threshold violation · 2 config or auth error · 3 runtime or network error. Use --ci to send JSON to stdout and status logs to stderr so CI logs stay parseable.

GitHub Action example:

- uses: ./.github/actions/shield-llm-scan
  with:
    api-key: ${{ secrets.SHIELD_LLM_API_KEY }}
    config: shield.config.json
    preset: owasp
    min-score: 75
    fail-on-critical: true
    output-format: sarif

Shield exposes its red-teaming to AI coding agents (Claude Code, Cursor, and any MCP client) through a Model Context Protocol server. An agent can scan the chatbot it is building, read the fixes, and re-prove them without leaving the editor.

Tools

Setup

npm install -g shield-llm-mcp

# or run without installing (your MCP client can use npx):
npx shield-llm-mcp

MCP client configuration

{
  "mcpServers": {
    "shield-llm": { "command": "shield-llm-mcp" }
  }
}

Shield LLM runs from your environment, testing chatbots through their HTTP endpoint — no SDK or code changes required.

Shield LLM's test suite is mapped to the OWASP LLM Top 10, the industry standard for AI/LLM security risks.

Your chatbot gets a score from 0 to 100 and a letter grade from A to F, like a report card. Higher is safer. Each vulnerability subtracts from a perfect score, weighted by how serious it is, so one critical hole costs far more than a minor finding.

Severity Weights

Grade Thresholds

Choose a scan preset based on your needs. Each preset runs a curated set of attacks optimized for different use cases.

Define your own security test scenarios tailored to your chatbot's specific use case and compliance requirements.