WhitzardAgent/qise

## 概述 Qise（发音为 "Cheese" 🧀）是一个开源的运行时安全框架，可**双向**保护 AI Agent： - **世界 → Agent**：阻止提示注入、工具投毒、记忆/知识库篡改和供应链攻击 - **Agent → 世界**：阻止危险命令、路径遍历、SSRF、数据泄露和策略违规 与容易绕过的纯规则解决方案不同，Qise 使用**分层 AI 模型**（SLM 快速筛选 + LLM 深度分析）来理解攻击*意图*，并以确定性规则作为快速路径和后备方案——**永不故障开放**。 ``` ┌─────────────────────────────────────────────────────────────────┐ │ Qise Security Framework │ │ │ │ ┌─── Soft Defense ──────────────────────────────────────────┐ │ │ │ SecurityContextProvider → Scene-aware rules injection │ │ │ │ ReasoningGuard → Chain-of-thought monitoring │ │ │ └───────────────────────────────────────────────────────────┘ │ │ ↓ still executes │ │ ┌─── Hard Defense (14 Guards) ─────────────────────────────┐ │ │ │ │ │ │ │ Ingress (World → Agent) │ │ │ │ ┌────────┐ ┌────────────┐ ┌─────────┐ ┌──────────────┐ │ │ │ │ │ Prompt │ │ ToolSanity │ │ Context │ │ SupplyChain │ │ │ │ │ │ Guard │ │ Guard │ │ Guard │ │ Guard │ │ │ │ │ └────────┘ └────────────┘ └─────────┘ └──────────────┘ │ │ │ │ │ │ │ │ Egress (Agent → World) │ │ │ │ ┌──────────┐┌─────────┐┌──────────┐┌────────┐┌──────┐ │ │ │ │ │Reasoning ││Command ││Filesystem││Network ││Exfil │ │ │ │ │ │ Guard* ││ Guard ││ Guard ││ Guard ││Guard │ │ │ │ │ └──────────┘└─────────┘└──────────┘└────────┘└──────┘ │ │ │ │ ┌──────┐ ┌──────┐ │ │ │ │ │Policy│ │Resrc │ │ │ │ │ │Guard │ │Guard │ │ │ │ │ └──────┘ └──────┘ │ │ │ │ │ │ │ │ Output (Audit) │ │ │ │ ┌──────────┐┌───────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │Reasoning ││Credential │ │ Audit │ │ Output │ │ │ │ │ │ Guard* ││ Guard │ │ Guard │ │ Guard │ │ │ │ │ └──────────┘└───────────┘ └──────────┘ └──────────┘ │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ │ ┌─── Shared Services ──────────────────────────────────────┐ │ │ │ ModelRouter (SLM <50ms + LLM <2s) │ ThreatPatternLoader │ │ │ │ BaselineManager (SHA-256) │ SessionTracker │ EventLogger │ │ │ └───────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ## 为什么选择 Qise | 问题 | Qise 的方法 | |---------|----------------| | 关键字规则容易被绕过 | AI 理解攻击语义，而不仅仅是模式匹配 | | 单一模型瓶颈 | 分层模型：SLM <50ms 快速筛选 + LLM 深度分析 | | 模型出错时故障开放 | 规则后备——**永不故障开放** | | 无数据泄露检测 | ExfilGuard：AI 优先的数据泄露检测 | | 无工具投毒检测 | ToolSanityGuard：哈希基线 + AI 语义分析 | | 静态安全指令 | 动态 SecurityContextProvider + Guard 执行 | | 需要修改代码 | 代理模式 / MCP 模式：零代码集成 | ## 三层决策流 每个 Guard 都使用相同的决策流——首先使用规则提高速度，然后使用 AI 分析语义，最后使用规则保障安全： ``` ┌──────────────────┐ │ Rule Fast-Path │ <1ms — deterministic BLOCK or PASS │ (regex, hash, │ e.g., "rm -rf /" → BLOCK │ patterns) │ For AI-first guards, only BLOCK short-circuits └────────┬─────────┘ (rule PASS flows to SLM for final say) │ uncertain or PASS (AI-first guards) ▼ ┌──────────────────┐ │ SLM Fast-Screen │ <50ms — semantic classification │ (≤4B model) │ e.g., obfuscated command → BLOCK └────────┬─────────┘ e.g., paraphrased injection → ESCALATE │ SLM can override low-confidence rule WARNs (<0.65) │ but not high-confidence ones (≥0.65) ▼ ┌──────────────────┐ │ LLM Deep Analysis│ <2s — full trajectory reasoning │ (8B-70B model) │ e.g., multi-turn attack chain → BLOCK └────────┬─────────┘ │ model unavailable ▼ ┌──────────────────┐ │ Rule Fallback │ <1ms — conservative defaults │ (never fail-open)│ e.g., WARN on uncertain + network tool └──────────────────┘ ``` **关键原则**：SLM 可以升级规则判定结果，但只能选择性地降级。信任边界隔离的 WARN（低置信度，<0.65）是预防性警告，SLM 可以通过内容分析覆盖它们。硬编码模式的 WARN（高置信度，≥0.65）是确定性发现，SLM 无法降级。 ## 纵深防御 四层防护，从软引导到硬执行： ``` Layer 0: SecurityContextProvider ┌─────────────────────────────────────────────┐ │ Inject scene-aware security rules into agent │ │ Agent follows voluntarily (~80% prevention) │ └──────────────────────┬──────────────────────┘ ↓ Agent ignores rules Layer 1: ReasoningGuard ┌─────────────────────────────────────────────┐ │ SLM detects manipulation in chain-of-thought │ │ Inserts safety reminders, lowers thresholds │ └──────────────────────┬──────────────────────┘ ↓ Agent still executes Layer 2: Guard Pipeline (14 Guards) ┌─────────────────────────────────────────────┐ │ Rule → SLM → LLM → Rule fallback │ │ BLOCK / WARN / APPROVE │ └──────────────────────┬──────────────────────┘ ↓ Action already executed Layer 3: OutputGuard + CredentialGuard ┌─────────────────────────────────────────────┐ │ Detect data leaks, PII, credentials │ └─────────────────────────────────────────────┘ ``` ## 快速开始 ### 安装 ``` pip install qise ``` ### 一键设置 ``` # 生成默认 config qise init # 检查 tool 调用 qise check bash '{"command": "rm -rf /"}' # → {"verdict": "block", "blocked_by": "command", ...} qise check bash '{"command": "ls"}' # → {"verdict": "pass", "blocked_by": null, "warnings": []} # 列出所有 guard 及其模式 qise guards ``` ### 零代码：代理模式 启动一个本地 HTTP 代理，拦截所有 Agent↔LLM 流量： ``` # 启动 proxy server qise proxy start --port 8822 --upstream https://api.openai.com # 将你的 agent 指向 proxy export OPENAI_API_BASE="http://localhost:8822/v1" ``` 代理实时拦截请求/响应，对所有 14 个 Guard 运行工具调用、注入尝试和输出泄露检查——支持 **SSE 流式传输**，实现零延迟文本透传。 ### 零代码：MCP 模式 添加到您 Agent 的 MCP 配置中： ``` { "mcpServers": { "qise": { "command": "python", "args": ["-m", "qise.mcp_server"] } } } ``` ### SDK 模式：框架适配器 **Nanobot:** ``` from qise import Shield from qise.adapters.nanobot import QiseNanobotHook shield = Shield.from_config() hook = QiseNanobotHook(shield) loop = AgentLoop(hooks=[hook]) ``` **LangGraph:** ``` from qise import Shield from qise.adapters.langgraph import QiseLangGraphWrapper shield = Shield.from_config() wrapper = QiseLangGraphWrapper(shield) safe_tools = [wrapper.wrap_tool_call(tool) for tool in my_tools] ``` **NexAU:** ``` from qise import Shield from qise.adapters.nexau import QiseNexauMiddleware shield = Shield.from_config() middleware = QiseNexauMiddleware(shield) agent = NexAUAgent(middlewares=[middleware]) ``` **OpenAI Agents SDK:** ``` from qise import Shield from qise.adapters.openai_agents import QiseOpenAIAgentsGuardrails shield = Shield.from_config() guardrails = QiseOpenAIAgentsGuardrails(shield) agent = Agent(guardrails=[guardrails.input_guardrail, guardrails.output_guardrail]) ``` **Hermes:** ``` from qise import Shield from qise.adapters.hermes import QiseHermesPlugin shield = Shield.from_config() plugin = QiseHermesPlugin(shield) plugin.register(ctx) ``` ### 运行测试 ``` pytest tests/ -v # 410 tests ``` ## 14 个 Guard 概览 ### 入站管道 (世界 → Agent) | Guard | 策略 | 检测内容 | |-------|----------|---------| | **PromptGuard** | AI 优先 (80/20) | 间接注入，多轮攻击，上下文投毒 | | **ToolSanityGuard** | AI 优先 (80/20) | 工具描述投毒，恶意替换，名称遮蔽 | | **ContextGuard** | AI+哈希 (70/30) | 记忆/知识库投毒，数据篡改，哈希完整性 | | **SupplyChainGuard** | AI+规则 (60/40) | 恶意技能，MCP 篡改，来源验证 | ### 出站管道 (Agent → 世界) | Guard | 策略 | 检测内容 | |-------|----------|---------| | **ReasoningGuard** \* | 纯 AI (100/0) | 思维链中的操纵痕迹，阈值调整 | | **CommandGuard** | 规则+AI (70/30) | Shell 注入，危险命令，权限提升 | | **FilesystemGuard** | 规则 (90/10) | 路径遍历，工作区违规，系统目录访问 | | **NetworkGuard** | 规则 (90/10) | SSRF，禁止域名，内网扫描 | | **ExfilGuard** | AI 优先 (80/20) | 数据泄露，隐蔽通道，DNS 数据外发 | | **ResourceGuard** | 规则+AI (60/40) | 无限循环，预算超支，熔断 | | **ToolPolicyGuard** | 规则 (100/0) | 未经授权的工具访问，拒绝/批准/仅限所有者 | ### 输出管道 (审计) | Guard | 策略 | 检测内容 | |-------|----------|---------| | **ReasoningGuard** \* | 纯 AI (100/0) | 思维链中的操纵痕迹，阈值调整 | | **CredentialGuard** | 规则 (100/0) | 输出中的 API 密钥，机密信息，令牌 | | **AuditGuard** | AI+规则 (50/50) | 攻击链重建，会话风险评分 | | **OutputGuard** | AI+规则 (70/30) | PII 暴露，知识库内容泄露，凭证泄露 | ## 5 个框架适配器 | 框架 | 适配器 | 挂载点 | 入站 | 出站 | 输出 | SecContext | |-----------|---------|-------------|---------|--------|--------|------------| | **Nanobot** | QiseNanobotHook | before_execute_tools, after_iteration | ✅ | ✅ | ✅ | ✅ | | **Hermes** | QiseHermesPlugin | pre/post_tool_call, transform_result, post_llm_call | ✅ | ✅ | ✅ | — | | **NexAU** | QiseNexauMiddleware | before/after_agent, before/after_model, before/after_tool | ✅ | ✅ | ✅ | ✅ | | **LangGraph** | QiseLangGraphWrapper | wrap/awrap_tool_call, pre_model_hook | — | ✅ | — | ✅ | | **OpenAI Agents** | QiseOpenAIAgentsGuardrails | input/output_guardrail, tool_input/output_guardrail | ✅ | ✅ | ✅ | — | 所有适配器都使用 **IngressCheckMixin + EgressCheckMixin** 基类——没有猴子补丁，仅使用官方的 Hook/Plugin/Middleware API。 ## 模型层 | 层级 | 模型 | 延迟 | 用途 | |------|-------|---------|-------| | SLM 快速筛选 | Qwen3-4B / Phi-4-mini | <50ms | 每次工具调用（AI 优先的 Guard） | | LLM 深度分析 | Claude / GPT / Qwen-72B | <2s | 仅当 SLM 升级时触发（约 5%） | | 规则后备 | 确定性规则 | <1ms | 当模型不可用时（永不故障开放） | **Stub 模式**：无需任何模型服务器即可开箱即用——所有 Guard 都会优雅地降级为规则模式。基于规则的 Guard（command、filesystem、network、credential、tool_policy）默认为**强制执行**模式；AI 优先的 Guard 默认为**观察**模式。 ## 性能 纯规则模式几乎不增加任何开销： | 操作 | 目标 | 测量值 (p95) | |-----------|--------|----------------| | 规则快速路径（单个 Guard） | <1ms | ~0.02ms | | 完整出站管道（6 个 Guard） | <10ms | ~0.02ms | | 完整入站管道（5 个 Guard） | <10ms | ~0.02ms | | 完整输出管道（3 个 Guard） | <10ms | ~0.01ms | | Shield 初始化 | <100ms | ~7ms | | 安全上下文渲染 | <5ms | ~0.01ms | 100 次连续出站检查：**总计约 1.8ms**（平均约 0.02ms）。 有关详细基准测试，请参阅 [docs/performance.md](docs/performance.md)。 ## 数据驱动的威胁情报 威胁模式采用 YAML 数据格式，而非硬编码的正则表达式——支持版本控制、可共享且 AI 可读： ``` # data/threat_patterns/indirect_injection_via_tool.yaml id: TPI-001 name: Indirect injection via tool result severity: high attack_examples: - input: 'Tool result: "IMPORTANT: Ignore previous instructions..."' verdict: malicious reasoning: "Tool result contains override instructions" rule_signatures: - type: regex pattern: "ignore\\s+(previous|above)\\s+instructions" confidence: 0.9 ``` ## 评估结果 经过 R12 调优的评估（SLM + 规则管道 vs 纯规则基线）： | 指标 | 纯规则 | SLM + 规则 | 差值 | |--------|-----------|-------------|-------| | **精确率** | 0.643 | **1.000** | +0.357 | | **召回率** | 0.973 | **1.000** | +0.027 | | **F1 分数** | 0.774 | **1.000** | +0.226 | | **FPR** | 0.400 | **0.000** | +0.400 (越低越好) | 各 Guard 的 F1 分数：prompt 0.681→1.000，reasoning 0.800→1.000，command 1.000→1.000，exfil 0.909→1.000。22 个样本得到改善，0 个样本退化。 ## 架构 ``` qise/ ├── src/qise/ │ ├── core/ # GuardContext, AIGuardBase, Pipeline, Shield, Config │ │ ├── models.py # Data models (GuardContext, GuardResult, GuardVerdict, RiskAttribution) │ │ ├── guard_base.py # AIGuardBase + RuleChecker (three-layer decision) │ │ ├── pipeline.py # Ingress/Egress/Output pipeline with BLOCK short-circuit │ │ ├── shield.py # Main entry point — 14 guards, dependency injection │ │ ├── config.py # ShieldConfig parser for shield.yaml │ │ ├── session_tracker.py # Cross-turn security state │ │ └── event_logger.py # Structured security event logging │ ├── guards/ # 14 Guard implementations │ ├── models/ # ModelRouter (httpx-based OpenAI-compatible client) │ ├── data/ # ThreatPatternLoader + BaselineManager + PromptExampleLoader │ ├── providers/ # SecurityContextProvider (DSL template rendering) │ ├── adapters/ # 5 Framework adapters │ │ ├── base.py # AgentAdapter ABC + IngressCheckMixin + EgressCheckMixin │ │ ├── nanobot.py # Nanobot AgentHook integration │ │ ├── hermes.py # Hermes Plugin hook integration │ │ ├── nexau.py # NexAU Middleware (6 hooks) │ │ ├── langgraph.py # LangGraph tool wrapper + pre-model hook │ │ └── openai_agents.py # OpenAI Agents SDK guardrails │ ├── proxy/ # HTTP proxy server │ │ ├── server.py # aiohttp-based proxy with SSE streaming │ │ ├── streaming.py # SSEStreamHandler with BufferedToolCall state machine │ │ ├── parser.py # Request/Response parser for OpenAI-compatible API │ │ ├── interceptor.py # ProxyInterceptor routing through Guard pipelines │ │ ├── context_injector.py # SecurityContext injection into system messages │ │ └── config.py # ProxyConfig with env overrides │ └── mcp_server.py # MCP Server (4 security check tools) ├── data/ │ ├── threat_patterns/ # 6 YAML threat patterns │ ├── security_contexts/ # 8 DSL security context templates │ └── prompts/ # 6 YAML few-shot example libraries (103 examples) ├── tests/ # 410 tests ├── eval/ # Evaluation datasets and results └── docs/ # Architecture, Guards, Threat Model, Integration ``` ## CLI 参考 ``` qise check bash '{"command": "rm -rf /"}' # Single security check qise serve # Start MCP Server qise proxy start --port 8822 # Start HTTP proxy qise init # Generate shield.yaml qise adapters # List framework adapters qise adapters nexau # Show integration code qise context bash # Get security context qise guards # List registered guards qise version # Print version ``` ## 文档 | 文档 | 描述 | |----------|-------------| | [架构](docs/architecture.md) | 系统设计，集成模式，核心接口 | | [Guards](docs/guards.md) | 详细的 Guard 规范和 AI/规则策略 | | [威胁模型](docs/threat-model.md) | 攻击分类，信任边界，防御链 | | [集成指南](docs/integration.md) | 代理/MCP/SDK 模式，桌面应用设置 | | [快速开始](docs/quickstart.md) | 5 分钟设置指南 | | [性能](docs/performance.md) | 延迟基准测试 | ## 集成模式 | 模式 | 所需代码 | 防御深度 | 最适合 | |------|--------------|---------------|----------| | **代理模式** | 0 行 | 完整（4 层） | 桌面用户，非开发人员 | | **MCP 模式** | 0 行 | 硬防御（14 个 Guard） | MCP 生态用户 | | **SDK 模式** | 1-5 行 | 完整（4 层）+ 最低延迟 | Agent 开发者 | ## 状态 | 组件 | 状态 | |-----------|--------| | 核心引擎（AIGuardBase、Pipeline、Shield） | ✅ 已完成 | | 14 个 Guard（Ingress + Egress + Output） | ✅ 已完成 | | ModelRouter（基于 httpx 的 SLM/LLM 客户端） | ✅ 已完成 | | 代理服务器（aiohttp + SSE 流式传输） | ✅ 已完成 | | 5 个框架适配器（Nanobot、Hermes、NexAU、LangGraph、OpenAI Agents） | ✅ 已完成 | | CLI（check / serve / proxy / init / adapters / context / guards / version） | ✅ 已完成 | | MCP Server（4 个安全检查工具） | ✅ 已完成 | | SecurityContextProvider（DSL 模板渲染） | ✅ 已完成 | | BaselineManager（SHA-256 哈希完整性） | ✅ 已完成 | | 软硬防御联动（active_security_rules） | ✅ 已完成 | | 结构化 SLM 提示（IS/NOT + few-shot） | ✅ 已完成 | | 动态 Few-Shot 加载（PromptExampleLoader） | ✅ 已完成 | | 基于置信度的 SLM 覆盖（<0.65 / ≥0.65） | ✅ 已完成 | | 410 个单元测试 + 集成测试 + 性能测试 | ✅ 已完成 | | 桌面应用（Tauri 2） | 🔜 计划中 | ## 许可证 [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) — 个人、学术和非商业免费。商业用途需另行获得许可。

标签：AI代理防护, AI安全, AI防火墙, AMSI绕过, Chat Copilot, CISA项目, DNS 反向解析, LLM, Petitpotam, Python, SLM, SSRF防护, Unmanaged PE, Web报告查看器, 云计算, 人工智能, 命令注入, 大语言模型安全, 威胁检测, 意图识别, 提示注入防护, 无后门, 机密管理, 深度防御, 用户模式Hook绕过, 网络安全, 规则引擎, 越权防护, 运行时操纵, 逆向工具, 隐私保护, 零日漏洞检测