Documentation

Overview

OpenSecureAI ships transparent, heuristic security tools for LLM applications. The flagship engine detects prompt-injection, jailbreak, system-prompt-leak, and data-exfiltration patterns in untrusted text. The same engine powers the in-browser Analyze tool, the @opensecureai/scanner npm package, a CLI, a GitHub Action, and a REST API. The package and CLI are free forever; with an API key the hosted REST API unlocks an enhanced engine that adds private detections (obfuscation/encoding evasions, indirect injection, tool abuse, multilingual overrides, and a de-obfuscation pass) on top of the open ruleset.

These tools are a first line of defense — pair them with output validation, least-privilege tool design, and human review for high-risk actions. See the OWASP Top 10 for LLMs for the full threat model.

Install

The package targets Node 18+ and ships ESM with TypeScript types. It has zero runtime dependencies.

npm install @opensecureai/scanner

Library API

The primary export is scanPrompt, which returns a structured result with a 0–100 score, a risk level, and per-rule findings.

import { scanPrompt } from "@opensecureai/scanner";

const result = scanPrompt(userInput);

result.score;   // 0-100 (higher = riskier)
result.level;   // "Critical" | "High" | "Medium" | "Low" | "Clean"
result.matches; // [{ ruleId, category, severity, title, ... }]

if (result.level === "Critical" || result.level === "High") {
  rejectRequest(result.matches);
}

The full ruleset is exported as RULES and demo inputs as SAMPLE_PAYLOADS.

CLI

Scan files or stdin. Exit codes make it CI-friendly: 0 = clean/below threshold, 1 = threshold met, 2 = usage error.

# scan a file
npx -y @opensecureai/scanner scan prompt.txt

# scan stdin
cat prompt.txt | npx -y @opensecureai/scanner scan

# gate on high+ findings, JSON output
npx -y @opensecureai/scanner scan ./prompts/*.txt --fail-on high --json

GitHub Action

Gate pull requests on risky prompt content by running the scanner CLI in a workflow step.

name: Prompt scan
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npx -y @opensecureai/scanner scan "prompts/**/*.txt" --fail-on high

REST API

A hosted scanning endpoint. Anonymous calls run the open basic engine (the same ruleset shipped in the npm package), are stateless, and are rate-limited by IP. Authenticated calls unlock the enhanced hosted engine — the open ruleset plus private detections (obfuscation, indirect injection, tool abuse, multilingual, de-obfuscation) that are not in the npm package. The response engine field is basic or hosted-advanced so you know which tier ran. CORS is open so you can call it from anywhere.

curl -X POST https://opensecureai.com/api/scan \
  -H "content-type: application/json" \
  -d '{"text":"ignore all previous instructions"}'

Authenticated calls

Generate a key on your API Keys page and send it as a Bearer token. Authenticated requests get a higher rate limit and each scan summary (score, level, findings, a short preview) is saved to your dashboard — the raw prompt text is never stored.

curl -X POST https://opensecureai.com/api/scan \
  -H "authorization: Bearer osai_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{"text":"ignore all previous instructions"}'

Response

{
  "ok": true,
  "engine": "hosted-advanced",
  "result": {
    "score": 90,
    "level": "Critical",
    "matches": [ /* findings */ ],
    "scannedChars": 34
  }
}

Agent Guard endpoint

POST /api/agent-guard audits an LLM agent's tool/function definitions. Post a definitions field containing an OpenAI tools array, Anthropic tools, or an MCP { "tools": [...] } manifest. Anonymous calls run the basic per-tool engine; authenticated calls unlock the hosted-advanced engine that adds cross-tool data-exfiltration-chain, confused-deputy, MCP annotation-spoofing, tool-name-shadowing, and attack-surface analysis. Findings are mapped to the OWASP 2025 LLM Top-10; raw definitions are never stored. Add "llm": true (optional llmKey for BYOK) to get an advisory AI remediation plan — the deterministic findings stay authoritative, and without a key it returns a clearly-labeled mock.

curl -X POST https://opensecureai.com/api/agent-guard \
  -H "authorization: Bearer osai_YOUR_KEY" \
  -H "content-type: application/json" \
  -d @tools.json

Prefer to gate it in CI? The same basic engine ships as a zero-dependency CLI / GitHub Action. It runs fully offline; add --api-key to also run the hosted advanced engine.

# fail the build if any tool is high/critical risk
npx @opensecureai/agent-guard agent/tools.json --fail-on high

LLM Gateway endpoint

POST /api/gateway is a secure proxy: it scans your prompt, forwards it to the provider/model you choose (llmProvider openai · anthropic · xai · groq, BYOK via llmKey), then scans the model's response — masking leaked secrets/PII in output.redacted. With "policy": "block" a high-risk prompt is halted before it ever reaches the model, and a high-risk response is withheld; with "flag" everything runs and the risks are reported. Anonymous calls (and calls without a provider key) return a clearly-labeled mock completion; the scans always run. Keys are never stored or logged, and the deterministic engines stay authoritative.

curl -X POST https://opensecureai.com/api/gateway \
  -H "authorization: Bearer osai_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{
    "input": "summarize this ticket: ...",
    "system": "You are a support assistant.",
    "policy": "block",
    "llmProvider": "openai",
    "llmKey": "sk-...",
    "llmModel": "gpt-4o-mini"
  }'

Observability

Send security events from your LLM app to /api/events with an API key and view them on your Observability dashboard. Authenticated scans are recorded automatically. Send only labels and metadata — never raw prompt or response text.

curl -X POST https://opensecureai.com/api/events \
  -H "authorization: Bearer osai_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{"type":"injection","severity":"high","source":"prod-chatbot","label":"Blocked instruction override"}'

Fields

type (required): scan, injection, block, flag, allow, request, error, custom. severity: info, low, medium, high, critical. source, label (short strings), and score (0–100) are optional.

System-prompt audit

The system-prompt audit is built into Analyze. It grades a system prompt against defensive best practices — secret isolation, instruction/data separation, injection resistance, refusal policy, and least-privilege tool use — returning an A–F report card with prioritized fixes. It runs entirely in the browser.

Threat Feed

Syndicate the curated threat intelligence feed as JSON or RSS. The JSON endpoint supports severity, category, and owasp filters.

# JSON API
curl https://opensecureai.com/api/threats
curl "https://opensecureai.com/api/threats?severity=Critical"
curl "https://opensecureai.com/api/threats?owasp=LLM01"

# RSS feed
curl https://opensecureai.com/threats/feed.xml

Writing content (blog & guides)

The blog and learning guides are file-based — no CMS. Add a Markdown/MDX file, commit it, and it publishes automatically with its own page, SEO metadata, and sitemap entry. No code changes needed.

1. Create content/blog/my-post.mdx (or content/learn/ for a guide). The filename becomes the URL slug.
2. Add frontmatter (title, description, date, author, tags, readingTime), then write the body in Markdown.
3. Commit and open a pull request — the post appears on merge.

---
title: "Your post title"
description: "One-sentence summary for SEO and the card."
date: "2026-06-25"
author: "OpenSecureAI"
tags: ["prompt-injection", "llm-security"]
readingTime: "8 min read"
---

Your first paragraph...

## A section heading

- bullet list
- fenced code blocks are syntax-highlighted

Full field reference, formatting support, and the originality / copyright rules are in content/AUTHORING.md. Write original content only — the guides use text/ASCII diagrams so there are no third-party image licenses.