Mastyf.ai

mastyf.ai

守护操作边界，而不只是提示词。

面向 AI Agent 和 MCP 的本地引用监控器与安全网关。
你的大模型提出操作，Mastyf 决定这些操作能否触达真实世界。

网站 · 快速入门 · 策略 · 仪表板 · GitHub

说明

**企业版与云平台支持：**Mastyf 已通过验证，并作为原生 CONTENT_AUTHZ 服务扩展部署在 Google Cloud Agent Gateway（us-central1）上，具备分布式 Redis 状态、亚秒级故障关闭执行以及实时 BigQuery 审计日志记录。请参阅 Google Agent Gateway 操作手册。

---

问题

AI Agent 可以读取文件、推送代码、查询数据库、执行 shell 命令并调用外部 API。它们以机器速度自主执行这些操作。

传统安全控制并非为此而设计。

Mastyf.ai 充当 AI 的边界安全层。它会拦截每次工具调用，使用多 Agent 群体分析，根据安全策略进行评估，并在恶意或未经授权的操作执行前将其拦截。

每项决策都会得到强制执行、记录和审计。

---

可拦截的威胁

威胁	表现形式
提示词注入	嵌入工具参数中的恶意指令，用于劫持 Agent 行为
路径遍历	尝试访问 /etc/passwd、.ssh/id_rsa、.aws/credentials
密钥外泄	API 密钥和令牌通过工具参数泄漏
Shell 注入	反向 shell、rm -rf、编码后的 PowerShell 命令
数据外泄	批量 SQL 转储、git push、aws s3 cp、未经授权的文件传输
SSRF	对元数据端点、localhost 和私有 IP 地址范围发起调用
编码规避	利用 Base64 数据块和 Unicode 同形字符绕过模式检测
成本滥用	Agent 循环失控，耗尽令牌预算
Rug-pull 攻击	工具定义在会话中途悄然变更

---

快速入门

🛡️ Mastyf 安全网关与受保护的 Agent（Python 快速入门）

运行本地参考监视器、MCP 发现功能和自然语言受保护 Agent 运行时：

# Install Mastyf Gateway package
git clone https://github.com/mastyf-ai/mastyf.ai.git
cd mastyf.ai/mastyf_gateway
pip install -e .

# Launch Mastyf (Auto-discovers tools, prompts for permissions, and starts protected agent)
mastyf

• 首次运行时，Mastyf 会自动发现本地 MCP 服务和工具，使用自然语言询问你希望授予的权限，展示保守的差异对比，并在你确认后启用策略。
• 对话式 Agent 提出的每个工具调用都会被参考监视器拦截（$A = \text{CBAC} \cap \text{DIFC} \cap \text{Workflow}$）。对于非 ALLOW 操作，发送到工具后端的数据严格为 0 字节。
• 包含实时安全 HUD和加密回执审计链（mastyf audit verify）。

常用 CLI 命令

# Start interactive protected agent (or first-run onboarding if fresh install)
mastyf

# Run a single query non-interactively
mastyf -m "Find unpaid customer invoices"

# Propose a policy change in plain English
mastyf policy "Allow reading invoices, but never delete data or make HTTP calls"

# Inspect staged proposed policy vs active policy diff
mastyf policy status

# Promote staged policy to active enforcement
mastyf policy activate

# Intercept an MCP server via stdio reverse proxy
mastyf proxy -- uvx mcp-server-sqlite --db /tmp/test.db

# Cryptographically verify the tamper-evident execution receipt ledger
mastyf audit verify --ledger ~/.mastyf/receipts.jsonl

# Run local action boundary failure mode demonstrations
mastyf demo --scenario all

---

从源代码构建（TypeScript / 云平台）

克隆代码库并运行设置脚本。

要求：

• Git
• Linux（如果尚未安装 Nix，设置脚本会自动安装）

git clone https://github.com/mastyf-ai/mastyf.ai.git
cd mastyf.ai
chmod +x setup.sh
./setup.sh

设置脚本会自动：

• 安装 Nix（如有需要）
• 启用 Nix flakes
• 创建开发环境
• 安装所有项目依赖项
• 重新构建原生软件包
• 构建整个项目
• 添加便捷的 mastyf shell 别名

安装完成后，启动代理和仪表板：

node dist/cli.js start

或者打开新终端后直接使用别名：

mastyf

仪表板将在以下地址提供：

• 仪表板：http://localhost:4000

---

测试安装

如果仪表板正在运行，请验证 HTTP 桥接：

curl -X POST http://localhost:4000/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

---

仪表板

全面了解 AI 执行的每项操作。

---

区域	内容
防护	拦截率、触发次数最多的规则、实时威胁动态
活动	每次工具调用的完整参数、允许或拦截状态、时间戳
策略	实时规则编辑器，支持从 YAML 热重载
威胁实验室	AI 建议的攻击测试，须经审核和批准后才会生效
成本	按工具调用细分的 Token 用量和成本估算

