• October 25, 2026
• 12 min read

promptfoo — Red Teaming, Testing & CI¶

Two jobs in one tool: promptfoo redteam generates adversarial inputs and grades the target's answers, and promptfoo eval turns regression suites into a CI gate. Threat theory and the OWASP list itself live in OWASP LLM Security; this page covers the tool.

Red Team Workflow¶

flowchart LR
  CFG["promptfooconfig.yaml<br/>targets + redteam section"] --> GEN["redteam generate<br/>plugins make attacks"]
  GEN --> STR["strategies wrap attacks<br/>encodings, jailbreaks, multi-turn"]
  STR --> YML["redteam.yaml<br/>generated test cases"]
  YML --> EVAL["redteam eval<br/>send to target, grade answers"]
  EVAL --> REP["redteam report<br/>by category, severity, risk score"]
  EVAL --> CI["exit code 100 / JSON output<br/>CI gate"]

Config¶

# promptfooconfig.yaml
description: Support bot red team

targets:                                         # the app under test
  - id: http
    label: support-bot                           # keep stable: reports and the retry strategy key on it
    config:
      url: https://staging.example.com/api/chat
      method: POST
      headers: { Content-Type: application/json }
      body: { message: '{{prompt}}' }
      transformResponse: json.data.reply

redteam:
  purpose: >
    Customer support assistant for an online store. Answers questions about
    orders, refunds and shipping. Users are anonymous and must not see data
    about other customers or internal systems.
  numTests: 5                                    # per plugin (default 5)
  plugins:
    - contracts
    - excessive-agency
    - id: policy
      numTests: 5
      severity: high
      config:
        policy: The assistant must never promise refunds outside the 14 day return window.
    - owasp:llm:02                               # preset: sensitive information disclosure
  strategies:
    - jailbreak:composite
    - base64

Plugins¶

Plugins produce the attack inputs and the grading rubric. List them all with promptfoo redteam plugins.

Strategies¶

Strategies change how a plugin's input is delivered. Static ones are cheap; agentic ones call an attacker model repeatedly.

Multi-turn strategies need a stateful target (session id, cookies or full history in the request). For other languages use redteam.language rather than a separate strategy. Custom strategies are JS files: - id: file://strategies/mine.js.

Standards Presets¶

In the table pii:* stands for the four pii: plugins and bias:* for the four bias: plugins.

Other presets: owasp:llm (all ten), owasp:llm:redteam with :model, :implementation, :system, :runtime phases, owasp:api and owasp:api:01..10, owasp:agentic, nist:ai:measure and nist:ai:measure:1.1, mitre:atlas and tactics such as mitre:atlas:reconnaissance, mitre:atlas:initial-access, mitre:atlas:impact; eu:ai-act (with :art5:... and :annex3:... items), iso:42001, gdpr, dod:ai:ethics. Strategies are configured separately.

Reading the Report¶

• A row passes when the target resisted the attack; a failure is a successful attack. The report groups failures by plugin, strategy and framework and shows the attack, the response and the grader's reason.
• Each vulnerability gets a severity (critical, high, medium, low; override per plugin with severity) and a risk score from 0 to 10 built from impact, attack success rate and how easy the attack is to run.
• Always read failing rows before filing bugs: graders are LLMs. Tune them per plugin with config.graderGuidance (free-text rules that win on conflict) and config.graderExamples ({output, pass, score, reason}), then re-run with --filter-failing.
• Export the failing set for triage with jq, keep the retry strategy in the config so fixed vulnerabilities stay covered, and rerun the same label to compare releases.

CI Gates¶

Exit codes: 0 pass, 100 any failed row or pass rate below PROMPTFOO_PASS_RATE_THRESHOLD (percent), 1 other errors; PROMPTFOO_FAILED_TEST_EXIT_CODE renames 100. They apply to eval, redteam eval and redteam run.

export PROMPTFOO_PASS_RATE_THRESHOLD=90          # allow 10% failures in this job
npx promptfoo@latest eval -c evals/triage.yaml --no-cache \
  --tag git.sha="$GITHUB_SHA" -o results.json -o results.junit.xml

# .github/workflows/prompt-evals.yml
name: Prompt evals
on:
  pull_request:
    paths: ['prompts/**', 'evals/**']
jobs:
  eval:
    runs-on: ubuntu-latest
    permissions: { contents: read, pull-requests: write }
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '24' }
      - uses: actions/cache@v4
        with:
          path: .cache/promptfoo
          key: ${{ runner.os }}-promptfoo-${{ hashFiles('prompts/**') }}
          restore-keys: ${{ runner.os }}-promptfoo-
      - name: Run evals
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          PROMPTFOO_CACHE_PATH: ${{ github.workspace }}/.cache/promptfoo
          PROMPTFOO_PASS_RATE_THRESHOLD: '90'
          PROMPTFOO_DISABLE_TELEMETRY: '1'
        run: npx promptfoo@latest eval -c evals/triage.yaml -o results.json -o results.junit.xml
      - uses: actions/upload-artifact@v4
        if: always()
        with: { name: promptfoo-results, path: 'results.*' }

      # alternative step: before/after comparison of changed prompts, result summary posted on the PR
      - uses: promptfoo/promptfoo-action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          config: evals/triage.yaml
          prompts: 'prompts/**/*.txt'
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          cache-path: .cache/promptfoo
          fail-on-threshold: '90'          # success rate in percent
          repeat: '3'
          repeat-min-pass: '2'             # each test must pass 2 of 3 runs
          no-share: 'true'

