@ny-squared/guard

Unified LLM Security SDK — Protect every AI call with one line of code.

Detects prompt injection, jailbreak attempts, PII exposure, and more. Works with OpenAI, Anthropic, and Google Gemini.

概要

@ny-squared/guard は、LLMアプリケーションにセキュリティレイヤーを1行で追加できる SDK です。

• Prompt Injection をリアルタイムで検出・ブロック
• 0〜100 のリスクスコア で脅威レベルを定量化
• OWASP Top 10 for LLM 2026 に完全準拠
• OpenAI / Anthropic / Google Gemini の3大プロバイダーに対応
• TypeScript 完全対応（型定義付き）
• ESM & CommonJS 両対応（import / require どちらでも動作）

既存の LLM クライアントをラップするだけで動作します。API の使い方は変わりません。

インストール

npm install @ny-squared/guard

Node.js 18+ required. No other runtime dependencies.

Quick Start

Scan a prompt directly

import { Guard } from '@ny-squared/guard';

const guard = new Guard(); // OSS mode — no API key, no network calls

const result = await guard.scan('Ignore all previous instructions and...');

if (!result.isSafe) {
  console.log('Blocked:', result.threats);
  // [{ type: 'injection', confidence: 0.95, detail: 'ignore all previous instructions', span: { start: 0, end: 43 } }]
} else {
  // safe to forward to your LLM
}

Wrap an OpenAI client (one-liner protection)

import { Guard } from '@ny-squared/guard';
import OpenAI from 'openai';

const guard = new Guard();
const openai = guard.wrap(new OpenAI()); // every call is now scanned automatically

// This will throw GuardBlockedError if the prompt is unsafe
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
});

Pro mode (ML-enhanced, cloud-backed)

const guard = new Guard({ apiKey: process.env.NYSQUARED_API_KEY });

Passing an apiKey switches to cloud mode automatically — same API, higher accuracy.

API Reference

new Guard(config?)

Creates a Guard instance. Omitting apiKey runs in OSS mode (local, rule-based).

const guard = new Guard({
  apiKey?: string;      // NY-squared Cloud API key. Omit for OSS mode.
  baseUrl?: string;     // Override the cloud API base URL.
  timeout?: number;     // Request timeout in milliseconds.
  retries?: number;     // Number of retries on network failure.
  onError?: 'throw' | 'log' | 'passthrough'; // Behaviour on unexpected errors.
});

guard.scan(prompt, options?): Promise<ScanResult>

Scans a prompt string and returns a ScanResult.

const result = await guard.scan(prompt, {
  checks?: ('injection' | 'jailbreak' | 'pii' | 'toxicity')[]; // subset of checks to run (default: all)
  threshold?: number;   // confidence threshold override (0–1)
  sanitize?: boolean;   // if true, return a redacted prompt in result.sanitized
});

Returns: ScanResult

guard.wrap<T>(client): T

Wraps an LLM client and returns the same client with every call automatically scanned.

• OpenAI (openai package ≥ 4): intercepts chat.completions.create — scans the last user message before sending, logs token usage after.
• Other clients are returned unchanged (pass-through).

const securedOpenAI = guard.wrap(new OpenAI());

If a prompt fails the scan, chat.completions.create throws GuardBlockedError before any network call is made.

guard.log(event): Promise<void>

Emits an audit event.

• OSS mode: writes to stdout as JSON.
• Cloud mode: POSTs to the NY-squared log endpoint.

await guard.log({ type: 'custom_event', userId: 'u_123', detail: '...' });

型定義

ScanResult

interface ScanResult {
  isSafe: boolean;       // false if any threat has confidence ≥ 0.8
  threats: Threat[];     // all detected threats (may be non-empty even when isSafe)
  sanitized?: string;    // redacted prompt, only present when sanitize: true
  latencyMs: number;     // time taken to scan, in milliseconds
  requestId: string;     // UUID for this scan request
}

Threat

interface Threat {
  type: 'injection' | 'jailbreak' | 'pii' | 'toxicity';
  confidence: number;                    // 0–1
  detail: string;                        // human-readable description of the match
  span?: { start: number; end: number }; // character offsets in the original prompt
}

エラーハンドリング

GuardBlockedError

Thrown by guard.wrap() when a prompt is unsafe. Extends Error.

import { GuardBlockedError } from '@ny-squared/guard';

try {
  await securedOpenAI.chat.completions.create({ ... });
} catch (err) {
  if (err instanceof GuardBlockedError) {
    console.log('Prompt blocked. Threats:', err.threats);
  }
}

OSS vs Pro

| Capability | OSS (no key) | Pro | |---|---|---| | scan() — rule-based detection | ✅ | ✅ ML-enhanced | | wrap() — LLM client proxy | ✅ | ✅ | | log() — audit logging | stdout | ✅ Cloud | | Accuracy (approximate) | ~70–80% | ~95%+ | | Network calls | None | Cloud API |

コントリビューション

Issue・PR はこちら： https://github.com/nysquared-support-ux/guard

バグ報告： https://github.com/nysquared-support-ux/guard/issues

ライセンス

Apache-2.0 License — © 2026 NY-squared, Inc.

https://github.com/nysquared-support-ux/guard/blob/main/LICENSE