shisa-ai/shisad
GitHub: shisa-ai/shisad
ShisaD 是一个安全优先的AI代理守护进程，通过运行时策略执行确保AI工具调用的安全性。
Stars: 24 | Forks: 4
# ShisaD (`shisad`)
[安全优先](docs/SECURITY.md)的 AI 代理守护进程框架。
ShisaD 是一个长期运行的守护进程，位于 LLM 与外部系统（工具、文件、网络、消息通道）之间。模型提出行动建议；运行时决定实际执行什么 —— 每次工具调用在执行前都必须通过策略执行、污染追踪和审计。
每个行动的核心问题是：**谁要求执行它？** ShisaD 是用户的代理 —— 它以最高保真度执行用户请求，并阻止其他任何控制（提示注入、幻觉、攻击者控制的输入）。
我们的设计没有回避关键问题，而是直面[致命三要素](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/)：能够访问私有数据、处理不可信内容并采取重大行动的代理本质上是高风险的。大多数代理安全研究通过移除功能直到代理安全但无用来解决此问题。ShisaD 采取[相反的方法](docs/DESIGN-PHILOSOPHY.md)：保持代理功能完备，并构建执行基础设施，使每个功能在运行时使用都是安全的。如果某个工具不安全，目标是修复执行机制，而不是禁用该工具。
```
┌─────────────────┐
│ LLM (Planner) │
Untrusted ─────────►│ [tokens mix] │─────────► Proposed
Content │ │ Actions
└─────────────────┘
│
═══════════════════════════════════════════════════════════
║ ARCHITECTURAL BOUNDARY ║
═══════════════════════════════════════════════════════════
│
▾
┌─────────────────┐ ┌─────────────┐
│ Trusted Config │ │ Security │
│ (policies, │ │ Analyzers │
│ goals) │ │ (metadata │
└─────────────────┘ │ only) │
└──────┬──────┘
▾
APPROVE / REJECT
```
## 功能特性
- **结构化长期记忆** —— 分离的身份、主动关注、回忆、过程和证据表面共享一个带版本控制的本地存储，具有来源控制的写入、高风险路径的审查门控以及可审计的来源
- **COMMAND/TASK 编排运行时** —— 持久化的 COMMAND 会话将委托的工作交接给隔离的 TASK 会话，提供污染安全的摘要、审批来源和明确的任务信封
- **逐调用策略执行** —— 8 层 PEP 管道（注册表、模式、能力、DLP、资源授权、出站白名单、凭证作用域、污染接收器执行）在每次工具调用时运行，而不仅仅是在会话开始时
- **污染感知的内容处理** —— 入站/出站内容防火墙通过执行路径追踪不可信输入的来源
- **确认门控，而非全面拒绝** —— 用户请求的操作继续执行；模糊或污染的操作路由至确认；仅真正的异常触发锁定
- **行为异常检测** —— 控制平面共识（5个独立投票器）用于运行时异常检测、速率限制、锁定升级以及在重复的可疑拒绝模式上向用户发出警告
- **破坏性命令保护** —— 在执行前由沙箱策略层强制执行，而非由 LLM 判断；无论提示注入或配置错误如何，结构上无法执行 `rm -rf /`
- **清洁室工作流** —— 管理员操作在污染隔离的会话模式下运行，无自动应用
- **多通道消息传递** —— Matrix、Discord、Telegram、Slack（Socket 模式），每个通道均有默认拒绝的身份白名单
- **助手原语** —— 便签/待办事项、带共享交付的调度器、网页搜索/抓取、基础浏览器自动化、文件系统/git 辅助工具以及大型不可信输出的证据引用
- **制品与证据边界** —— 重启稳定的证据引用、结构化的 ArtifactLedger 存储以及终端安全的证据渲染，默认将大型不可信内容隔离在原始提示路径之外
- **意图接地执行** —— 风险操作必须追溯到已提交的用户或清洁的 COMMAND 意图，缺失路径的读取路由至确认，缺失路径的副作用被阻止
- **提供商路由** —— 可插拔的 LLM 提供商预设（Shisa、OpenAI、OpenRouter、Google、本地 vLLM），支持每路由认证、模型选择和混合模式部署
- **工具表面完整性** —— 经过审查的本地技能可以声明工具，但其模式哈希在安装/重启/运行时期间被固定，发生漂移的已审查工具会以明确的审计可见性进行失败关闭，动态远程工具发现保持失败关闭状态
- **可观察性** —— 全面的审计跟踪、TUI 仪表板（待处理操作、任务、通道健康状况、警报）以及 `doctor` 诊断
## 状态
此仓库是公开的，仍处于预发布前阶段。最新发布的版本行是
`v0.7.3`：开放的线程/主题恢复、模糊时间线/档案搜索、
过程经验候选者，以及基于结构化长期记忆行的时间线/过程安全加固。
| 版本 | 重点 |
|---------|-------|
| v0.7 | 记忆基础 + 长期记忆表面（最新发布：`v0.7.3` 开放线程、时间线搜索和过程记忆试点） |
| v0.6 | 编排基础 + 工具表面扩展（COMMAND/TASK 运行时、凭证作用域、网页工具、浏览器基线） |
| v0.5 | 首次公开发布 —— 证据引用、仓库拆分、零配置 SHISA 提供商 |
| v0.4 | 自我修改、编码代理运行时、COMMAND/TASK 隔离 |
| v0.3 | 提供商路由、通道、助手工具、破坏性命令保护 |
| v0.2 | 结构重构（类型化处理器、分解运行时、覆盖率） |
| v0.1 | 核心守护进程、PEP 安全管道、控制 API |
此表追踪主要版本行以方便读者参考；补丁版本
如 `v0.5.1` 和 `v0.5.2` 保留在变更日志中，此处不列出。
详见 [`docs/ROADMAP.md`](docs/ROADMAP.md)。
## 入门指南
希望在自己的系统上设置 ShisaD 的用户和代理，请参阅 [`docs/DEPLOY.md`](docs/DEPLOY.md) 获取完整的部署指南 —— 主机引导、提供商配置、通道设置（Discord、Telegram、Slack）以及故障排除。ShisaD 设计为在专用实例或容器中运行，而非在你的开发环境内部。
### 快速开始
```
git clone https://github.com/shisa-ai/shisad.git
cd shisad
uv sync --group dev --extra chat
```
基于 YARA 的内容扫描通过
`textguard[yara]` 包含在基础安装中。要从源代码检出运行本地 PromptGuard 运行时检查，
请添加安全运行时依赖组：
```
uv sync --group security-runtime --group dev --extra chat
```
对于包安装，请使用一流的 PromptGuard 扩展，例如
`uv pip install 'shisad[promptguard]'`。 `security-runtime` 是一个 uv 依赖
组，而非 pip 扩展；使用 `--group security-runtime`，而非
`--extra security-runtime`。 `chat` 和 `promptguard` 包集合是
项目可选扩展，使用 `--extra chat` / `shisad[promptguard]`。
### 配置
环境变量使用 `SHISAD_` 前缀。完整参考：`docs/ENV-VARS.md`。
**推荐：本地开发使用 runner 工具**。它处理环境隔离、密钥加载和策略引导：
```
bash runner/harness.sh start # background (requires tmux)
bash runner/harness.sh start --fg # foreground
bash runner/harness.sh status
```
详见 `runner/README.md`。密钥放在 `runner/.env`（git忽略）或 `SHISAD_ENV_FILE` 中。
### 手动基线
```
export SHISAD_DATA_DIR="$HOME/.local/share/shisad"
export SHISAD_SOCKET_PATH="/tmp/shisad/control.sock"
export SHISAD_POLICY_PATH="$PWD/.local/policy.yaml"
export SHISAD_LOG_LEVEL="INFO"
```
### 提供商路由
默认（Shisa.AI）：
```
# Planner route remote-enables implicitly when SHISA key resolves.
export SHISA_API_KEY=""
```
OpenAI：
```
export SHISAD_MODEL_REMOTE_ENABLED=true
export OPENAI_API_KEY=""
export SHISAD_MODEL_PLANNER_PROVIDER_PRESET="openai_default"
export SHISAD_MODEL_PLANNER_MODEL_ID="gpt-5.4-2026-03-05"
# Optional: export SHISAD_MODEL_PLANNER_REQUEST_PARAMETERS='{"max_completion_tokens":512}'
```
OpenRouter：
```
export SHISAD_MODEL_REMOTE_ENABLED=true
export OPENROUTER_API_KEY=""
export SHISAD_MODEL_PLANNER_PROVIDER_PRESET="openrouter_default"
export SHISAD_MODEL_PLANNER_MODEL_ID="qwen/qwen3.5-397b-a17b"
export SHISAD_MODEL_PLANNER_EXTRA_HEADERS='{"HTTP-Referer":"https://example.com","X-Title":"shisad"}'
```
Google（OpenAI 兼容）：
```
export SHISAD_MODEL_REMOTE_ENABLED=true
export GEMINI_API_KEY=""
export SHISAD_MODEL_PLANNER_PROVIDER_PRESET="google_openai_default"
export SHISAD_MODEL_PLANNER_MODEL_ID="gemini-3.1-pro-preview"
```
本地 vLLM：
```
export SHISAD_MODEL_PLANNER_PROVIDER_PRESET="vllm_local_default"
export SHISAD_MODEL_PLANNER_BASE_URL="http://127.0.0.1:8000/v1"
export SHISAD_MODEL_PLANNER_REMOTE_ENABLED=true
export SHISAD_MODEL_PLANNER_AUTH_MODE="none"
```
混合模式（规划器远程，嵌入本地，监控器远程）：
```
export SHISAD_MODEL_REMOTE_ENABLED=true
export SHISAD_MODEL_PLANNER_PROVIDER_PRESET="openrouter_default"
export SHISAD_MODEL_PLANNER_MODEL_ID="qwen/qwen3.5-397b-a17b"
export SHISAD_MODEL_PLANNER_API_KEY=""
export SHISAD_MODEL_EMBEDDINGS_PROVIDER_PRESET="vllm_local_default"
export SHISAD_MODEL_EMBEDDINGS_BASE_URL="http://127.0.0.1:8000/v1"
export SHISAD_MODEL_EMBEDDINGS_REMOTE_ENABLED=true
export SHISAD_MODEL_EMBEDDINGS_AUTH_MODE="none"
export SHISAD_MODEL_EMBEDDINGS_MODEL_ID="text-embedding-3-small"
export SHISAD_MODEL_MONITOR_PROVIDER_PRESET="openai_default"
export SHISAD_MODEL_MONITOR_API_KEY=""
export SHISAD_MODEL_MONITOR_MODEL_ID="gpt-5.4-2026-03-05"
```
验证提供商设置：
```
uv run shisad doctor check --component provider
```
认证说明：
- 当需要自定义认证头名称时，请使用 `*_auth_mode=header`。
- `*_auth_header_name` 不接受 `*_auth_mode=bearer|none`。
### 通道
```
export SHISAD_DISCORD_ENABLED=true
export SHISAD_DISCORD_BOT_TOKEN=""
export SHISAD_TELEGRAM_ENABLED=true
export SHISAD_TELEGRAM_BOT_TOKEN=""
export SHISAD_SLACK_ENABLED=true
export SHISAD_SLACK_BOT_TOKEN=""
export SHISAD_SLACK_APP_TOKEN=""
# Default-deny allowlist: channel -> [external_user_id]
export SHISAD_CHANNEL_IDENTITY_ALLOWLIST='{"discord":["1234567890"],"telegram":["11111"],"slack":["U12345"]}'
```
### 助手表面
```
# web_fetch and web_search are enabled by default.
# web_search needs a compatible JSON search backend (SearxNG-style /search?q=...&format=json).
# The backend host must also be present in SHISAD_WEB_ALLOWED_DOMAINS.
export SHISAD_WEB_SEARCH_BACKEND_URL="https://search.example.com"
export SHISAD_WEB_ALLOWED_DOMAINS='["search.example.com","docs.example.com"]'
# Verify the configured tool surface from a live daemon:
# uv run python scripts/live_tool_matrix.py --tool-status
# Optional: browser automation baseline (read-mostly navigation plus
# confirmation-gated write actions). The built wheel does not install this
# source-checkout wrapper; package installs need an explicit compatible wrapper.
export SHISAD_BROWSER_ENABLED=true
export SHISAD_BROWSER_COMMAND="/path/to/shisad/scripts/shisad-playwright-cli.mjs"
export SHISAD_BROWSER_ALLOWED_DOMAINS='["example.com"]'
export SHISAD_ASSISTANT_FS_ROOTS='["/tmp/shisad-workspace"]'
```
## 用法
### 启动与验证
```
uv run shisad start --foreground
```
在另一个 shell 中：
```
uv run shisad status
uv run shisad doctor check --component all
uv run shisad tui --plain
```
### 会话
```
uv run shisad session create --user alice --workspace demo
uv run shisad session list
uv run shisad session message "summarize current priorities"
```
会话衍生的对话摘要默认可以在
会话具有 `memory.write` 时创建持久内存条目；当会话具有完整的 `--user` / `--workspace` 所有者元组时，生成的写入按所有者作用域限定。对于普通聊天不应创建自动记忆的干净演示或工作区，请设置
`SHISAD_MEMORY_AUTO_EXTRACTION_ENABLED=false`。运维人员还可以提高
`SHISAD_MEMORY_AUTO_EXTRACTION_CONFIDENCE_THRESHOLD`（从 `0` 向 `1`）以仅保留
更高置信度的自动提取建议。
### 时间线搜索
```
uv run shisad memory timeline search "what did we decide last week?" --user alice --workspace demo
uv run shisad memory timeline read --user alice --workspace demo
uv run shisad memory timeline promote --type fact --key project/decision --user alice --workspace demo
```
时间线搜索是显式拉取的。结果来自先前会话记录的归档证据，
而非当前用户指令，共享/公共通道上下文不会泄露所有者私有历史，除非为该请求显式允许私有历史。读取数据包包括角色、来源表面、来源、污染、证据引用和内容摘要；搜索/读取/提升决策记录在审计日志中，不包含原始查询或片段文本。对于共享通道上下文，使用 `--recipient`、`--workspace-hint` 和 `--thread-id` 传递具体的房间绑定，这样相同连接器/不同房间的历史记录保持隔离。
### 便签与待办事项
```
uv run shisad note create --key ops/runbook --content "verify doctor before deploy" --user alice --workspace demo
uv run shisad note list --user alice --workspace demo
uv run shisad todo create --title "close rollout checklist" --status open --user alice --workspace demo
uv run shisad todo list --user alice --workspace demo
```
### 网页与文件系统
```
uv run shisad web search "shisad security architecture" --limit 5
uv run shisad web fetch https://example.com
uv run shisad fs read /tmp/shisad-workspace/notes.txt
uv run shisad fs write /tmp/shisad-workspace/out.txt --content "hello" --confirm
uv run shisad git status --repo /tmp/shisad-workspace
```
### 管理员清洁室
```
uv run shisad session mode --mode admin_cleanroom
uv run shisad channel pairing-propose --limit 50
```
## 安全模型
shisad 假设提示注入会成功，并在模型外部构建执行机制。LLM 是规划器，而非执行器 —— 它提出工具调用建议，但运行时管道决定每次调用是继续执行、需要确认还是被阻止。无论多少提示注入、越狱或配置错误都无法覆盖执行层，因为它们在独立于模型的信任域中运行。
**问题所在**：任何能访问私有数据（文件、邮件）、暴露于不可信内容（网页、API 响应）并能够采取重大行动（发送消息、写入文件）的代理都是可被利用的。这就是[致命三要素](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/)。shisad 设计上具备所有这三个要素 —— 它旨在成为一个有用的助手，而非沙盒演示。
**方法**：shisad 没有移除功能直到代理安全（此时你已用额外步骤重建了 ChatGPT），而是保持所有功能可用，并在每次调用时强制执行安全性：
- 每个工具调用上的 **8 层 PEP 管道**：注册表检查、模式验证、能力检查、DLP（密钥模式检测）、资源授权、出站白名单、凭证主机作用域、污染接收器执行
- **污染追踪**：内容防火墙在入口处标记不可信输入，并在出口处强制执行来源感知限制 —— 运行时知道*谁要求*每个操作（用户 vs. 注入内容 vs. 模型幻觉）
- **确认门控**：用户请求的操作继续执行；来源模糊或污染的操作路由至用户确认并附带上下文；仅真正的异常触发锁定
- **行为异常检测**：控制平面共识（5 个独立投票器）捕获单个调用级别检查遗漏的模式
- **破坏性命令保护**：在执行前由沙箱层强制执行，而非由 LLM 判断 —— 无论模型被诱导提出什么建议，结构上无法执行 `rm -rf /`
**默认姿态**：所有工具开箱即用。需要限制性姿态的运维人员通过 `SHISAD_POLICY_PATH` 部署显式策略。
**出站模型**：白名单自动批准已知良好的目的地。显式用户请求无需确认即可继续。仅由不可信内容建议的目的地路由通过警告确认。未归因/幻觉漂移被阻止。
详见 `docs/SECURITY.md` 了解完整的安全架构，以及 `docs/DESIGN-PHILOSOPHY.md` 了解指导原则。
## 架构
```
shisad/
├── src/shisad/ # Core source
│ ├── daemon/ # Control API, handlers, runtime implementation
│ ├── security/ # PEP pipeline, content firewalls, taint tracking
│ ├── executors/ # Tool execution, egress proxy
│ ├── channels/ # Matrix, Discord, Telegram, Slack
│ ├── assistant/ # Notes, todos, web, fs/git tools
│ ├── memory/ # Structured storage with semantic search
│ ├── scheduler/ # Task scheduling and delivery
│ ├── cli/ # Click-based CLI
│ ├── ui/ # TUI dashboard
│ ├── skills/ # Hot-reloadable skill plugins
│ └── governance/ # Anomaly voting, consensus
├── tests/
│ ├── unit/ # Component tests
│ ├── integration/ # Cross-component runtime flows
│ ├── behavioral/ # Product-correctness gate
│ └── adversarial/ # Prompt injection, exfil, evasion
├── runner/ # Dev harness (tmux, env isolation, policy bootstrap)
├── scripts/ # Validation, coverage, asset checks
├── docs/ # Design docs, ADRs, runbooks, analysis
└── examples/ # Example configs and skills
```
关键运行时路径：
- 策略执行：`src/shisad/security/pep.py`
- 出站代理：`src/shisad/executors/proxy.py`
- 处理器实现：`src/shisad/daemon/handlers/_impl.py`（由 `_impl_session.py`、`_impl_tool_execution.py`、`_impl_memory.py` 等组合而成）
## 开发
```
uv run ruff check src/ tests/ scripts/
uv run mypy src/shisad/
uv run pytest -q
```
详见 `AGENTS.md` 了解完整的开发流程、验证矩阵和提交约定。
## 文档
| 文档 | 描述 |
|-----|-------------|
| `docs/DESIGN-PHILOSOPHY.md` | 第一性原理参考 —— 请先阅读此文档 |
| `docs/DEPLOY.md` | 公开部署和快速启动指南 |
| `docs/SECURITY.md` | 安全架构 —— 威胁模型、执行层、信任边界 |
| `docs/ROADMAP.md` | 公开路线图和里程碑方向 |
| `docs/USE-CASES.md` | 优先用例和能力映射 |
| `docs/ENV-VARS.md` | 环境变量参考 |
| `docs/TOOL-STATUS.md` | 当前工具表面快照 |
| `docs/adr/` | 架构决策记录 |
| `docs/analysis/` | 安全案例研究和供应链分析 |
| `docs/runbooks/` | 运维手册（浏览器设置、事件响应、密钥轮换、回滚、技能撤销） |
| `runner/RUNBOOK.md` | 开发工具运维手册 |
- [agentic-security](https://github.com/lhl/agentic-security) —— LLM 代理安全文献综述（78 篇论文、防御分类、生产就绪评估）
- [agentic-memory](https://github.com/lhl/agentic-memory) —— 代理内存架构和污染防御文献综述（29+ 参考文献、攻击分类、防御建议）
## 许可证
Apache License 2.0。见 `LICENSE`。
标签：AI代理, DLL 劫持, Lerna, 人工智能安全, 代理框架, 合规性, 外部系统集成, 大语言模型, 守护进程, 安全优先, 审计, 工具调用安全, 提示词模板, 污点跟踪, 策略执行, 网络安全, 逆向工具, 隐私保护