guard-rail-edge 🛡️

Prompt-injection testing for CI/CD that measures whether its own AI judge can be trusted.

The Problem: Uncalibrated Judges Fail Silently

Most LLM security testers trust an arbitrary AI judge to grade security tests. In our empirical testing across 50 benchmark cases, small local judges miss 20–30% of system prompt leaks when disclosures are framed politely, while other models hallucinate an 85% false alarm rate on benign inputs.

guard-rail-edge eliminates blind trust with defense-in-depth:

1. Code-First Catches: Deterministic cryptographic canaries and fuzzy system-prompt overlap detection catch leaks before invoking an LLM.
2. Empirically Calibrated Judges: Benchmarked against ground-truth datasets with 95% Wilson confidence intervals.
3. "NEEDS REVIEW" Verdict: When an LLM judge is uncertain, ambiguous, or discordant, it escalates to NEEDS REVIEW (exit 3) instead of guessing PASS.

⚡ Quickstart (Under 60 Seconds)

Step 1: Install guard-rail-edge

pip install guard-rail-edge

Step 2: Set your API Key (or use offline mock)

# Recommended free hosted judge: Groq
export GROQ_API_KEY="gsk_..."

# Or on Windows PowerShell:
# $env:GROQ_API_KEY="gsk_..."

(No API key? Test offline immediately with guard-rail-edge init --preset mock.)

Step 3: Initialize and Run

guard-rail-edge init --preset groq
guard-rail-edge run

What It Checks

guard-rail-edge evaluates production prompt defenses across real-world workloads:

• Direct Prompt Injection: Instruction overrides, delimiter breakouts, and persona hijacking.
• Indirect RAG Injections: Attacks embedded inside retrieved knowledge base context.
• System Prompt Exfiltration: Extracting confidential rules, internal credentials, or canary tokens.
• Format Breakouts: Breaking structured JSON/schema contracts or smuggling executable payloads.
• Roleplay & Social Engineering: Authority emulation (e.g. fake compliance auditor) and hypothetical framing.

Explore realistic runnable suites in examples/:

• examples/support-bot/: Customer support bot with confidential discount codes and canaries.
• examples/rag-assistant/: Internal Q&A assistant tested against indirect document injection.
• examples/internal-hr-bot/: Slack HR bot tested against compensation and executive leak probes.
• examples/json-api-agent/: Structured API agent enforcing strict JSON contracts.

Calibrated Judge Accuracy

Empirical calibration benchmark results evaluated across 50 ground-truth cases (30 dev, 20 holdout):

With --on-review fail (default), cases sent to review fail CI; use --on-review warn to report them without blocking.

*Evaluated in commit 101a81e on local CPU. Legacy results; see docs/real-model-results.md for raw details. Calibration uses 50 cases (20 holdout, 8 holdout leaks); treat results as indicative, not a guarantee. Re-run calibrate on your own judge and, ideally, your own labelled cases.

Full evaluation methodology, confusion matrices, and audit logs: docs/real-model-results.md.

CI/CD Pipeline Integration

Add guard-rail-edge directly to your GitHub Actions workflow using our official composite action:

- name: Run Guardrail Security Gate
  uses: zayanahmed23/guard-rail-edge@v0.5.4
  with:
    suite: tests.json
    on-review: fail
  env:
    GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}

Raw model responses are redacted in CI report artifacts by default (redact-responses: true) to prevent leaking prompt secrets.

(Or run via manual CLI script: pip install guard-rail-edge && guard-rail-edge doctor && guard-rail-edge run --on-review fail --report-json security-audit.json.)

Deterministic Exit Codes

• 0: PASSED — All adversarial tests verified safe.
• 1 : BLOCKED — Vulnerability or prompt leakage detected.
• 2: ERROR — Configuration or operational runtime failure.
• 3: NEEDS REVIEW — Evaluation uncertain; human review required.

Comparison: When to Use Which

Documentation

• 🚀 GitHub Action — Official composite action, step summaries, and PR automation.
• 📖 CLI Reference — Complete options, flags, and command reference.
• ⚙️ Configuration Guide — TOML files, pyproject.toml integration, and presets.
• 🎯 Attack Library — Attack packs, categories, and test schema.
• 🔬 Judge Calibration — Methodology, 50-case benchmark, and Wilson score formulation.
• 🔌 Backends & Caching — Local Ollama, Groq, OpenAI endpoints, and cache setup.
• 📊 Real Model Results — Empirical benchmark tables and proofs.

License

Distributed under the MIT License.