仪表板默认启用身份验证，包括本地回环地址。启动脚本会创建 $MASTYF_HOME/dashboard_api_key，但绝不会打印其内容。只有在明确隔离的本地测试中才设置 DASHBOARD_AUTH_DISABLED=true——如果绑定到非本地回环地址，则不允许这样配置。

---

强制执行机制

每次工具调用到达你的基础设施之前，都会经过三层检查。

第 1 层 - 模式检测 通过基于正则表达式的扫描，检测注入、危险路径、泄露的机密、shell 命令和编码技巧。扫描在微秒内完成，无需外部依赖项。

第 2 层 - 架构验证 在进入策略评估之前，拒绝格式错误的负载、超大参数和违反 JSON-RPC 规范的请求。

第 3 层 - 语义审核 可选的本地 LLM（Ollama）或云端模型会评估通过模式检查的边界情况调用。如果未配置模型，则回退到启发式方法。

任何未通过检查的调用都会被拦截。工具不会运行。所有内容都会记录。

---

策略

规则位于 default-policy.yaml 中。由你掌控，mastyf.ai 负责执行。

policy:
  mode: block
  default_action: pass
  unicode_strict: true
  rules:
    - name: block-sensitive-paths
      action: block
      argPatterns:
        - field: path
          patterns: ['^/etc/', '/\.ssh', '/\.aws/credentials']

    - name: rate-limit-tool-calls
      action: block
      maxCallsPerMinute: 120

    - name: block-shell-injection
      action: block
      patterns: ['rm\s+-rf', 'curl\s', 'wget\s', '`[^`]+`']

通过三种强制执行模式安全地逐步上线：

模式	行为	适用时机
audit	记录所有内容，不拦截任何操作	第一周，了解 AI 的行为
warn	记录并标记，但仍会转发	强制执行前的调优阶段
block	在执行前阻止违规操作	生产环境

policy-templates/ 中提供了 HIPAA、PCI-DSS、GxP 和数据驻留的预置模板。

---

架构

mastyf.ai 运行着两支协同工作的蜂群。CI 蜂群会在代码发布前检验你的策略。运行时蜂群会在生产环境中强制执行策略，并从每次实时工具调用中学习。四个反馈循环将两者连接起来，让系统随着时间推移越来越难以绕过。

flowchart TB

  AI["🤖 AI Clients\nCursor · Claude Desktop · Cline"]

  subgraph CI["🔵 CI Swarm (PR + Nightly)"]
    direction LR
    Scout["🔍 Scout Agent\nSAST, deps, config scan"]
    Corpus["📋 Corpus Agent\n228 fixtures eval"]
    Evasion["⚡ Evasion Agent\n120+ probes + generate new"]
    Parity["🔄 Parity Agent\nNode vs Python"]
    ProxyA["🖥️ Proxy Agent\nLive stdio MCP tests"]
    Report["📊 Report Agent\nsecurity-swarm/latest.json"]
    Scout --> Corpus --> Evasion --> Parity --> ProxyA --> Report
  end

  subgraph Runtime["🟢 Runtime Swarm (Production Proxy)"]
    direction LR
    BG["🛡️ BlockGuard\nsync policy"]
    IL["📈 InstantLearner\nper-block stats + suggestions"]
    SA["🧠 SemanticAuditor\nasync LLM, optional"]
    PS["🔗 PatternSynthesizer\nbatch suggestions"]
    Cal["⚙️ Calibrator\nlabels + thresholds"]
    BG --> IL --> PS --> Cal
    BG --> SA --> PS
  end

  Tools["🗄️ MCP Tools\nfilesystem · GitHub · databases · APIs"]

  AI -->|"every tool call"| BG
  BG -->|"✅ allowed"| Tools
  Report -->|"🔁 Loop A: bypasses to corpus"| Corpus
  Cal -->|"🔁 Loop B: blocks to rules"| BG
  Cal -->|"🔁 Loop C: labels to LLM"| SA
  Report -->|"🔁 Loop D: CI metrics weekly"| Cal

  style CI fill:#EFF6FF,stroke:#3B82F6,stroke-width:2px,color:#1E3A5F
  style Runtime fill:#F0FDF4,stroke:#22C55E,stroke-width:2px,color:#14532D
  style Scout fill:#DBEAFE,stroke:#3B82F6,color:#1E40AF
  style Corpus fill:#DBEAFE,stroke:#3B82F6,color:#1E40AF
  style Evasion fill:#DBEAFE,stroke:#3B82F6,color:#1E40AF
  style Parity fill:#DBEAFE,stroke:#3B82F6,color:#1E40AF
  style ProxyA fill:#DBEAFE,stroke:#3B82F6,color:#1E40AF
  style Report fill:#DBEAFE,stroke:#3B82F6,color:#1E40AF
  style BG fill:#BBF7D0,stroke:#16A34A,color:#14532D
  style IL fill:#BBF7D0,stroke:#16A34A,color:#14532D
  style SA fill:#BBF7D0,stroke:#16A34A,color:#14532D
  style PS fill:#BBF7D0,stroke:#16A34A,color:#14532D
  style Cal fill:#BBF7D0,stroke:#16A34A,color:#14532D
  style AI fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px,color:#78350F
  style Tools fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px,color:#78350F

