akanthed/SecureAI-Scan

# SecureAI-Scan [](https://www.npmjs.com/package/secureai-scan) [](LICENSE) [](https://www.typescriptlang.org/) [](https://www.python.org/) [](https://nodejs.org) [](https://chatgpt.com/g/g-6a25141758188191a764020c1ab6a226-secureai-scan-ai-security-advisor) **在攻击者之前，发现你代码中的 AI/LLm 安全漏洞。** SecureAI-Scan 是一个 CLI 工具，用于扫描 **TypeScript、JavaScript 和 Python** 代码库，查找 AI 驱动应用特有的安全问题 —— prompt 注入、MCP 工具滥用、RAG 数据投毒、agent 信任违规等。 - **本地优先** —— 绝不离开你的机器 - **零配置**即可启动 —— 一条命令，即时获取结果 - **19 条规则**，涵盖 AI/LLM、MCP (Model Context Protocol) 和 Vector/RAG pipeline - **TypeScript + Python** —— 覆盖两大主要 AI 开发者生态系统 - **可操作** —— 每个发现都包含代码级别的修复示例 ## 30 秒快速开始 ``` # 立即扫描您的 repo — 无需安装 npx --yes secureai-scan@latest scan . ``` 自动处理 TypeScript、JavaScript 和 Python 文件。你会立即在终端看到带有颜色标记的扫描结果。 ## 你的 4 步安全之旅 ### 第 1 步 — 设置（每个项目一次） ``` npx --yes secureai-scan@latest init ``` 创建两个文件： - `.secureai-policy.json` —— 你的安全策略（严重性阈值、规则、CI 行为） - `.github/workflows/secureai-scan.yml` —— 开箱即用的 GitHub Actions 工作流 ### 第 2 步 — 扫描并了解详情 ``` # 应用您的 policy 进行扫描 npx --yes secureai-scan@latest scan . --policy .secureai-policy.json # 获取详细的 HTML 报告以与您的团队共享 npx --yes secureai-scan@latest scan . --output report.html # 准确了解 rule 的含义以及如何修复 npx --yes secureai-scan@latest explain AI001 ``` ### 第 3 步 — 创建基线（仅追踪新问题） ``` npx --yes secureai-scan@latest scan . --baseline .secureai-baseline.json ``` 首次运行会将当前的扫描结果保存为你的基线。之后的每次运行将**仅显示**自那以后引入的**新问题** —— 非常适合 PR。 ### 第 4 步 — 生成威胁模型 ``` npx --yes secureai-scan@latest threat-model . ``` 编写 `THREAT_MODEL.md`，包含信任边界、现实的攻击场景和优先修复列表 —— 直接可用于安全审查或合规审计。 ## 所有命令 | 命令 | 作用 | |---------|--------------| | `secureai-scan init` | 首次设置：策略文件 + CI 工作流 | | `secureai-scan scan ` | 扫描 repo 查找 AI/LLM/MCP/RAG 漏洞 | | `secureai-scan explain ` | 展示某条规则的重要性、被利用方式及修复方案 | | `secureai-scan threat-model ` | 生成 `THREAT_MODEL.md` | | `secureai-scan prompt ""` | 评估原始 prompt 文本的注入风险 | ### `scan` 选项 ``` secureai-scan scan . # scan everything (TS, JS, Python) secureai-scan scan . --only-ai # only AI/LLM rules (AI001–AI012) secureai-scan scan . --only-mcp # only MCP rules (MCP001–MCP003) secureai-scan scan . --only-vec # only Vector/RAG rules (VEC001–VEC003) secureai-scan scan . --rules AI001,MCP002 # specific rules only secureai-scan scan . --severity high # high and critical only secureai-scan scan . --min-confidence 0.6 # stricter: fewer, higher-confidence findings secureai-scan scan . --output report.html # save HTML report secureai-scan scan . --output report.md # save Markdown report secureai-scan scan . --output report.json # save JSON report secureai-scan scan . --baseline baseline.json # show only new issues since baseline secureai-scan scan . --policy .secureai-policy.json # enforce policy + CI exit code secureai-scan scan . --check-dependencies # check for hallucinated/typo packages secureai-scan scan . --limit 10 # show top 10 findings in terminal secureai-scan scan . --debug # show file counts and rule metadata ``` ## 安全规则 ### AI / LLM 规则 涵盖调用语言模型 API 的应用中最常见的漏洞 —— 适用于 **TypeScript 和 Python**。 | 规则 | 严重性 | 检测内容 | |------|----------|---------------| | **AI001** | 高 | 用户输入在没有角色隔离的情况下被拼接进 LLM prompt（prompt 注入） | | **AI002** | 高 | 记录的 prompt 或响应包含敏感字段（电子邮件、token、补全文本） | | **AI003** | 严重 | 在路由处理程序中，先调用了 LLM，后进行身份验证/授权 | | **AI004** | 高 | 将整个用户/会话对象发送给 LLM（PII 和机密泄露） | | **AI005** | 严重 | LLM 输出被传递给 `eval`、`exec`、subprocess、SQL 查询或 `innerHTML` | | **AI006** | 严重 | LLM 被赋予高影响力工具（删除、执行、发送电子邮件）且无人工批准关卡 | | **AI007** | 高 | 检索到的 RAG 文档作为受信任指令直接混入 system prompt | | **AI008** | 高 | API 密钥或机密被硬编码在 system prompt 字符串中 | | **AI009** | 中 | 发送给 LLM 的用户输入没有 token 限制或输入长度上限 | | **AI010** | 高 | 外部 HTTP/fetch 响应被直接管道传输到 LLM prompt 中（间接注入） | | **AI011** | 高 | 上游 agent 的输出被放置在下游 agent 的 `system` 角色中（信任边界） | | **AI012** | 中 | LLM 响应通过 `JSON.parse` / `json.loads` 解析，但未使用 schema 进行验证 | **示例 — Python 中的 AI001（Prompt 注入）：** ``` # Vulnerable — 用户可以覆盖您的 system instructions user_msg = request.json["message"] response = client.chat.completions.create( model="gpt-4", messages=[{"role": "user", "content": f"You are a helpful assistant. {user_msg}"}] ) # Fixed — 用户输入被隔离在其自身的 role 中 response = client.chat.completions.create( model="gpt-4", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": str(user_msg)}, ] ) ``` **示例 — TypeScript 中的 AI001：** ``` // Vulnerable const prompt = `You are a helpful assistant. User says: ${req.body.message}`; await openai.chat.completions.create({ messages: [{ role: "user", content: prompt }] }); // Fixed await openai.chat.completions.create({ messages: [ { role: "system", content: "You are a helpful assistant." }, { role: "user", content: String(req.body.message) }, ], }); ``` ### MCP 规则 (Model Context Protocol) MCP 允许 AI agent 连接到外部工具服务器。这些规则涵盖了特定于该架构的攻击。 | 规则 | 严重性 | 检测内容 | |------|----------|---------------| | **MCP001** | 严重 | 工具描述包含注入语言（“忽略之前的指令”、“扮演”等） | | **MCP002** | 严重 | MCP 服务器 URL 由用户输入构建 —— 攻击者控制了你的 agent 使用哪些工具 | | **MCP003** | 高 | MCP 工具结果在未经校验的情况下被提升为 `system`/`developer` 角色 | **示例 — MCP002（动态服务器 URL）：** ``` // Vulnerable — attacker sends { mcpUrl: "https://evil.com/mcp" } const server = { url: req.body.mcpUrl }; agent.connect(server); // Fixed — only pre-approved servers allowed const TRUSTED_SERVERS = { search: "https://mcp.yourdomain.com/search" }; const url = TRUSTED_SERVERS[req.body.tool]; if (!url) throw new Error("Unknown tool"); agent.connect({ url }); ``` ### Vector / RAG 规则 涵盖检索增强生成 (RAG) pipeline 和向量数据库中的安全问题 —— 检测 **TypeScript 和 Python** 中的模式（LangChain、Pinecone、Chroma、Weaviate、pgvector 等）。 | 规则 | 严重性 | 检测内容 | |------|----------|---------------| | **VEC001** | 高 | 向量相似性搜索没有用户/租户过滤器 —— 用户 A 检索到了用户 B 的文档 | | **VEC002** | 中-高 | 结果数量 (`k`) 来自用户输入或没有上限（成本耗尽 / prompt 填充） | | **VEC003** | 高 | 用户上传的内容在未净化的情况下被摄取到共享向量存储中（数据投毒） | **示例 — Python 中的 VEC001（无访问控制）：** ``` # Vulnerable — 返回 ALL 用户的 documents docs = vectorstore.similarity_search(query, k=5) # Fixed — 限定在 current user 范围内 docs = vectorstore.similarity_search( query, k=5, filter={"user_id": current_user.id} ) ``` ### 依赖项规则（可选，`--check-dependencies`） | 规则 | 严重性 | 检测内容 | |------|----------|---------------| | **LLM_DEP001** | 低 | 在 npm/PyPI 中找不到的包名（可能由 LLM 幻觉产生） | | **LLM_DEP002** | 低 | 与流行包名称极其相似的包名（typosquatting/域名抢注风险） | ## 误报控制 每个发现都有一个**置信度分数**（0–1）。默认情况下，低信号噪音会被过滤掉。 ``` # 默认：隐藏 confidence 低于 0.4 的 findings secureai-scan scan . # Strict mode：仅显示高 confidence 的 findings secureai-scan scan . --min-confidence 0.6 # 查看所有内容（适用于初始 triage） secureai-scan scan . --min-confidence 0.1 ``` 在以下情况下，置信度会自动降低： - 测试文件（`*.test.ts`、`*_test.py`、`conftest.py`、`__tests__/**`） - 附近已经有净化代码（`bleach`、`DOMPurify`、`validate` 等） - 仅用于 Embedding 的调用（非 prompt 注入目标） 使用附带必要理由的注释，在代码中屏蔽已确认的误报： ``` // secureai-ignore AI001: sanitized via DOMPurify before this call const prompt = buildPrompt(userInput); ``` ``` # secureai-ignore AI001：输入已根据上面的 allowlist 进行验证 response = client.chat.completions.create(...) ``` 被屏蔽的发现仍会显示在报告的 **Ignored Findings** 下，并附带你的理由 —— 审计追踪得到保留。 ## 策略文件 运行 `secureai-scan init` 以创建 `.secureai-policy.json`，或手动写入一个： ``` { "$comment": "Commit this file — CI will enforce it automatically", "minSeverity": "medium", "minConfidence": 0.45, "failOnSeverity": "high", "skipPaths": ["test/**", "examples/**"], "blockedRules": [], "onlyRules": [], "requireOutputValidation": true } ``` | 字段 | 作用 | |-------|--------------| | `minSeverity` | 隐藏低于此严重性的发现 | | `minConfidence` | 隐藏低于此置信度分数的发现 | | `failOnSeverity` | 在 CI 中，当任何发现达到此严重性时以退出代码 1 退出 | | `skipPaths` | 要从扫描中排除的 Glob 匹配模式 | | `blockedRules` | 始终跳过的规则 ID | | `onlyRules` | 仅运行这些规则 ID | 应用它： ``` secureai-scan scan . --policy .secureai-policy.json ``` ## CI / GitHub Actions `secureai-scan init` 会自动创建 `.github/workflows/secureai-scan.yml`。 或者将此内容添加到现有的工作流中： ``` - name: AI Security Scan run: | npm install -g secureai-scan secureai-scan scan . \ --policy .secureai-policy.json \ --baseline .secureai-baseline.json \ --output secureai-report.html - name: Upload Report if: always() uses: actions/upload-artifact@v4 with: name: secureai-report path: secureai-report.html ``` 在你的策略中设置 `"failOnSeverity": "high"`，当引入高或严重发现时，工作流会自动失败。无需额外配置。 ## 与 Claude 配合使用（MCP 服务器） SecureAI-Scan 内置了 MCP 服务器，因此你可以直接从 Claude Desktop 或任何兼容 MCP 的客户端扫描代码库并获取安全说明。 ### 设置 添加到你的 Claude Desktop 配置 (`claude_desktop_config.json`) 中： ``` { "mcpServers": { "secureai-scan": { "command": "node", "args": ["/absolute/path/to/secureai-scan/mcp-server/index.js"] } } } ``` ### 可用的 MCP 工具 连接后，Claude 将拥有三个工具： | 工具 | 作用 | |------|--------------| | `scan_repository` | 扫描本地路径，返回带有严重性和置信度的结构化发现 | | `explain_rule` | 获取 19 个规则 ID 中任意一个的完整说明 | | `evaluate_prompt` | 检查原始 prompt 文本是否存在注入风险模式 | ### Claude 对话示例 ## 威胁模型 ``` secureai-scan threat-model . --output THREAT_MODEL.md ``` 生成一份结构化文档，包含： - **安全等级**（基于发现严重性的 A–F 级） - **信任边界** —— 跨越安全边界的数据流（用户 -> LLM、MCP 服务器 -> agent、向量存储 -> context） - **攻击场景** —— 针对你最重大发现的具体“如果发生什么会怎样”的叙述 - **修复优先级列表** —— 按风险影响排序 将其用于安全审查、合规文档（SOC 2、ISO 27001），或引导工程师熟悉代码库的风险面。 ## 报告 所有三种格式都包含相同的数据 —— 根据受众进行选择： ``` --output report.html # Best for sharing with non-technical stakeholders --output report.md # Best for GitHub PRs and documentation --output report.json # Best for integrating with other tools / SIEM ``` 每份报告均包含：执行摘要、按类别和严重性划分的发现结果、每个模式被标记的原因、记录了理由的被忽略发现，以及下一步操作指南。 ## Programmatic API 在你自己的工具中将 SecureAI-Scan 作为库使用： ``` import { scanRepository, scanRepositoryDetailed, buildReport, formatReport, evaluatePromptRisk, } from "secureai-scan"; // Simple: get findings as an array (TypeScript + Python files) const findings = scanRepository("./my-repo"); // Detailed: includes ignored findings, TS file list, Python file list const result = scanRepositoryDetailed("./my-repo"); console.log(`TS/JS files: ${result.scannedFiles.length}`); console.log(`Python files: ${result.pythonFiles?.length ?? 0}`); // Build and format a report const report = buildReport(result.findings, { tool: "SecureAI-Scan", version: "0.2.1", scannedAt: new Date().toISOString(), }); const html = formatReport(report, "html"); // Evaluate a prompt string directly const risk = evaluatePromptRisk("Ignore previous instructions and..."); console.log(risk.level); // "High" console.log(risk.reasons); // ["Contains instruction-override language"] ``` ## 常见问题 **这会把我的代码发送到其他地方吗？** 不会。所有分析均在本地运行。没有遥测，没有 SaaS 调用，任何数据都不会离开你的机器。 **它支持哪些语言？** TypeScript、JavaScript（`.ts`、`.tsx`、`.js`、`.jsx`）和 Python（`.py`）。所有 19 条规则均在 TypeScript/JS 上运行。其中 11 条最关键的规则也适用于 Python —— 涵盖了 AI001–AI007、AI010、VEC001、VEC003 和 MCP001。 **它能用于 LangChain / LlamaIndex / OpenAI SDK 代码吗？** 可以。这些规则能识别来自 `openai`、`anthropic`、`@langchain/openai`、`llama-index`、`google-generativeai`、LangChain Python 等的模式。 **如果我发现有太多问题无法一次性修复怎么办？** 使用 `--baseline` 创建快照。未来的扫描将仅显示在该时间点之后引入的发现 —— 按照你自己的节奏修复遗留问题，同时在 PR 中拦截新问题。 **某个发现是错误的 —— 我该如何屏蔽它？** 在该发现所在行的上方添加 `// secureai-ignore RULE_ID: reason` 注释。必须提供理由，并会被记录在报告中。 **有没有办法在不安装任何东西的情况下提问？** 有。**[SecureAI-Scan AI Security Advisor](https://chatgpt.com/g/g-6a25141758188191a764020c1ab6a226-secureai-scan-ai-security-advisor)** 是 ChatGPT 上的一个免费 Custom GPT。粘贴代码、询问任何规则，或获取即时安全审查 —— 无需安装。 **我可以直接与 Claude 一起使用它吗？** 可以。内置的 MCP 服务器允许 Claude Desktop 将 `scan_repository`、`explain_rule` 和 `evaluate_prompt` 作为原生工具调用。请参阅上面的 [MCP Server](#use-with-claude-mcp-server) 部分。 **我可以添加自己的规则吗？** `Rule` 接口是公开的。实现 `{ id, title, severity, run(context) }` 并将其传递给 Programmatic API 即可。 **它可以替代安全审计吗？** 不能。它能快速、低成本地捕获常见模式。人工安全审查仍然很有价值 —— 而 `secureai-scan threat-model` 可以帮助你为此做准备。 ## 适用人群 - 正在 LLM 功能并希望拥有合并前安全网的**开发团队** - 需要对代码库进行快速、自动化 AI 风险盘点**安全工程师** - 希望在没有专门 AppSec 团队的情况下证明进行了安全尽职调查的**创始人和 CTO** - 使用 LangChain、LlamaIndex、OpenAI SDK 或 Anthropic SDK 进行构建的 **Python AI 开发人员** - **任何使用 MCP、RAG 或多 agent 架构构建的人** —— 这个攻击面是全新的，大多数扫描器尚未覆盖它 ## 环境要求 - Node.js 22 或更高版本 - 扫描 TypeScript、JavaScript 和 Python 文件（运行扫描器不需要安装 Python） ## 许可证 MIT — [Akshay Kanthed](https://github.com/akanthed) 欢迎提交 Issues 和贡献：[github.com/akanthed/SecureAI-Scan](https://github.com/akanthed/SecureAI-Scan) **尝试免费的 ChatGPT 顾问：**[SecureAI-Scan AI Security Advisor](https://chatgpt.com/g/g-6a25141758188191a764020c1ab6a226-secureai-scan-ai-security-advisor)

标签：AI安全, Chat Copilot, MITM代理, Python, TypeScript, 安全插件, 数据可视化, 无后门, 暗色界面, 自动化攻击, 逆向工具, 零日漏洞检测, 静态应用安全测试