Sapper AI (db94d0)

SapperAI

用于人工智能系统的轻量级、基于规则的安全框架。实时检测并阻止提示注入、命令注入等威胁。

具有工具调用功能的AI代理面临着严重的安全风险：

• 快速注射：用户输入中的恶意指令会覆盖系统行为
• 命令注入：通过工具执行的危险命令（rm-rf、SQL注入等）
• 数据渗漏：通过工具参数或LLM输出泄露的秘密

SapperAI提供 零依赖威胁检测 与：

• ✅ 96%检出率 （阻止了48/50个恶意样本）
• ✅ 零误报 （0/100良性样本被阻断）
• ✅ 亚毫秒延迟 （p99:0.0018ms仅适用于规则）
• ✅ 开放式设计失败 （可用性高于安全性）

快速开始

npm install sapper-ai
# or
pnpm install sapper-ai

import { createGuard } from 'sapper-ai'

const guard = createGuard()
const decision = await guard.check({ toolName: 'shell', arguments: { cmd: 'ls' } })

CLI：扫描->硬化（推荐）

# 1) Scan your repo (interactive in a TTY)
npx sapper-ai scan

# 2) If you skipped prompts, you can harden explicitly:
npx sapper-ai harden --apply

# 3) To include system-level protection (writes to your home directory):
npx sapper-ai harden --apply --include-system

CI友好扫描（确定性，无提示）：

npx -y sapper-ai@0.6.0 scan --policy ./sapperai.config.yaml --no-prompt --no-open --no-save

建筑

┌──────────────────────────────────────────────────────────────┐
│                        SapperAI Stack                        │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  @sapper-ai/types (11 types, no deps)                        │
│      │                                                       │
│      └─► @sapper-ai/core (60+ rules, policy engine)          │
│              │                                               │
│              ├─► @sapper-ai/mcp (stdio proxy + CLI)          │
│              │                                               │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Detection Pipeline:
  ToolCall → RulesDetector → DecisionEngine → Guard → Block/Allow

包裹

直接集成（高级）

import { AuditLogger, DecisionEngine, Guard, RulesDetector } from '@sapper-ai/core'
import type { Policy } from '@sapper-ai/types'

const policy: Policy = {
  mode: 'enforce',
  defaultAction: 'allow',
  failOpen: true,
}

const detector = new RulesDetector()
const engine = new DecisionEngine([detector])
const auditLogger = new AuditLogger()
const guard = new Guard(engine, auditLogger, policy)

const decision = await guard.preTool({
  toolName: 'executeCommand',
  arguments: { command: 'rm -rf /' },
})

if (decision.action === 'block') {
  throw new Error(`Blocked: ${decision.reasons.join(', ')}`)
}

检测能力

威胁类别（60+种模式）

• 快速注射：“忽略以前”、“系统提示”、“越狱”、“绕过”
• 命令注入: rm -rf /SQL注入(' OR '1'='1)，XXE
• 路径遍历: ../, /etc/passwd, /etc/shadow
• 数据外泄：API密钥、机密、， process.env
• 代码注入: eval(), __import__(), system()，模板注入

教育背景抑制

包含安全关键字的文档/教程的误报减少。

演出

基准测试结果（仅限规则管道，vitest bench）：

RulesDetector.run - small (50B)     737,726 ops/sec  p99: 0.0018ms
DecisionEngine.assess - small       391,201 ops/sec  p99: 0.0030ms
DecisionEngine.assess - large (5KB)  30,785 ops/sec  p99: 0.0424ms

验证指标（MVP）

• 测试覆盖率：80次测试（19种+50芯+11 mcp）
• 检测率：96%（48/50个恶意样本）
• 假阳性：0%（0/100良性样本）
• 边界情况：0%假阳性（0/20个边缘案例样本）
• 延迟：p99\<10ms（仅限规则）

安装

# Full monorepo (for development)
git clone https://github.com/sapper-ai/sapperai.git
cd sapperai
pnpm install
pnpm build

发展

# Build all packages
pnpm build

# Run tests (80 tests across 3 packages)
pnpm test

# Run deterministic security smoke tests
pnpm --filter @sapper-ai/core run test:smoke

# Type checking
pnpm exec tsc -b --noEmit

# Benchmarks
pnpm --filter @sapper-ai/core run bench

操作文档

• Runbook索引： docs/ops/README.md
• 观察+隔离： docs/ops/watch-quarantine.md
• 威胁情报+黑名单： docs/ops/threat-intel.md
• 对抗性活动： docs/ops/adversary.md

许可证

麻省理工学院