Metadata-Version: 2.4
Name: qise
Version: 0.1.0
Summary: AI-first runtime security framework for AI agents — 14 guards, 5 framework adapters, sub-ms rule checks
Project-URL: Homepage, https://github.com/opq-qise/qise
Project-URL: Documentation, https://github.com/opq-qise/qise/tree/main/docs
Project-URL: Repository, https://github.com/opq-qise/qise
Project-URL: Issues, https://github.com/opq-qise/qise/issues
Author: Qise Team
License-Expression: CC-BY-NC-SA-4.0
License-File: LICENSE
Keywords: agent-security,ai-agent,ai-security,guardrails,llm-security,prompt-injection,runtime-security
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Pydantic
Classifier: Intended Audience :: Developers
Classifier: License :: Free For Educational Use
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9
Requires-Dist: httpx>=0.25
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# 🧀 Qise

**AI-First Runtime Security Framework for AI Agents**

[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: CC BY-NC-SA 4.0](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-green.svg)](LICENSE)
[![Tests: 410 passed](https://img.shields.io/badge/Tests-410%20passed-brightgreen.svg)](tests/)
[![Guards: 14](https://img.shields.io/badge/Guards-14-orange.svg)](src/qise/guards/)
[![Adapters: 5](https://img.shields.io/badge/Adapters-5-purple.svg)](src/qise/adapters/)

[English](#overview) | [中文](./README_CN.md)

</div>

---

## Overview

Qise (pronounced "Cheese" 🧀) is an open-source runtime security framework that protects AI agents from **both directions**:

- **World → Agent**: Stops prompt injection, tool poisoning, memory/KB tampering, and supply chain attacks
- **Agent → World**: Stops dangerous commands, path traversal, SSRF, data exfiltration, and policy violations

Unlike rule-only solutions that are easily bypassed, Qise uses **layered AI models** (SLM fast-screen + LLM deep analysis) to understand attack *intent*, with deterministic rules as fast-path and fallback — **never fail-open**.

```
┌─────────────────────────────────────────────────────────────────┐
│                        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)                                   │ │
│   │  ┌─────────┐ ┌──────────┐ ┌────────┐ ┌──────┐ ┌──────┐ │ │
│   │  │ Command │ │Filesystem│ │Network │ │Exfil │ │Policy│ │ │
│   │  │  Guard  │ │  Guard   │ │ Guard  │ │Guard │ │Guard │ │ │
│   │  └─────────┘ └──────────┘ └────────┘ └──────┘ └──────┘ │ │
│   │                         + ResourceGuard                    │ │
│   │                                                           │ │
│   │  Output (Audit)                                           │ │
│   │  ┌───────────┐ ┌──────────┐ ┌──────────┐                 │ │
│   │  │Credential │ │  Audit   │ │  Output  │                 │ │
│   │  │   Guard   │ │  Guard   │ │  Guard   │                 │ │
│   │  └───────────┘ └──────────┘ └──────────┘                 │ │
│   └───────────────────────────────────────────────────────────┘ │
│                                                                 │
│   ┌─── Shared Services ──────────────────────────────────────┐ │
│   │  ModelRouter (SLM <50ms + LLM <2s) │ ThreatPatternLoader │ │
│   │  BaselineManager (SHA-256) │ SessionTracker │ EventLogger │ │
│   └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

## Why Qise

| Problem | Qise's Approach |
|---------|----------------|
| Keyword rules easily bypassed | AI understands attack semantics, not just pattern matching |
| Single model bottleneck | Layered models: SLM <50ms fast-screen + LLM deep analysis |
| Fail-open on model errors | Rule fallback — **never fail-open** |
| No exfiltration detection | ExfilGuard: AI-first data exfiltration detection |
| No tool poisoning detection | ToolSanityGuard: hash baseline + AI semantic analysis |
| Static safety instructions | Dynamic SecurityContextProvider + Guard enforcement |
| Requires code changes | Proxy mode / MCP mode: zero-code integration |

## Three-Layer Decision Flow

Every guard uses the same decision flow — rules first for speed, AI for semantics, rules last for safety:

```
  ┌──────────────────┐
  │ Rule Fast-Path   │  <1ms — deterministic BLOCK or PASS
  │ (regex, hash,    │  e.g., "rm -rf /" → BLOCK
  │  patterns)       │  e.g., matching hash → PASS
  └────────┬─────────┘
           │ uncertain
           ▼
  ┌──────────────────┐
  │ SLM Fast-Screen  │  <50ms — semantic classification
  │ (≤4B model)      │  e.g., obfuscated command → BLOCK
  └────────┬─────────┘  e.g., paraphrased injection → ESCALATE
           │ low confidence
           ▼
  ┌──────────────────┐
  │ 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
  └──────────────────┘
```

## Defense in Depth

Four layers protect from soft guidance to hard enforcement:

```
  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         │
           └─────────────────────────────────────────────┘
```

## Quick Start

### Install

```bash
pip install qise
```

### One-Command Setup

```bash
# Generate default config
qise init

# Check a tool call
qise check bash '{"command": "rm -rf /"}'
# → {"verdict": "block", "blocked_by": "command", ...}

qise check bash '{"command": "ls"}'
# → {"verdict": "pass", "blocked_by": null, "warnings": []}

# List all guards and their modes
qise guards
```

### Zero-Code: Proxy Mode

Start a local HTTP proxy that intercepts all Agent↔LLM traffic:

```bash
# Start proxy server
qise proxy start --port 8822 --upstream https://api.openai.com

# Point your agent at the proxy
export OPENAI_API_BASE="http://localhost:8822/v1"
```

The proxy intercepts requests/responses in real-time, running all 14 guards on tool calls, injection attempts, and output leaks — with **SSE streaming support** for zero-latency text passthrough.

### Zero-Code: MCP Mode

Add to your agent's MCP configuration:

```json
{
  "mcpServers": {
    "qise": {
      "command": "python",
      "args": ["-m", "qise.mcp_server"]
    }
  }
}
```

### SDK Mode: Framework Adapters

**Nanobot:**
```python
from qise import Shield
from qise.adapters.nanobot import QiseNanobotHook

shield = Shield.from_config()
hook = QiseNanobotHook(shield)
loop = AgentLoop(hooks=[hook])
```

**LangGraph:**
```python
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:**
```python
from qise import Shield
from qise.adapters.nexau import QiseNexauMiddleware

shield = Shield.from_config()
middleware = QiseNexauMiddleware(shield)
agent = NexAUAgent(middlewares=[middleware])
```

**OpenAI Agents SDK:**
```python
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:**
```python
from qise import Shield
from qise.adapters.hermes import QiseHermesPlugin

shield = Shield.from_config()
plugin = QiseHermesPlugin(shield)
plugin.register(ctx)
```

### Run Tests

```bash
pytest tests/ -v    # 410 tests
```

## 14 Guards at a Glance

### Ingress Pipeline (World → Agent)

| Guard | Strategy | Detects |
|-------|----------|---------|
| **PromptGuard** | AI-first (80/20) | Indirect injection, multi-turn attacks, context poisoning |
| **ReasoningGuard** | AI-only (100/0) | Manipulation traces in chain-of-thought |
| **ToolSanityGuard** | AI-first (80/20) | Tool description poisoning, rug pulls, name shadowing |
| **ContextGuard** | AI+hash (70/30) | Memory/KB poisoning, data tampering, hash integrity |
| **SupplyChainGuard** | AI+rules (60/40) | Malicious Skills, MCP tampering, source verification |

### Egress Pipeline (Agent → World)

| Guard | Strategy | Detects |
|-------|----------|---------|
| **CommandGuard** | Rules+AI (70/30) | Shell injection, dangerous commands, privilege escalation |
| **FilesystemGuard** | Rules (90/10) | Path traversal, workspace violations, system dir access |
| **NetworkGuard** | Rules (90/10) | SSRF, forbidden domains, internal network scanning |
| **ExfilGuard** | AI-first (80/20) | Data exfiltration, covert channels, DNS exfil |
| **ResourceGuard** | Rules+AI (60/40) | Infinite loops, budget overruns, circuit breaker |
| **ToolPolicyGuard** | Rules (100/0) | Unauthorized tool access, deny/approval/owner-only |

### Output Pipeline (Audit)

| Guard | Strategy | Detects |
|-------|----------|---------|
| **CredentialGuard** | Rules (100/0) | API keys, secrets, tokens in output |
| **AuditGuard** | AI+rules (50/50) | Attack chain reconstruction, session risk scoring |
| **OutputGuard** | AI+rules (70/30) | PII exposure, KB content leaks, credential leaks |

## 5 Framework Adapters

| Framework | Adapter | Hook Points | Ingress | Egress | Output | 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 | ✅ | ✅ | ✅ | — |

All adapters use the **IngressCheckMixin + EgressCheckMixin** base classes — no monkey-patching, only official Hook/Plugin/Middleware APIs.

## Model Layer

| Tier | Model | Latency | Usage |
|------|-------|---------|-------|
| SLM fast-screen | Qwen3-4B / Phi-4-mini | <50ms | Every tool call (AI-first guards) |
| LLM deep analysis | Claude / GPT / Qwen-72B | <2s | Only when SLM escalates (~5%) |
| Rule fallback | Deterministic rules | <1ms | When models unavailable (never fail-open) |

**Stub mode**: Works out of the box without any model server — all guards degrade to rules gracefully. Rules-based guards (command, filesystem, network, credential, tool_policy) default to **enforce** mode; AI-first guards default to **observe** mode.

## Performance

Rule-only mode adds virtually zero overhead:

| Operation | Target | Measured (p95) |
|-----------|--------|----------------|
| Rule fast-path (single guard) | <1ms | ~0.02ms |
| Full egress pipeline (6 guards) | <10ms | ~0.02ms |
| Full ingress pipeline (5 guards) | <10ms | ~0.02ms |
| Full output pipeline (3 guards) | <10ms | ~0.01ms |
| Shield initialization | <100ms | ~7ms |
| Security context render | <5ms | ~0.01ms |

100 sequential egress checks: **~1.8ms total** (~0.02ms avg).

See [docs/performance.md](docs/performance.md) for detailed benchmarks.

## Data-Driven Threat Intelligence

Threat patterns are YAML data, not hardcoded regex — versionable, shareable, and AI-readable:

```yaml
# 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
```

## Architecture

```
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
│   ├── 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
├── tests/                 # 410 tests
└── docs/                  # Architecture, Guards, Threat Model, Integration
```

## CLI Reference

```bash
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
```

## Documentation

| Document | Description |
|----------|-------------|
| [Architecture](docs/architecture.md) | System design, integration modes, core interfaces |
| [Guards](docs/guards.md) | Detailed Guard specifications and AI/rule strategies |
| [Threat Model](docs/threat-model.md) | Attack taxonomies, trust boundaries, defense chains |
| [Integration Guide](docs/integration.md) | Proxy/MCP/SDK modes, desktop app setup |
| [Quick Start](docs/quickstart.md) | 5-minute setup guide |
| [Performance](docs/performance.md) | Latency benchmarks |

## Integration Modes

| Mode | Code Required | Defense Depth | Best For |
|------|--------------|---------------|----------|
| **Proxy Mode** | 0 lines | Full (4 layers) | Desktop users, non-developers |
| **MCP Mode** | 0 lines | Hard defense (14 guards) | MCP ecosystem users |
| **SDK Mode** | 1-5 lines | Full (4 layers) + lowest latency | Agent developers |

## Status

| Component | Status |
|-----------|--------|
| Core engine (AIGuardBase, Pipeline, Shield) | ✅ Complete |
| 14 Guards (Ingress + Egress + Output) | ✅ Complete |
| ModelRouter (httpx-based SLM/LLM client) | ✅ Complete |
| Proxy Server (aiohttp + SSE streaming) | ✅ Complete |
| 5 Framework Adapters (Nanobot, Hermes, NexAU, LangGraph, OpenAI Agents) | ✅ Complete |
| CLI (check / serve / proxy / init / adapters / context / guards / version) | ✅ Complete |
| MCP Server (4 security check tools) | ✅ Complete |
| SecurityContextProvider (DSL template rendering) | ✅ Complete |
| BaselineManager (SHA-256 hash integrity) | ✅ Complete |
| Soft-Hard Defense Linkage (active_security_rules) | ✅ Complete |
| 410 unit + integration + performance tests | ✅ Complete |
| Desktop App (Tauri 2) | 🔜 Planned |

## License

[CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) — Free for personal, academic, and non-commercial use. Commercial use requires separate permission.
