mastyf.ai

<p align="center"> <img src="docs/assets/logo.jpeg" alt="mastyf.ai logo" width="200" /> </p> <h1 align="center">mastyf.ai</h1> <p align="center"><strong>AI 安全防护</strong></p> <p align="center">运行时强制执行、策略控制和每项 AI 操作的完整审计跟踪。</p> <p align="center"> <a href="https://mastyf-ai-cloud-jet.vercel.app/">官方网站</a> · <a href="#快速入门">快速入门</a> · <a href="#策略">策略</a> · <a href="#仪表盘">仪表盘</a> · <a href="https://github.com/mastyf-ai/mastyf.ai">GitHub</a> </p> <p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL3.0-E11D48?style=for-the-badge" alt="许可证"></a> <a href="https://github.com/mastyf-ai/mastyf.ai/actions"><img src="https://img.shields.io/badge/CI-passing-22C55E?style=for-the-badge&logo=githubactions&logoColor=white" alt="持续集成"></a> <img src="https://img.shields.io/badge/版本-4.1.7-2563EB?style=for-the-badge" alt="版本"> <img src="https://img.shields.io/badge/TypeScript-5.x-7C3AED?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript"> <img src="https://img.shields.io/npm/v/@mastyf_ai/server?style=for-the-badge&logo=npm&label=npm&color=CB3837" alt="npm"> </p> --- ## 问题 AI 代理可以读取文件、推送代码、查询数据库、执行 shell 命令和调用外部 API。它们自主地以机器速度执行这些操作。 传统的安全控制措施并不是为此而设计的。 mastyf.ai 作为 AI 的周边安全层。它拦截每个工具调用，使用多智能体群集分析评估调用是否符合您的安全策略，并在执行前阻止恶意或未经授权的操作。 每个决定都被强制执行、记录和可审计。 --- ## 它能阻止什么 | 威胁 | 表现形式 | |--------|--------------------| | 提示注入 | 恶意指令嵌入到工具参数中，以劫持代理行为 | | 路径遍历 | 尝试访问 `/etc/passwd`、`.ssh/id_rsa`、`.aws/credentials` | | 机密泄露 | API 密钥和令牌通过工具参数泄露 | | shell 注入 | 反向 shell、`rm -rf`、编码 PowerShell 命令 | | 数据泄露 | 大规模 SQL 转储、`git push`、`aws s3 cp`、未经授权的文件传输 | | SSRF | 调用元数据端点、localhost 和私有 IP 范围 | | 编码逃避 | 使用 Base64 块和 Unicode 同形字绕过模式检测 | | 成本滥用 | 失控的代理循环消耗令牌预算 | | Rug-pull 攻击 | 工具定义在会话期间静默更改 | --- ## 快速入门 ### 从源代码构建 克隆存储库并运行安装脚本。 **要求：** - Git - Linux（安装脚本会自动安装 Nix，如果需要） ```bash git clone https://github.com/mastyf-ai/mastyf.ai.git cd mastyf.ai chmod +x setup.sh ./setup.sh ``` 安装脚本会自动： - 安装 Nix（如果需要） - 启用 Nix flake - 创建开发环境 - 安装所有项目依赖项 - 重建原生包 - 构建整个项目 - 添加一个方便的 `mastyf` shell 别名 安装完成后，在新终端中启动代理和仪表盘： ```bash node dist/cli.js start ``` 或直接使用别名： ```bash mastyf ``` 仪表盘将可在： - 仪表盘：http://localhost:4000 --- ### 测试安装 如果仪表盘正在运行，请通过以下命令验证 HTTP 网桥： ```bash curl -X POST http://localhost:4000/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}' ``` --- ## 仪表盘 对 AI 采取的每项操作都具有完全的可见性。 <img width="1918" height="912" alt="20260628-1234-42 0110563" src="https://github.com/user-attachments/assets/f820017b-c83d-4a8d-9b29-0593597f6271" /> --- | 部分 | 您看到的内容 | |---------|-------------| | 保护 | 阻止率、触发的顶级规则、实时威胁动态 | | 活动 | 每个工具调用及其完整参数、允许或阻止状态、时间戳 | | 策略 | 实时规则编辑器，从 YAML 热重载 | | 威胁实验室 | AI 建议的攻击测试，在应用前经过审查和批准 | | 成本 | 按工具调用划分的令牌使用和成本估算 | > 在启用仪表盘身份验证之前，请勿公开暴露端口 4000。默认本地开发配置已启用 `DASHBOARD_AUTH_DISABLED=true`。 --- ## 强制执行的工作原理 每个工具调用在到达您的基础设施之前都会经过三个层。 **第 1 层 - 模式检测** 基于正则表达式的扫描，用于检测注入、危险路径、泄露的机密、shell 命令和编码技巧。在微秒内运行，无需外部依赖。 **第 2 层 - 模式验证** 在策略评估之前，拒绝格式错误的负载、超大参数和 JSON-RPC 违规。 **第 3 层 - 语义审查** 可选的本地 LLM（Ollama）或云模型评估通过模式检查的边缘调用。如果未配置模型，则回落到启发式。 任何失败的调用都会被阻止。工具永远不会运行。所有内容都已记录。 <img width="1917" height="912" alt="image" src="https://github.com/user-attachments/assets/cc8976c5-1195-4025-adf7-116b4054482a" /> --- ## 策略 您的规则位于 `default-policy.yaml`。您拥有它们。mastyf.ai 强制执行它们。 ```yaml 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/`](policy-templates/) 中提供了 HIPAA、PCI-DSS、GxP 和数据驻留的预建模板。 <img width="1917" height="912" alt="image" src="https://github.com/user-attachments/assets/40c0ad98-9d3f-4606-a832-5ff034349cfd" /> --- ## 架构 mastyf.ai 运行两个协调的群集。CI 群集在代码交付前攻击您的策略。运行时群集在生产中强制执行并从每个实时工具调用中学习。四个反馈环连接它们，因此系统随着时间的推移变得更难绕过。 ```mermaid flowchart TB AI["🤖 AI 客户端\nCursor · Claude Desktop · Cline"] subgraph CI["🔵 CI 群集（PR + 每夜）"] direction LR Scout["🔍 侦察代理\nSAST、依赖项、配置扫描"] Corpus["📋 语料库代理\n228 个固定评估"] Evasion["⚡ 逃避代理\n120+ 探针 + 生成新的"] Parity["🔄 奇偶校验代理\nNode 与 Python"] ProxyA["🖥️ 代理代理\n实时 stdio MCP 测试"] Report["📊 报告代理\nsecurity-swarm/latest.json"] Scout --> Corpus --> Evasion --> Parity --> ProxyA --> Report end subgraph Runtime["🟢 运行时群集（生产代理）"] direction LR BG["🛡️ 阻止卫士\n同步策略"] IL["📈 即时学习器\n每个阻止的统计数据 + 建议"] SA["🧠 语义审计器\n异步 LLM，可选"] PS["🔗 模式合成器\n批量建议"] Cal["⚙️ 校准器\n标签 + 阈值"] BG --> IL --> PS --> Cal BG --> SA --> PS end Tools["🗄️ MCP 工具\n文件系统 · GitHub · 数据库 · API"] AI -->|"每个工具调用"| BG BG -->|"✅ 允许"| Tools Report -->|"🔁 环 A：绕过到语料库"| Corpus Cal -->|"🔁 环 B：阻止规则"| BG Cal -->|"🔁 环 C：标签到 LLM"| SA Report -->|"🔁 环 D：CI 指标每周"| 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 和夜间运行。六个代理按顺序工作，每个代理都强化了前一个代理发现的内容。 | 代理 | 它做什么 | |-------|-------------| | 侦察 | SAST 扫描、依赖项审计、配置审查 | | 语料库 | 评估当前策略的所有 228 个攻击固定装置 | | 逃避 | 运行 120+ 绕过探针并使用 LLM 生成新的探针 | | 奇偶校验 | 验证 Node 和 Python 实现产生相同的决策 | | 代理 | 实时 stdio MCP 会话测试，针对正在运行的代理实例 | | 报告 | 编写 `security-swarm/latest.json`，包含完整的结果和指标 | ### 运行时群集 在生产代理上运行每个工具调用。 | 组件 | 它做什么 | |-----------|-------------| | 阻止卫士 | 同步强制执行活动策略。关闭失败。 | | 即时学习器 | 跟踪每个阻止的统计数据，并实时提供规则建议 | | 语义审计器 | 对通过模式检查但看起来可疑的调用进行可选的异步 LLM 审查 | | 模式合成器 | 将即时学习器和语义审计器的建议批处理成候选规则 | | 校准器 | 标记候选者，调整阈值，并将批准的规则推广到阻止卫士 | ### 反馈环 | 环 | 信号 | 效果 | |------|--------|--------| | A | 发现 CI 绕过 | 添加到语料库，CI 现永久防范 | | B | 运行时阻止模式 | 合成新规则，推广到阻止卫士 | | C | 校准器标签 | 用于微调语义审计器阈值 | | D | CI 指标（每周） | 更新运行时配置 — 保持 CI 和生产同步 | 代理支持五种传输：stdio、HTTP、SSE、流式 HTTP 和 WebSocket。 有关使用 Redis、Postgres 和 Kubernetes 的企业部署，请参见 [`docs/ENTERPRISE_DEPLOYMENT.md`](docs/ENTERPRISE_DEPLOYMENT.md)。 --- ## 威胁实验室 威胁实验室监视实时流量，并使用本地 LLM 提出新的攻击测试用例，当它检测到可疑模式时。没有任何内容会自动应用。您在仪表板中审查和批准每个建议，然后它成为一条规则。 批准的发现会反馈到 CI 攻击语料库中，以进行持续的回归测试。 ```bash 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 ``` <img width="1917" height="912" alt="image" src="https://github.com/user-attachments/assets/a525e744-badf-48e2-98b0-c45c5a797f7d" /> --- ## MCP 包信任分数 在从 npm 安装任何 MCP 服务器之前，请在 [https://www.mastyf.ai/certified](https://www.mastyf.ai/certified) 上检查其信任分数。分数涵盖 CVE 暴露、类型混淆风险、维护者信号和已知攻击模式。免费，无需帐户。 --- ## 常用命令 | 命令 | 它做什么 | |---------|-------------| | `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）](docs/ENTERPRISE_DEPLOYMENT.md) - [深入防御管道](docs/DEFENSE_FABRIC.md) - [安全群集和 CI 红队](security-swarm/README.md) - [现实世界中的 MCP 集成示例](docs/REAL_WORLD_INTEGRATION.md) - [核心检测引擎](packages/core/README.md)