The action needs Node.js >=22.22.0 on the runner (Node 24 recommended); other inputs include working-directory, promptfoo-version, max-concurrency, no-cache, disable-comment, env-files. Red team in CI is a plain CLI step: npx promptfoo@latest redteam run -c redteam/promptfooconfig.yaml -o redteam-results.json --tag git.sha=$GITHUB_SHA on a nightly schedule, with PROMPTFOO_PASS_RATE_THRESHOLD or a jq check on the JSON. On redteam run, -o redirects the generated-cases file and the results JSON is written to the same path, so give it a name of its own (-o results.json), never -o redteam.yaml.

Baseline comparison: run the suite on the base branch and on the PR, then compare stats or individual rows.

rate() { jq '.results.stats | .successes / (.successes + .failures + .errors)' "$1"; }
awk -v b="$(rate base.json)" -v h="$(rate head.json)" 'BEGIN { exit !(h + 0.02 >= b) }' \
  || { echo "pass rate dropped by more than 2 points"; exit 1; }

jq -rs '(.[0].results.results | map({key: "\(.testIdx)/\(.promptIdx)", value: .success}) | from_entries) as $base
  | .[1].results.results[] | select(.success | not) | select($base["\(.testIdx)/\(.promptIdx)"] == true)
  | "regressed: test \(.testIdx), prompt \(.promptIdx): \(.gradingResult.reason)"' base.json head.json

Cost and time control:

Library Mode¶

// scripts/gate.mjs  (npm install --save-dev promptfoo)
import promptfoo from 'promptfoo';

const evalRecord = await promptfoo.evaluate(
  {
    prompts: ['Question: {{question}}'],
    providers: [{ id: 'openai:chat:gpt-6-luna', config: { temperature: 0 } }],
    tests: [
      {
        vars: { question: 'How long do refunds take?' },
        assert: [
          { type: 'contains', value: '14 days' },
          { type: 'javascript', value: (output) => output.length < 200 },   // functions are allowed here
        ],
      },
    ],
    writeLatestResults: true,                  // makes the run visible in `promptfoo view`
  },
  { maxConcurrency: 2, cache: false },
);

const { successes, failures, errors } = (await evalRecord.toEvaluateSummary()).stats;
const rate = successes / (successes + failures + errors);
if (rate < 0.9) {
  console.error(`pass rate ${(rate * 100).toFixed(0)}% < 90%`);
  process.exitCode = 1;
}

prompts, providers and assert values may be functions; transform, transformVars and contextTransform accept functions (not persisted with writeLatestResults). The same API runs from Jest, Vitest or Mocha when a test runner should own the assertions.

Self-Hosting the Share Server¶

docker run -d --name promptfoo -p 3000:3000 \
  -v "$PWD/promptfoo_data:/home/promptfoo/.promptfoo" \
  ghcr.io/promptfoo/promptfoo:latest              # data (SQLite) lives in the mounted directory

export PROMPTFOO_REMOTE_API_BASE_URL=http://localhost:3000
export PROMPTFOO_REMOTE_APP_BASE_URL=http://localhost:3000
promptfoo eval --share                            # or `promptfoo share` for the latest eval

The same URLs can be set as sharing: {apiBaseUrl, appBaseUrl} in the config, and the container exposes /health. It is a single-instance server on SQLite with no built-in authentication: run one replica, put it behind your own access control, and set PROMPTFOO_SHARE_CHUNK_SIZE (e.g. 10) if a proxy rejects large uploads. Shared snapshots contain prompts, variables and outputs.

promptfoo vs Other Tools¶

Rule of thumb: promptfoo for provider-agnostic regression suites, prompt / model comparisons and red teaming straight from YAML; DeepEval or Ragas when metrics must live inside Python tests (pytest); Langfuse, LangSmith, Phoenix or MLflow when production traces and shared datasets are the main need. They combine well: promptfoo gates the PR, a tracing platform watches production, and failures found there become new promptfoo rows (eval harness overview, CI/CD).

Quick Rules¶

1. Exit code is the gate; archive results.json and JUnit XML with if: always().
2. Separate suites by speed: deterministic PR suite, wider nightly run, red team on a schedule.
3. Write a real purpose and keep the target label stable.
4. Select plugins by risk (presets for coverage, individual plugins for depth); add strategies deliberately, agentic ones cost the most.
5. Review graded failures before treating them as bugs; tune graders with graderGuidance and graderExamples.
6. Never aim red team runs at production with real accounts; use staging data and rate limits.
7. Pin the judge model and re-baseline when it changes.
8. Tag runs (--tag git.sha=...) so results from different pipelines are comparable.

See also¶

• promptfoo — LLM Evals & Red Teaming from YAML
• promptfoo — Test Cases & Assertions
• promptfoo — RAG, Agents & Multi-turn
• OWASP LLM Security
• Eval Harness — Tools, Testing & CI
• AI Harness
• CI/CD
• DeepEval — LLM Testing Guide
• Langfuse — LLM Tracing, Prompts & Evals
• LangSmith — LLM Tracing, Prompts & Evals
• Arize Phoenix — LLM Tracing & Evaluation
• MLflow — Experiment Tracking, LLM Tracing & Evaluation