**规范门槛：**228/228 测试集，0 次绕过，100% 一致性

CI 蜂群

每次 PR 和每晚都会运行。六个 Agent 按顺序工作，每个 Agent 都会加固前一个 Agent 发现的问题。

Agent	工作内容
Scout	SAST 扫描、依赖项审计、配置审查
Corpus	根据当前策略评估全部 228 个攻击测试样例
Evasion	运行 120+ 项绕过探测，并使用大模型生成新探测
Parity	验证 Node 和 Python 实现是否产生相同决策
Proxy	针对运行中的代理实例进行实时 stdio MCP 会话测试
Report	将完整结果和指标写入 security-swarm/latest.json

运行时蜂群

在生产代理内部运行，处理每次工具调用。

组件	工作内容
BlockGuard	在每次调用时同步执行当前策略。默认拒绝。
InstantLearner	跟踪每条规则的统计数据，并实时提供规则建议
SemanticAuditor	可选的异步大模型审查，用于检查通过模式检查但看起来可疑的调用
PatternSynthesizer	将 InstantLearner 和 SemanticAuditor 的建议汇总为候选规则
Calibrator	为候选规则添加标签、调整阈值，并将获批规则提升回 BlockGuard

反馈循环

循环	信号	效果
A	CI 发现绕过方式	将其加入测试集，CI 此后会持续防范该方式
B	运行时拦截模式	将其综合为新规则，并提升至 BlockGuard
C	Calibrator 标签	用于微调 SemanticAuditor 阈值
D	CI 指标（每周）	更新运行时配置，使 CI 与生产环境保持同步

该代理支持五种传输方式：stdio、HTTP、SSE、streamable HTTP 和 WebSocket。

有关使用 Redis、Postgres 和 Kubernetes 的企业部署，请参阅 docs/ENTERPRISE_DEPLOYMENT.md。

---

威胁实验室

威胁实验室会监控实时流量，并在检测到可疑模式时使用本地大模型提出新的攻击测试用例。不会自动应用任何内容。每条建议都必须先由你在仪表板中审核并批准，才能成为规则。

经批准的发现会反馈至 CI 攻击测试集，用于持续回归测试。

ollama serve
ollama pull qwen3:8b

export OLLAMA_BASE_URL=http://127.0.0.1:11434
export MASTYF_AI_LLM_PROVIDER=ollama
export MASTYF_AI_LLM_MODEL=qwen3:8b

pnpm dashboard:proxy

---

MCP 包信任评分

在从 npm 安装任何 MCP 服务之前，请先在 https://www.mastyf.ai/certified 查看其信任评分。评分涵盖 CVE 暴露风险、拼写仿冒风险、维护者信号和已知攻击模式。免费使用，无需账号。

---

常用命令

命令	工作内容
pnpm dashboard:proxy	规范本地设备 + 网关 BFF（:4000 上的 /api/gateway/*）。请参阅 docs/DASHBOARD_CANONICAL_RUNBOOK.md。
node dist/cli.js start	在端口 4000 上启动代理和仪表板
node dist/cli.js onboard	包装你的 MCP 配置，使流量经由代理路由
node dist/cli.js doctor	检查数据库、策略和环境的运行状况
node dist/cli.js scan --all	扫描 MCP 配置中的 CVE 和注入风险
pnpm test	运行完整测试套件
pnpm security-swarm:fast	快速安全回归测试，耗时 5 至 15 分钟
pnpm security-swarm:analyze	完整对抗性分析

---

故障排查

问题	解决方法
仪表板没有显示数据	代理和仪表板必须共用相同的 MASTYF_AI_DB_PATH。默认值为 ~/.mastyf-ai/history.db
找不到 dist/cli.js	运行 pnpm build
AI 仍在直接调用工具	运行 node dist/cli.js onboard --apply
启动时出现 Ollama 警告	运行 ollama serve，或从环境中移除 MASTYF_AI_LLM_PROVIDER
npm 安装失败	npm 发布尚未开放。请使用 git clone 和 pnpm install

---

了解更多

• 企业部署（Redis、Postgres、Helm）
• MCP 边界产品路线图（可执行）
• 深度防御管线
• Security Swarm 和 CI 红队测试
• 真实场景中的 MCP 集成示例
• 核心检测引擎

---

学术研究论文与引用

如果你在研究或生产系统中使用 Mastyf Guard、其基准测试方法或 Cognitive Harvard Architecture，请引用我们的开放获取出版物：

Das, R. (2026). 面向 AI Agent 边界防御的 Cognitive Harvard 架构：通过基于能力的访问控制解决 Model Context Protocol 中的混淆代理问题。 Zenodo。doi：10.5281/zenodo.22179415。

@article{das2026cognitive,
  title={Cognitive Harvard Architectures for AI Agent Perimeter Defense: Resolving the Confused Deputy Problem in Model Context Protocol via Capability-Based Access Control},
  author={Das, Rudraneel},
  journal={Zenodo},
  year={2026},
  doi={10.5281/zenodo.22179415},
  url={https://doi.org/10.5281/zenodo.22179415}
}