AI Guard v0.2.0

Dual-plane AI security — static analysis CLI + runtime enforcement SDK — detecting and blocking prompt injection, API key leaks, unsafe output, RAG poisoning, agent hijacking, and more.

For the complete tutorial, open the dashboard at /tutorial or see docs/user-guide.md.

What it detects

| Category | Severity | Description | |---|---|---| | prompt-injection | Critical | Classic, jailbreak, multilingual, evasion, taint flow, zero-width chars | | api-key-leak | Critical | OpenAI, Anthropic, AWS, Stripe, GitHub, Cohere, Mistral + 6 more | | sensitive-data | High | PII, passwords, tokens, private keys in source or payloads | | unsafe-output | High | innerHTML, eval(), Function(), shell commands from model output | | ai-runtime-abuse | Critical | Tool argument injection, privilege escalation, RAG context poisoning | | rag-poisoning | Critical | Embedding injection, chunk splitting, metadata injection | | multimodal | High | Image alt-text, base64 data URIs, audio transcript injection | | supply-chain | Medium | Unpinned AI packages, Dockerfile :latest tags | | excessive-agency | High | Agent tool permissions, missing human approval gates | | model-theft | High | Model weight exposure, unauthenticated logits | | overreliance | Medium | Direct LLM output execution without validation | | training-data-poisoning | High | Untrusted dataset sources, unvalidated HTTP ingestion | | model-dos | Medium | Missing max_tokens, recursive agent loops, no input validation | | config-exposure | Medium | Hardcoded API keys, system prompts, model base URLs in config |

Install

npm install -g @scan5/ai-guard      # CLI (global)
npm install @scan5/ai-guard          # SDK (project dependency)

CLI Quickstart

ai-guard scan ./src                                    # Scan a directory
ai-guard scan https://github.com/owner/repo           # Scan a GitHub repo
ai-guard scan ./src --sarif report.sarif --json report.json  # CI outputs
ai-guard scan ./src --baseline baseline.json --ci-delta     # Delta mode
ai-guard scan ./src --siem-json siem-findings.ndjson        # Splunk/Datadog

SDK Quickstart

import { getSDK, wrapOpenAIClient } from "@scan5/ai-guard/sdk";

// Initialize with hard-block enforcement (default)
const sdk = getSDK({ enforcementMode: "hard-block" });

// Wrap your provider — scanning is automatic
const openai = wrapOpenAIClient(new OpenAI());

// Non-streaming: block before response if critical finding
const response = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: userInput }],
});
// If blocked: { object: "ai_guard.block", choices: [{ finish_reason: "ai_guard_blocked" }] }

// Streaming: interceptor scans chunks before delivery
const stream = await openai.chat.completions.create({
  stream: true,
  messages: [{ role: "user", content: userInput }],
});
// If critical finding mid-stream: terminates with [BLOCKED by AI Guard]

Provider Wrappers

import {
  wrapOpenAIClient, wrapAnthropicClient, wrapGeminiClient,
  wrapBedrockClient, wrapAzureOpenAIClient, wrapCohereClient,
  wrapMistralClient, wrapOllamaClient, wrapGenericOpenAICompatibleClient,
  wrapLangChainLLM, aiGuardMiddleware,
} from "@scan5/ai-guard/sdk";

Enforcement Modes

| Mode | Behavior | |---|---| | hard-block | Default. Blocks requests with critical findings. Non-streaming returns error object, streaming terminates with [BLOCKED]. | | shadow-block | Observes + logs warnings via X-AI-Guard-Warning headers. Marks wouldHaveBlocked. Never blocks. | | observe | Scans and logs only. No warnings, no blocks. |

const sdk = getSDK({ enforcementMode: "shadow-block" }); // validate before enabling

Observability

import { prometheusMetricsText, healthCheck } from "@scan5/ai-guard/sdk";

app.get("/metrics", (_, res) => res.type("text").send(prometheusMetricsText()));
app.get("/healthz", (_, res) => res.json(healthCheck()));

10 Prometheus metrics exposed: ai_guard_scans_total, ai_guard_findings_total, ai_guard_runtime_requests_total, ai_guard_runtime_requests_blocked_total, ai_guard_runtime_errors_total, and more.

Enterprise Features

• JWT auth — workspace-scoped HS256 tokens with refresh
• RBAC — 4-tier role hierarchy (owner > admin > member > viewer) on all endpoints
• Rate limiting — Redis-backed sliding window with in-memory fallback
• SSO — SAML 2.0 + OIDC infrastructure (config via AI_GUARD_SSO_MODE)
• Audit logging — batched writes to Supabase audit_logs table
• Alerting — Slack, Discord, email, webhook, SIEM with dedup + retry + escalation
• Docker — docker compose up for full stack (API + Web + Redis)
• Kubernetes — Helm chart with autoscaling, PDB, health probes

Docs

• Tutorial: 30-section guide at /tutorial in the dashboard
• SDK: SDK_README.md
• Integration: docs/user-guide/integration-express.md
• Operations: docs/operations/production-deployment-guide.md, docs/operations/incident-response.md

Test

npm test                    # All tests
npm run test:unit           # 320 unit tests
npm run test:integration    # Integration tests

Exit Codes

• 0: Scan completed successfully
• 1: Runtime failure
• 2: Validation/config/input error

License

MIT

Version History

• 0.2.0 — Enforcement (hard-block/shadow-block/observe), 4 new providers (Cohere/Mistral/Ollama/Generic), streaming interceptor, RBAC, JWT auth, rate limiting, RAG/multimodal/multilingual rules, Prometheus metrics, web dashboard with findings triage + compliance posture, SSO infrastructure, Redis state layer, Helm chart, audit logging, penetration test suite
• 0.1.1 — GitHub device login, repo scan auth flow
• 0.1.0 — Initial release: CLI scanner + SDK