Documentation

Shield LLM is a CLI that performs automated security testing on AI chatbots. Follow these steps to get started:

1. 1
   Install the CLI

   Install Shield LLM globally with npm: `npm install -g @shield-llm/cli`.
2. 2
   Initialize the config

   Run `shield-llm init` to generate a shield.config.json describing your chatbot endpoint.
3. 3
   Authenticate

   Run `shield-llm login` to authenticate with your dashboard, or set an API key in shield.config.json.
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/cli

# 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

Scan Flags

Configuration File

Create a shield.config.json in your project root. The CLI auto-discovers it, or pass -c path explicitly.

{
  "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. Bundled attacks act as an offline fallback only when the backend is unreachable.
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 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.

Shield LLM uses Weighted Impact Scoring to calculate a security score from 0 to 100. Critical vulnerabilities have a much larger impact than minor findings.

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.