尧图网站建设 
应用安全漏洞扫描人工智能AI Agent【免费下载链接】deepsecDeepsec is a security harness for finding vulnerabilities in your codebase powered by coding agents项目地址https://gitcode.com/gh_mirrors/deeps/deepsec点击查看免费下载deepsec 是一个由编码智能体驱动、扫描代码库漏洞的安全工具其可扩展性完全建立在新的 matcher和新的插件这两个扩展点上。本文以仓库根目录的 CONTRIBUTING.md 为主线完整梳理它的仓库布局、开发工作流、bundle 分发、live-sandbox 端到端测试以及新增 matcher 与插件的标准路径并配合 packages/core/src/plugin.ts、packages/scanner/src/matchers/index.ts、e2e/bundle.test.ts 等源码佐证每个环节的真实实现。读完你既能上手提交第一个 matcher也能理解从源码到发布包的完整验证链路。仓库布局五个包与三类支撑目录deepsec 是一个 pnpm workspace 单仓库根目录 package.json 声明了node 22、pnpm8.15.9。核心代码集中在packages/下的五个工作区职责边界非常清晰packages/ core/ Types、schemas、插件契约、配置加载器 scanner/ Regex matchers 扫描引擎 processor/ AI 智能体集成Claude SDK、Codex SDK、enrich、triage、revalidate deepsec/ 可发布包打包后的 CLI deepsec/config 子导出 vercel/sandbox 执行器 e2e/ 针对 fixture 项目的端到端测试 fixtures/ vulnerable-app/ 故意植入漏洞的测试数据从 lint/knip 中排除 docs/ 面向用户的文档 samples/ 新用户可直接复制的起步示例需要特别注意的是fixtures/vulnerable-app它包含src/api/admin.ts、src/api/users.ts、src/components/comment.tsx、src/lib/crypto.ts等故意存在漏洞的源码是 matcher 单元测试packages/scanner/src/tests/matchers.test.ts和 bundle e2ee2e/bundle.test.ts共用的标准靶场因此被排除在 lint 与 knip 之外。开发工作流一套必须全部通过的验证命令从源码开始贡献标准流程是pnpm install pnpm test # 所有包包括 e2e pnpm test:unit # 排除 e2e pnpm -r build # 所有 workspace 的 tsc 类型检查 pnpm lint # biome check pnpm lint:fix # biome check --write pnpm knip # 未使用代码/依赖检测 pnpm deepsec --help # 通过 tsx 运行 CLI其中pnpm deepsec实际执行的是tsx packages/deepsec/src/cli.ts见根 package.json 的 scripts也就是说在源码环境下你跑的是 TypeScript 源码而非打包产物非常适合调试 matcher 逻辑。打包分发bundle 与 bundle 测试开发期验证通过后还要验证真正分发出去的产物pnpm bundle # esbuild → packages/deepsec/dist/{cli,config}.mjs pnpm test:bundle # bundle e2e把产物作为子进程运行e2e/bundle.test.ts 是这套流程的核心证据它用spawnSync(node, [BUNDLE, ...args])直接执行packages/deepsec/dist/cli.mjs覆盖了--help、--version、对 fixture 执行scan、从 cwd 加载deepsec.config.ts、激活配置中的内联插件、验证dist/config.d.ts不自引用 workspace 内部的deepsec/*包等场景。其中config.d.ts 自包含检查e2e/bundle.test.ts保证了消费方只安装deepsec一个 npm 包就能获得完整的类型。手动演练未发布的 onboarding想在不发布的情况下完整演练新用户的初始化流程先构建一次 bundle再把它跑在一个一次性目标仓库上pnpm bundle cd /path/to/disposable-project node /path/to/deepsec/packages/deepsec/dist/cli.mjs init这里有一个对贡献者非常重要的机制当 bundle 检测到自己运行在源码检出目录时生成的.deepsec/package.json会自动把deepsec依赖指向当前源码检出不需要 pack、link、scaffold-only 或手工改 manifest。重复运行同一个命令还能修复由旧本地 bundle 生成、错误指向 npm registry 的 workspace——e2e/bundle.test.ts 专门断言了这条修复路径把依赖临时改成^2.2.9再重跑init --scaffold-only依赖会被修正回本地源码的file:URL。合并 PR 的硬性门槛是build、test、lint、knip 全部通过任何触碰发布面即一切经由deepsec/config导入的内容的 PR 还必须通过pnpm test:bundle。CI 侧由 .github/workflows/ci.yml 在 Node 22 与 24 双版本矩阵上执行pnpm -r build、pnpm lint、pnpm knip、pnpm test:unit、pnpm test:bundle、pnpm typecheck:deepsec其中 typecheck 用刚打出的dist/config.d.ts类型检查.deepsec/deepsec.config.ts专门拦截发布类型泄漏 workspace 内部包的回归。Live-sandbox e2e手动不花 token 的真实沙箱链路常规pnpm test会跳过一项关键测试e2e/pipeline-sandbox.test.ts 用真实的 Vercel Sandbox 跑完整 pipeline但沙箱内是stub agent——它验证 bootstrap 快照、worker 拉起、文件上传/下载、结果合并这条基础设施链路不消耗模型 token。它由DEEPSEC_E2E_LIVE_SANDBOX1环境变量加 Vercel Sandbox 凭证门控describe.skipIf默认不进入测试套件。两种运行方式CI手动在 GitHub Actions 触发 E2E live sandbox 工作流需要三个仓库 secretVERCEL_TOKEN、VERCEL_TEAM_ID、VERCEL_PROJECT_ID不需要 AI key。本地在改沙箱代码时VERCEL_OIDC_TOKEN$(grep ^VERCEL_OIDC .deepsec/.env.local | cut -d -f2) \ DEEPSEC_E2E_LIVE_SANDBOX1 \ pnpm exec vitest run --project e2e e2e/pipeline-sandbox.test.ts从测试源码可以看到该测试以 stub agent 依次执行init → scan → sandbox process → sandbox revalidate并在每个沙箱阶段前后对比os.tmpdir()中的deepsec-tar-*临时 tarball 数量防止 orchestrator 长期运行把/tmp塞满e2e/pipeline-sandbox.test.ts。触及packages/deepsec/src/sandbox/的 PR 应该在合并前跑它。注意stub-agent 流程没有 AI 流量因此不会覆盖防火墙的 credential-brokering 变换专门改动那条路径的 PR 仍值得用--agent claude-agent-sdk加 AI key 做一次性验证。添加一个 matcher从 4 步快速路径到完整契约CONTRIBUTING 给出的是短版本完整版在 docs/writing-matchers.md在packages/scanner/src/matchers/slug.ts创建带MatcherPlugin导出的文件。在packages/scanner/src/matchers/index.ts注册import registry.register(...)。运行pnpm deepsec scan --project-id id --root path --matchers slug检查候选数量是否合理。pnpm test和pnpm lint。MatcherPlugin 的真实契约packages/core/src/plugin.ts 定义了 matcher 的最小结构export interface MatcherPlugin { slug: string; description: string; noiseTier: NoiseTier; // precise | normal | noisy filePatterns: string[]; requires?: MatcherGate; // tech 标签 / sentinel 文件门控 examples?: string[]; // 开发期契约每个示例必须命中 match(content: string, filePath: string): CandidateMatch[]; }几个从源码可以确认的要点门控gaterequires可指定tech标签如laravel、nextjs或sentinelFilessentinelContains谓词按扫描而非按文件解析一次。这正是 packages/scanner/src/matchers/index.ts 注释所写的框架入口 matcher 靠detectTech标签保持休眠的实现基础——仓库里大量框架 matcherExpress、Fastify、Laravel、Django、Gin、Axum……都是靠这一机制避免在不相关的仓库上误报。match返回CandidateMatch[]字段定义在 packages/core/src/types.tsvulnSlug、lineNumbers、snippet、matchedPattern。regexMatcher辅助函数packages/scanner/src/matchers/utils.ts逐行扫描每个 pattern收集 1-based 行号并截取前后各 2-3 行作为上下文一个 pattern 命中即产出一个 candidate。examples 是可执行文档examples数组是开发期契约而非运行时数据。自动发现的测试 packages/scanner/src/tests/matcher-examples.test.ts 遍历注册表里所有带 examples 的 matcher断言每个示例字符串至少产出一个 candidate——任何一个子 pattern 的 typo只要被至少一个示例覆盖就会让 CI 失败。它的注释明确建议为 matcher 的每个子 pattern 以及真实语法变体不同动词、大小写、标识符、空白都补一个示例一行一个无需额外测试接线。这也是为什么新 matcher 的 review 重点之一是 examples 是否真实反映仓库语法。标准测试模式packages/scanner/src/tests/matchers.test.ts 展示了统一的 matcher 测试范式对fixtures/vulnerable-app中已知有漏洞的输入断言必须命中对已知安全的输入断言必须不命中。例如xssmatcher 断言components/comment.tsx里dangerouslySetInnerHTML被命中missing-authmatcher 同时断言users.ts/admin.ts命中而lib/db.ts不命中。哪些 matcher 应该放进插件而非内置集只有对单一组织有意义的 matcher特定 helper 命名、内部包 import应该走插件路线见 docs/plugins.md。而如果规则形状属于公共框架或广泛适用的弱点应贡献进 deepsec 内置注册表而不是保留组织私有副本。编写插件五个槽位与最小形态插件可填充五个槽位中的任意子集槽位用途matchers额外 regex matcher与内置 matcher 并列注册notifiers发现结果上报到哪里Slack、GitHub Issues、webhook……ownership把文件映射到所属团队/人如内部目录people按 email/名字查人经理、on-call、联系方式executor在远程基础设施上运行 deepsec 命令完整契约在 packages/core/src/plugin.tsexport interface DeepsecPlugin { name: string; matchers?: MatcherPlugin[]; agents?: AgentPluginRef[]; notifiers?: NotifierPlugin[]; /** Last plugin to declare this wins. */ ownership?: OwnershipProvider; /** Last plugin to declare this wins. */ people?: PeopleProvider; /** Last plugin to declare this wins. */ executor?: ExecutorProvider; commands?: (program: unknown) void; // commander program }最小形态也是 CONTRIBUTING 给出的骨架import type { DeepsecPlugin } from deepsec/config; import { myMatcher } from ./matchers/my-matcher.js; export default function myPlugin(): DeepsecPlugin { return { name: my-org/plugin-internal-services, matchers: [myMatcher], }; }插件从deepsec.config.ts加载CLI 通过 packages/deepsec/src/load-config.tsjiti从 cwd 向上自动加载deepsec.config.{ts,mjs,js,cjs}。命名约定是 Vite 风格scope/plugin-thing。五个槽位的源码细节matchers最常见。slug全局唯一若与内置 slug 冲突插件胜出后注册覆盖这被设计成用更严格的 org 版本替换内置 matcher 的合法手段。MatcherRegistry在 packages/scanner/src/matcher-registry.ts 中用Mapstring, MatcherPlugin实现register就是set天然是最后写入者胜。ownershipfetchOwnership({ filePath, repo })返回OwnershipData | null返回null表示未配置/不可用调用方按软失败处理。deepsec enrich会把该数据附加到发现结果上用于通知路由与评审优先级。peoplelookup(query)与可选的lookupManager(person)。Person有通用核心字段name、email、title、managerKey加extra映射如slackId、slackHandle。notifiersnotify(params)返回携带externalId/externalUrl的FindingNotification用于回链到来源。注意core 不内置任何 notifier——开源的 Slack notifier 已被移除Slack 属于插件职责CONTRIBUTING 与 docs/plugins.md 都指出GitHub Issues notifier 是写第一个插件的好选题。executorlaunch返回 runIdcollect拉回结果可选status。仓库内vercel/sandbox执行器是权威示例代码在packages/deepsec/src/sandbox/但它尚未走ExecutorProvider接口那个重构在路线图上——这是五个槽位中最实验性的一个。完整可运行的内联插件示例仓库的 samples/webapp/deepsec.config.ts 是一个完整的内联插件示例与发布版插件同形只是定义在用户配置文件里const webappPlugin: DeepsecPlugin { name: webapp-internal, matchers: [webappDebugFlag, webappRouteNoRateLimit], }; export default defineConfig({ ai: { mode: gateway, provider: vercel }, projects: [ { id: webapp, root: ./your-app, githubUrl: https://github.com/acme/webapp/blob/main, infoMarkdown: fs.readFileSync(path.join(here, INFO.md), utf-8), promptAppend: Pay extra attention to /api/admin/* and /api/billing/* surfaces., priorityPaths: [src/api/admin/, src/api/billing/, src/lib/auth/], }, ], plugins: [webappPlugin], });两个真实 matcher 值得细读webapp-debug-flagsamples/webapp/matchers/webapp-debug-flag.ts用regexMatcher匹配NODE_ENV ! production与DEBUG_API等仅靠环境变量门控的调试面webapp-route-no-rate-limitsamples/webapp/matchers/webapp-route-no-rate-limit.ts则展示了手写 matcher 的优势——它先排除测试文件、_internal/、webhook 目录再判断文件是否含withRateLimit/rateLimiter.check最后逐行找导出的 handler 并带上 6 行上下文。这正是 docs/writing-matchers.md 所说需要负条件如没有认证助手的路由声明或同文件多组相关搜索时应写 TypeScript matcher 而非声明式 matcher 的场景。e2e/bundle.test.ts 甚至专门验证了这个 sample在samples/webapp目录下用--matchers webapp-debug-flag,webapp-route-no-rate-limit跑 scan断言两个自定义 matcher 都出现在运行日志中——这是配置加载 → 插件激活 → 扫描调用全链路的最小闭环证明。分辨率顺序ownership、people、executor是单槽位最后一个声明者胜通用codeowners插件可先加载组织专属 oracle 排在plugins: [...]数组后面即可覆盖。matchers、notifiers、agents是可叠加的所有插件的贡献全部堆叠。代码风格与评审原则匹配既有代码风格lint 用 Biomepnpm lint:fix自动格式化。默认不写注释只有当为什么不明显时才加隐藏约束、微妙不变量、workaround。禁止写复述代码的注释。保持 PR 小而单一如果加 matcher 需要重构测试 fixture拆成独立 PR。测试体系vitest 与 workspace 粘合测试用 vitest由pnpm test驱动。每个包有自己的vitest.config.tsvitest.workspace.ts 把它们粘合为 workspace 级配置。matcher 的标准测试模式如前所述在 packages/scanner/src/tests/matchers.test.ts。插件自身的测试可用createDefaultRegistry()做drop-in断言——验证插件贡献的 matcher slug 存在、且不与内置集冲突除非是有意覆盖并已大声注释。报告 deepsec 自身的安全问题见 SECURITY.md。对工具本身的安全问题不要开公开 issue走安全披露渠道。小结贡献路径一览把 CONTRIBUTING 的要点收束成一条可执行的贡献路线先pnpm install并跑通pnpm test:unit建立基线添加 matcher 走matchers/slug.tsindex.ts注册 examples 针对性scan --matchers slug验证候选数量 全量测试与 lint组织专用规则走插件五个槽位按需填充plugins: [...]数组顺序决定单槽位覆盖触碰发布面或沙箱路径的 PR 分别补pnpm test:bundle与 live-sandbox e2e最后确保 build、test、lint、knip 四项全绿再提 PR。这条链路的每一步都有对应的源码与测试可查证也是 deepsec 把贡献质量落到工程机制上的核心设计。赞分享应用安全漏洞扫描人工智能AI Agent【免费下载链接】deepsecDeepsec is a security harness for finding vulnerabilities in your codebase powered by coding agents项目地址https://gitcode.com/gh_mirrors/deeps/deepsec点击查看免费下载相关推荐Deepsec 实战指南从 /deepsec 到全仓库漏洞扫描的完整 RunbookDeepsec 实战指南从 /deepsec 到全仓库漏洞扫描的完整 Runbook Deepsec 是一个由 AI 智能体coding agent驱动的应用安全漏洞扫描人工智能AI Agentgarak 的 AI 辅助贡献规范为 LLM 漏洞扫描器编写安全、可合并的代码garak 的 AI 辅助贡献规范为 LLM 漏洞扫描器编写安全、可合并的代码 garakGenerative AI Red teaming Asses人工智能大模型模型评测红蓝对抗提示词注入防护模型安全AI 安全治理深度探索SAConfettiView自定义图像、颜色与发射参数的终极指南 深度探索SAConfettiView自定义图像、颜色与发射参数的终极指南 想要为你的iOS应用添加令人惊叹的彩色纸屑动画效果吗SAConfettiVi上一篇SpacetimeDB LLM 基准评估解析Grok Code 生成 PostgreSQL 实时聊天应用的评分结果与缺陷诊断下一篇TEN Framework 会话式语音 AI Agent 框架示例快速上手、环境配置与自托管部署指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 deepsec 贡献指南：为 AI 漏洞扫描器新增 Matcher 与插件并打通 CI 全流程
应用安全漏洞扫描人工智能AI Agent【免费下载链接】deepsecDeepsec is a security harness for finding vulnerabilities in your codebase powered by coding agents项目地址https://gitcode.com/gh_mirrors/deeps/deepsec点击查看免费下载deepsec 是一个由编码智能体驱动、扫描代码库漏洞的安全工具其可扩展性完全建立在新的 matcher和新的插件这两个扩展点上。本文以仓库根目录的 CONTRIBUTING.md 为主线完整梳理它的仓库布局、开发工作流、bundle 分发、live-sandbox 端到端测试以及新增 matcher 与插件的标准路径并配合 packages/core/src/plugin.ts、packages/scanner/src/matchers/index.ts、e2e/bundle.test.ts 等源码佐证每个环节的真实实现。读完你既能上手提交第一个 matcher也能理解从源码到发布包的完整验证链路。仓库布局五个包与三类支撑目录deepsec 是一个 pnpm workspace 单仓库根目录 package.json 声明了node 22、pnpm8.15.9。核心代码集中在packages/下的五个工作区职责边界非常清晰packages/ core/ Types、schemas、插件契约、配置加载器 scanner/ Regex matchers 扫描引擎 processor/ AI 智能体集成Claude SDK、Codex SDK、enrich、triage、revalidate deepsec/ 可发布包打包后的 CLI deepsec/config 子导出 vercel/sandbox 执行器 e2e/ 针对 fixture 项目的端到端测试 fixtures/ vulnerable-app/ 故意植入漏洞的测试数据从 lint/knip 中排除 docs/ 面向用户的文档 samples/ 新用户可直接复制的起步示例需要特别注意的是fixtures/vulnerable-app它包含src/api/admin.ts、src/api/users.ts、src/components/comment.tsx、src/lib/crypto.ts等故意存在漏洞的源码是 matcher 单元测试packages/scanner/src/tests/matchers.test.ts和 bundle e2ee2e/bundle.test.ts共用的标准靶场因此被排除在 lint 与 knip 之外。开发工作流一套必须全部通过的验证命令从源码开始贡献标准流程是pnpm install pnpm test # 所有包包括 e2e pnpm test:unit # 排除 e2e pnpm -r build # 所有 workspace 的 tsc 类型检查 pnpm lint # biome check pnpm lint:fix # biome check --write pnpm knip # 未使用代码/依赖检测 pnpm deepsec --help # 通过 tsx 运行 CLI其中pnpm deepsec实际执行的是tsx packages/deepsec/src/cli.ts见根 package.json 的 scripts也就是说在源码环境下你跑的是 TypeScript 源码而非打包产物非常适合调试 matcher 逻辑。打包分发bundle 与 bundle 测试开发期验证通过后还要验证真正分发出去的产物pnpm bundle # esbuild → packages/deepsec/dist/{cli,config}.mjs pnpm test:bundle # bundle e2e把产物作为子进程运行e2e/bundle.test.ts 是这套流程的核心证据它用spawnSync(node, [BUNDLE, ...args])直接执行packages/deepsec/dist/cli.mjs覆盖了--help、--version、对 fixture 执行scan、从 cwd 加载deepsec.config.ts、激活配置中的内联插件、验证dist/config.d.ts不自引用 workspace 内部的deepsec/*包等场景。其中config.d.ts 自包含检查e2e/bundle.test.ts保证了消费方只安装deepsec一个 npm 包就能获得完整的类型。手动演练未发布的 onboarding想在不发布的情况下完整演练新用户的初始化流程先构建一次 bundle再把它跑在一个一次性目标仓库上pnpm bundle cd /path/to/disposable-project node /path/to/deepsec/packages/deepsec/dist/cli.mjs init这里有一个对贡献者非常重要的机制当 bundle 检测到自己运行在源码检出目录时生成的.deepsec/package.json会自动把deepsec依赖指向当前源码检出不需要 pack、link、scaffold-only 或手工改 manifest。重复运行同一个命令还能修复由旧本地 bundle 生成、错误指向 npm registry 的 workspace——e2e/bundle.test.ts 专门断言了这条修复路径把依赖临时改成^2.2.9再重跑init --scaffold-only依赖会被修正回本地源码的file:URL。合并 PR 的硬性门槛是build、test、lint、knip 全部通过任何触碰发布面即一切经由deepsec/config导入的内容的 PR 还必须通过pnpm test:bundle。CI 侧由 .github/workflows/ci.yml 在 Node 22 与 24 双版本矩阵上执行pnpm -r build、pnpm lint、pnpm knip、pnpm test:unit、pnpm test:bundle、pnpm typecheck:deepsec其中 typecheck 用刚打出的dist/config.d.ts类型检查.deepsec/deepsec.config.ts专门拦截发布类型泄漏 workspace 内部包的回归。Live-sandbox e2e手动不花 token 的真实沙箱链路常规pnpm test会跳过一项关键测试e2e/pipeline-sandbox.test.ts 用真实的 Vercel Sandbox 跑完整 pipeline但沙箱内是stub agent——它验证 bootstrap 快照、worker 拉起、文件上传/下载、结果合并这条基础设施链路不消耗模型 token。它由DEEPSEC_E2E_LIVE_SANDBOX1环境变量加 Vercel Sandbox 凭证门控describe.skipIf默认不进入测试套件。两种运行方式CI手动在 GitHub Actions 触发 E2E live sandbox 工作流需要三个仓库 secretVERCEL_TOKEN、VERCEL_TEAM_ID、VERCEL_PROJECT_ID不需要 AI key。本地在改沙箱代码时VERCEL_OIDC_TOKEN$(grep ^VERCEL_OIDC .deepsec/.env.local | cut -d -f2) \ DEEPSEC_E2E_LIVE_SANDBOX1 \ pnpm exec vitest run --project e2e e2e/pipeline-sandbox.test.ts从测试源码可以看到该测试以 stub agent 依次执行init → scan → sandbox process → sandbox revalidate并在每个沙箱阶段前后对比os.tmpdir()中的deepsec-tar-*临时 tarball 数量防止 orchestrator 长期运行把/tmp塞满e2e/pipeline-sandbox.test.ts。触及packages/deepsec/src/sandbox/的 PR 应该在合并前跑它。注意stub-agent 流程没有 AI 流量因此不会覆盖防火墙的 credential-brokering 变换专门改动那条路径的 PR 仍值得用--agent claude-agent-sdk加 AI key 做一次性验证。添加一个 matcher从 4 步快速路径到完整契约CONTRIBUTING 给出的是短版本完整版在 docs/writing-matchers.md在packages/scanner/src/matchers/slug.ts创建带MatcherPlugin导出的文件。在packages/scanner/src/matchers/index.ts注册import registry.register(...)。运行pnpm deepsec scan --project-id id --root path --matchers slug检查候选数量是否合理。pnpm test和pnpm lint。MatcherPlugin 的真实契约packages/core/src/plugin.ts 定义了 matcher 的最小结构export interface MatcherPlugin { slug: string; description: string; noiseTier: NoiseTier; // precise | normal | noisy filePatterns: string[]; requires?: MatcherGate; // tech 标签 / sentinel 文件门控 examples?: string[]; // 开发期契约每个示例必须命中 match(content: string, filePath: string): CandidateMatch[]; }几个从源码可以确认的要点门控gaterequires可指定tech标签如laravel、nextjs或sentinelFilessentinelContains谓词按扫描而非按文件解析一次。这正是 packages/scanner/src/matchers/index.ts 注释所写的框架入口 matcher 靠detectTech标签保持休眠的实现基础——仓库里大量框架 matcherExpress、Fastify、Laravel、Django、Gin、Axum……都是靠这一机制避免在不相关的仓库上误报。match返回CandidateMatch[]字段定义在 packages/core/src/types.tsvulnSlug、lineNumbers、snippet、matchedPattern。regexMatcher辅助函数packages/scanner/src/matchers/utils.ts逐行扫描每个 pattern收集 1-based 行号并截取前后各 2-3 行作为上下文一个 pattern 命中即产出一个 candidate。examples 是可执行文档examples数组是开发期契约而非运行时数据。自动发现的测试 packages/scanner/src/tests/matcher-examples.test.ts 遍历注册表里所有带 examples 的 matcher断言每个示例字符串至少产出一个 candidate——任何一个子 pattern 的 typo只要被至少一个示例覆盖就会让 CI 失败。它的注释明确建议为 matcher 的每个子 pattern 以及真实语法变体不同动词、大小写、标识符、空白都补一个示例一行一个无需额外测试接线。这也是为什么新 matcher 的 review 重点之一是 examples 是否真实反映仓库语法。标准测试模式packages/scanner/src/tests/matchers.test.ts 展示了统一的 matcher 测试范式对fixtures/vulnerable-app中已知有漏洞的输入断言必须命中对已知安全的输入断言必须不命中。例如xssmatcher 断言components/comment.tsx里dangerouslySetInnerHTML被命中missing-authmatcher 同时断言users.ts/admin.ts命中而lib/db.ts不命中。哪些 matcher 应该放进插件而非内置集只有对单一组织有意义的 matcher特定 helper 命名、内部包 import应该走插件路线见 docs/plugins.md。而如果规则形状属于公共框架或广泛适用的弱点应贡献进 deepsec 内置注册表而不是保留组织私有副本。编写插件五个槽位与最小形态插件可填充五个槽位中的任意子集槽位用途matchers额外 regex matcher与内置 matcher 并列注册notifiers发现结果上报到哪里Slack、GitHub Issues、webhook……ownership把文件映射到所属团队/人如内部目录people按 email/名字查人经理、on-call、联系方式executor在远程基础设施上运行 deepsec 命令完整契约在 packages/core/src/plugin.tsexport interface DeepsecPlugin { name: string; matchers?: MatcherPlugin[]; agents?: AgentPluginRef[]; notifiers?: NotifierPlugin[]; /** Last plugin to declare this wins. */ ownership?: OwnershipProvider; /** Last plugin to declare this wins. */ people?: PeopleProvider; /** Last plugin to declare this wins. */ executor?: ExecutorProvider; commands?: (program: unknown) void; // commander program }最小形态也是 CONTRIBUTING 给出的骨架import type { DeepsecPlugin } from deepsec/config; import { myMatcher } from ./matchers/my-matcher.js; export default function myPlugin(): DeepsecPlugin { return { name: my-org/plugin-internal-services, matchers: [myMatcher], }; }插件从deepsec.config.ts加载CLI 通过 packages/deepsec/src/load-config.tsjiti从 cwd 向上自动加载deepsec.config.{ts,mjs,js,cjs}。命名约定是 Vite 风格scope/plugin-thing。五个槽位的源码细节matchers最常见。slug全局唯一若与内置 slug 冲突插件胜出后注册覆盖这被设计成用更严格的 org 版本替换内置 matcher 的合法手段。MatcherRegistry在 packages/scanner/src/matcher-registry.ts 中用Mapstring, MatcherPlugin实现register就是set天然是最后写入者胜。ownershipfetchOwnership({ filePath, repo })返回OwnershipData | null返回null表示未配置/不可用调用方按软失败处理。deepsec enrich会把该数据附加到发现结果上用于通知路由与评审优先级。peoplelookup(query)与可选的lookupManager(person)。Person有通用核心字段name、email、title、managerKey加extra映射如slackId、slackHandle。notifiersnotify(params)返回携带externalId/externalUrl的FindingNotification用于回链到来源。注意core 不内置任何 notifier——开源的 Slack notifier 已被移除Slack 属于插件职责CONTRIBUTING 与 docs/plugins.md 都指出GitHub Issues notifier 是写第一个插件的好选题。executorlaunch返回 runIdcollect拉回结果可选status。仓库内vercel/sandbox执行器是权威示例代码在packages/deepsec/src/sandbox/但它尚未走ExecutorProvider接口那个重构在路线图上——这是五个槽位中最实验性的一个。完整可运行的内联插件示例仓库的 samples/webapp/deepsec.config.ts 是一个完整的内联插件示例与发布版插件同形只是定义在用户配置文件里const webappPlugin: DeepsecPlugin { name: webapp-internal, matchers: [webappDebugFlag, webappRouteNoRateLimit], }; export default defineConfig({ ai: { mode: gateway, provider: vercel }, projects: [ { id: webapp, root: ./your-app, githubUrl: https://github.com/acme/webapp/blob/main, infoMarkdown: fs.readFileSync(path.join(here, INFO.md), utf-8), promptAppend: Pay extra attention to /api/admin/* and /api/billing/* surfaces., priorityPaths: [src/api/admin/, src/api/billing/, src/lib/auth/], }, ], plugins: [webappPlugin], });两个真实 matcher 值得细读webapp-debug-flagsamples/webapp/matchers/webapp-debug-flag.ts用regexMatcher匹配NODE_ENV ! production与DEBUG_API等仅靠环境变量门控的调试面webapp-route-no-rate-limitsamples/webapp/matchers/webapp-route-no-rate-limit.ts则展示了手写 matcher 的优势——它先排除测试文件、_internal/、webhook 目录再判断文件是否含withRateLimit/rateLimiter.check最后逐行找导出的 handler 并带上 6 行上下文。这正是 docs/writing-matchers.md 所说需要负条件如没有认证助手的路由声明或同文件多组相关搜索时应写 TypeScript matcher 而非声明式 matcher 的场景。e2e/bundle.test.ts 甚至专门验证了这个 sample在samples/webapp目录下用--matchers webapp-debug-flag,webapp-route-no-rate-limit跑 scan断言两个自定义 matcher 都出现在运行日志中——这是配置加载 → 插件激活 → 扫描调用全链路的最小闭环证明。分辨率顺序ownership、people、executor是单槽位最后一个声明者胜通用codeowners插件可先加载组织专属 oracle 排在plugins: [...]数组后面即可覆盖。matchers、notifiers、agents是可叠加的所有插件的贡献全部堆叠。代码风格与评审原则匹配既有代码风格lint 用 Biomepnpm lint:fix自动格式化。默认不写注释只有当为什么不明显时才加隐藏约束、微妙不变量、workaround。禁止写复述代码的注释。保持 PR 小而单一如果加 matcher 需要重构测试 fixture拆成独立 PR。测试体系vitest 与 workspace 粘合测试用 vitest由pnpm test驱动。每个包有自己的vitest.config.tsvitest.workspace.ts 把它们粘合为 workspace 级配置。matcher 的标准测试模式如前所述在 packages/scanner/src/tests/matchers.test.ts。插件自身的测试可用createDefaultRegistry()做drop-in断言——验证插件贡献的 matcher slug 存在、且不与内置集冲突除非是有意覆盖并已大声注释。报告 deepsec 自身的安全问题见 SECURITY.md。对工具本身的安全问题不要开公开 issue走安全披露渠道。小结贡献路径一览把 CONTRIBUTING 的要点收束成一条可执行的贡献路线先pnpm install并跑通pnpm test:unit建立基线添加 matcher 走matchers/slug.tsindex.ts注册 examples 针对性scan --matchers slug验证候选数量 全量测试与 lint组织专用规则走插件五个槽位按需填充plugins: [...]数组顺序决定单槽位覆盖触碰发布面或沙箱路径的 PR 分别补pnpm test:bundle与 live-sandbox e2e最后确保 build、test、lint、knip 四项全绿再提 PR。这条链路的每一步都有对应的源码与测试可查证也是 deepsec 把贡献质量落到工程机制上的核心设计。赞分享应用安全漏洞扫描人工智能AI Agent【免费下载链接】deepsecDeepsec is a security harness for finding vulnerabilities in your codebase powered by coding agents项目地址https://gitcode.com/gh_mirrors/deeps/deepsec点击查看免费下载相关推荐Deepsec 实战指南从 /deepsec 到全仓库漏洞扫描的完整 RunbookDeepsec 实战指南从 /deepsec 到全仓库漏洞扫描的完整 Runbook Deepsec 是一个由 AI 智能体coding agent驱动的应用安全漏洞扫描人工智能AI Agentgarak 的 AI 辅助贡献规范为 LLM 漏洞扫描器编写安全、可合并的代码garak 的 AI 辅助贡献规范为 LLM 漏洞扫描器编写安全、可合并的代码 garakGenerative AI Red teaming Asses人工智能大模型模型评测红蓝对抗提示词注入防护模型安全AI 安全治理深度探索SAConfettiView自定义图像、颜色与发射参数的终极指南 深度探索SAConfettiView自定义图像、颜色与发射参数的终极指南 想要为你的iOS应用添加令人惊叹的彩色纸屑动画效果吗SAConfettiVi上一篇SpacetimeDB LLM 基准评估解析Grok Code 生成 PostgreSQL 实时聊天应用的评分结果与缺陷诊断下一篇TEN Framework 会话式语音 AI Agent 框架示例快速上手、环境配置与自托管部署指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考