企业官网建设流程全解析

• 应用安全
• 漏洞扫描
• 人工智能
• AI Agent

导读

本文以 prompt-samples/11-go-multi-framework-batch.md 这份"提示词样本"为主线，深入拆解 Deepsec 这个由编码 Agent 驱动的安全扫描器，如何为一个同时引入Gin 与 Chi 两个 Go Web 框架的项目，自动组装出一份完整、可复现、面向大模型的安全审查提示词。读完本文，你将理解 Deepsec 提示词的完整骨架（核心提示 + 框架威胁高亮 + Slug 级审查笔记 + Agent 层包装）、样本与源码/测试的对应关系、以及如何通过UPDATE_PROMPT_SAMPLES=1 pnpm test:unit重新生成这类样本。

一、样本是什么：一个"Go 双框架批量扫描"场景的完整快照

prompt-samples/11-go-multi-framework-batch.md是 Deepsec 仓库中 11 个提示词样本之一，它并不是一份人类手写的文档，而是一份运行时真正发送给编码 Agent 的完整提示词的确定性快照（fixture）。文件开头的 HTML 注释记录了该场景的元数据，逐字段解读如下：

Scenario : 11-go-multi-framework-batch Go project that pulls in two Go frameworks (Gin + Chi) — both highlights ship for a Go-only batch. Detected tags: ["gin","chi","go"] Batch files : ["cmd/server/main.go"] Batch langs : ["go"] Batch slugs : ["go-gin-route","go-chi-route","go-ssrf"] Generated by : packages/processor/src/__tests__/prompt-samples.test.ts Regenerate : UPDATE_PROMPT_SAMPLES=1 pnpm test:unit

这 6 行元数据本身就浓缩了 Deepsec 提示词组装的核心链路：

• Detected tags：来自扫描器对项目的技术栈识别（detectTech()），这里识别出项目同时使用 Gin、Chi 与 Go；
• Batch files：本次批量调查只包含一个文件cmd/server/main.go（一个同时挂了 Gin 和 Chi 路由的 Go 服务入口）；
• Batch langs：由批内文件的扩展名推导出的规范语言名，这里只有"go"（对应 file-language.ts 中.go → "go"的映射）；
• Batch slugs：扫描器在该文件上命中的漏洞匹配器集合；
• Generated by / Regenerate：表明该样本由 prompt-samples.test.ts 生成并校验，可用UPDATE_PROMPT_SAMPLES=1 pnpm test:unit在提示词组装逻辑变更后重新生成。

这个场景的设计意图，从 prompt-samples.fixtures.ts 中的定义可以看得更清楚：一个 Go 项目同时引入 Gin 和 Chi 两个框架，验证在Go 单语言批量下，两个框架的威胁高亮会同时进入提示词。这与 04/05 号样本（多语言仓库中按批内语言过滤其他框架高亮）形成对照：框架高亮跟随的是"批内文件的语言"，而不是"整个项目检测到的技术栈"。

二、提示词的整体架构：三段式组装 + Agent 层包装

这份样本实际是两层代码拼接的产物，理解这一点是读懂全文的关键：

1. 系统提示词半段（assembler 组装）：由 assemblePrompt() 完成，顺序为：

   • 通用核心提示（core.ts 中的CORE_PROMPT）；
   • 框架威胁高亮段## Threat highlights for this repo's tech stack（按detectedTags+batchLanguages过滤，来自 highlights.ts）；
   • Slug 级审查笔记段## Slug-specific reviewer notes（仅包含批内实际命中的 slug，来自 slug-notes.ts）；
   • 可选的INFO.md与config.json:promptAppend追加内容（用---分隔，避免出现连续两个 H2）。

2. Agent 层包装（buildInvestigatePrompt）：由 agents/shared.ts 中的buildInvestigatePrompt()完成，追加## Target Files（含命中行号）、## Investigation Instructions（调查步骤）与## Output Format（JSON 输出规格）。

样本中## Severity Classification、## Known Vulnerability Categories、## False Positive Guidance等段落来自核心提示；### Gin、### Chi段落来自框架高亮；go-gin-route/go-chi-route/go-ssrf三条笔记来自 slug 笔记；## Target Files及其之后的全部内容来自 Agent 层包装。测试 prompt-samples.test.ts 正是通过断言"样本同时包含两半内容"来防止其中一半丢失。

组装器还有一个重要的预算控制机制：FRAMEWORK_SECTION_CHAR_BUDGET = 6000字符（约 1500 token，按 4 字符 ≈ 1 token 估算）。当多语言巨型仓库使框架段超预算时，会退化为一行"本仓库使用 N 个已知框架：…"的摘要，而不是把提示词撑爆（见 07 号样本07-overflow-fallback的设计意图）。

三、核心提示词详解：让 Agent 以"攻击者思维"做静态审查

样本正文的第一段定义了 Agent 的角色与任务边界：

• 角色设定：世界级安全研究员，精通 Web 安全、认证系统与跨语言现代框架；以攻击者思维寻找自动化工具漏掉的"微妙逻辑缺陷"——竞态条件、参数操纵导致的认证绕过、信任边界违规；
• 候选机制：扫描器用正则与启发式模式"撒大网"产出候选文件，多数是误报；Agent 的职责是以候选为起点做彻底、开放式的安全审查；
• 硬性约束：仅做静态分析，不得复现、利用或触发任何漏洞，不得运行目标代码、向端点发包、执行 PoC 脚本。

3.1 严重性分级

提示词为安全漏洞定义了三级、为非安全缺陷定义了两级，这是后续 JSON 输出的枚举依据：

3.2 已知漏洞类别表

提示词内置了一张完整的漏洞类别（slug）对照表，作为 Agent 的"查漏清单"——无论扫描器是否命中，Agent 都应检查所有这些类别：

3.3 误报指导（False Positive Guidance）

提示词要求 Agent 在分类前先核查缓解因素，以压制误报：

• 输入在使用前是否被清洗/转义（参数化查询、HTML 转义）？
• 是否有中间件或框架防护罩保护该代码路径？
• 该脆弱模式是否只用于可信/内部数据，而非用户输入？
• 认证检查的判定标准：只有直接包裹 handler 的中间件才算数（Express 中间件、Fastify hooks、NestJS guards、Spring filters、Rails before_action、Django decorators、FastAPI Depends）。边缘/代理/CDN/WAF 规则以及运行在 handler 之前的栈前中间件单独不足以构成防护——太容易被误配置或通过逃逸匹配器的路由绕过；
• 对于重定向：重定向前是否有显式 allowlist 或 origin 检查？

如果已完全缓解，则不得上报，只报告真实可利用的漏洞。

3.4 认证绕过模式清单

核心提示专门列出三类"看似有认证实则可绕过"的检查模式：

Query String & URL 操纵

• 参数污染：重复查询参数（如?teamId=x&teamId=y）能否改变行为或绕过检查？
• 编码字符：%2Fvs/、%00空字节——应用是否正确处理 URL 编码、双重编码与 Unicode 规范化路径？
• 路由参数注入：动态路由段能否被操纵以访问他人数据？
• Token 刷新滥用：强制刷新 token 的查询参数是否有速率限制？

认证流程绕过

• OAuth 回调操纵：state 参数篡改、redirect_uri 操纵、自定义 URI scheme 注入；
• 会话/JWT 弱点：算法未固定（algorithm pinning）、未配置认证时的 stub 会话、测试 token 在生产可达；
• 头注入：X-Forwarded-For、Authorization、自定义x-*token 是否被盲目信任？

授权缺口（有认证，但认证错了）

• 跨租户访问：用户提供的teamId/userId直接用于 DB 查询而非认证身份；
• 缺少资源级检查：认证只确认"用户已登录"，未确认"用户拥有该资源"；
• 取反的权限检查：!(await auth.can(...))这类反转逻辑。

3.5 Out-of-scope 文件

dist/、node_modules/、vendor/、generated/或匹配.gitignore的生成/供应文件应跳过；若某文件属于此类，则对它返回空 findings 数组。

四、框架威胁高亮：Gin 与 Chi 的安全检查要点

框架高亮是 Deepsec 提示词最有特色的部分：它不教模型"框架是什么"，而是直接点名扫描器看不见的高信号威胁与误报缓解点。本样本同时携带了 Gin 与 Chi 两份高亮（这正是"Go 多框架批量"场景的验证目标）。

Gin

• 每个r.GET/POST/...与r.Group(...)都是一个公共端点；通过r.Use(...)应用的认证中间件必须在同一组内的路由注册之前；
• c.Query/c.Param/c.PostForm是用户输入——常规注入面（SQL、exec、fs、URL）均适用；
• c.HTML(http.StatusOK, "tmpl", data)中若data含不可信字符串则是 XSS，除非模板使用{{.X}}（自动转义）而非{{.X | safehtml}}。

Chi

• r.Use(middleware)与r.Group(...)定义认证作用域——子路由器会继承，但r.Mount("/x", h)不会继承 mount 之后应用的中间件；
• chi.URLParam(r, "id")是用户输入，在 DB / fs / exec 调用中必须视为不可信；
• render.JSON(w, r, data)原样返回你传入的内容——DB 行常含秘密列，应使用响应形状结构体（response-shape struct）。

从 highlights.ts 可以看到，这两份高亮的languages都声明为["go"]，因此在batchLanguages = ["go"]时二者都被保留，而 Next.js / Django 等高亮则被语言过滤剔除。这正是本场景元数据里 "both highlights ship for a Go-only batch" 的含义。

与之配套的扫描器侧证据在 go-gin-route.ts 与 go-chi-route.ts：前者匹配r.GET/POST/...、.Group(、gin.Default()/gin.New()与c.Query/Param/PostForm/GetHeader/ShouldBind*访问器；后者匹配chi.NewRouter()、.Route(、.Group(、.Mount(（并特意标注"middleware inheritance gotcha"）与chi.URLParam(。两者都要求requires: { tech: [...] }，即只在detectTech()识别到对应框架时才生效，且都会跳过_test.go测试文件。

五、Slug 级审查笔记：go-gin-route / go-chi-route / go-ssrf

批内命中的每个 slug 会对应一行"上报前先核查什么"的评审直觉笔记。本样本的三条：

• go-gin-route：弱入口点候选——确认该组内没有先于路由注册的认证r.Use(...)；
• go-chi-route：弱入口点候选——确认r.Use(auth)在作用域内，且后续没有r.Mount(...)短路掉继承；
• go-ssrf：拼接 URL 传给http.Get/client.Do且无 allowlist——内部主机是高严重度情形。

这三条笔记分别来自 slug-notes.ts 中的SLUG_NOTES表。需要说明的是：通用的ssrf匹配器（ssrf.ts）主要针对 TS/JS 生态的fetch/axios/got等客户端，而 Go 场景里命中的go-ssrf是独立于通用匹配器的 Go 专用 slug，笔记也单独维护——这体现了 Deepsec"按语言生态定制审查直觉"的设计。

笔记段由renderSlugSection()生成（assemble.ts），只包含当前批内出现的 slug，因此提示词长度随扫描器实际命中规模伸缩，而不是始终携带完整注册表。

六、目标文件、调查指令与输出格式：Agent 层包装

6.1 目标文件与命中行号

## Target Files段把批内文件与扫描器命中位置一一对应，成为 Agent 的阅读清单：

• cmd/server/main.go
  • [go-gin-route] L18：Gin method registration
  • [go-chi-route] L42：Chi method registration
  • [go-ssrf] L60：http.Get with concatenated URL

行号的呈现逻辑来自 agents/shared.ts：有候选的文件列出每条[slug] L行号: 命中模式；无扫描器命中的文件（如process --diff直接调用的场景）则标注"no scanner hits — full holistic review"，引导 Agent 做整体审查而非追问候选在哪。

6.2 调查指令（五步法）

对每个文件，Agent 必须：

1. 完整读取文件（使用 Read 工具）；
2. 追踪数据流——输入从哪来？是否用户可控？
3. 跟进导入——阅读相关文件（中间件、工具、共享库）以获得完整图景；
4. 检查缓解措施——是否有清洗、校验、认证中间件或框架防护？
5. 开阔思考——寻找扫描器标记之外的问题：逻辑缺陷、竞态条件、缺失检查等。

6.3 输出格式（JSON 规格）

调查结束后，Agent 必须对每个文件输出一个 JSON 块，格式严格固定：

[ { "filePath": "relative/path/to/file.ts", "findings": [ { "severity": "CRITICAL|HIGH|MEDIUM|HIGH_BUG|BUG", "vulnSlug": "the-vuln-slug-or-other", "title": "Brief title of the issue", "description": "Detailed description of the vulnerability, the attack scenario, and evidence from the code", "lineNumbers": [10, 15], "recommendation": "How to fix this vulnerability", "confidence": "high|medium|low" } ] } ]

补充规则：vulnSlug可以是已知类别之一，也可以用"other"前缀自定义（如"other-race-condition"、"other-logic-bug"、"other-info-disclosure"）；如果某个文件经彻底调查确实没有真实漏洞，仍要包含该文件并返回空 findings 数组——这保证了每个批内文件都有对应的结构化结论，便于后续的 reconciliation（核对）与 revalidate（复验）流程。

七、样本的生成与校验：测试即文档

prompt-samples/目录不是手工维护的，而是由测试驱动的确定性产物，这一点对使用者非常重要：

• prompt-samples.test.ts 遍历PROMPT_SAMPLE_SCENARIOS，为每个场景走与生产完全相同的代码路径（assemblePrompt()+buildInvestigatePrompt()），然后断言磁盘上的样本与实时组装结果逐字节一致；
• 场景数据定义在 prompt-samples.fixtures.ts：detectedTags直接来自场景声明，batchLanguages由文件扩展名推导，batchSlugs由候选 slug 去重而来——样本因此与真实运行保持诚实一致；
• 当提示词组装器、框架高亮或 Agent 层有意改变输出形状时，开发者设置UPDATE_PROMPT_SAMPLES=1 pnpm test:unit即可让测试改写磁盘上的样本，之后在 PR 中审查 diff（测试代码注释明确建议了这种做法）。

该测试还附带两条额外断言以守护组装质量：样本必须同时包含"组装的核心半段"与"Agent 层的文件列表"（防止某一半丢失）；INFO.md内容在最终提示词中恰好出现一次（防止 Agent 层重复发射，见 prompt-samples.test.ts）。

八、如何查看与使用这份样本

对于使用者（而非贡献者）而言，这份样本的价值在于预测和调试：

• 在运行 Deepsec 扫描之前阅读对应场景样本，可以准确预期"我这种技术栈/批次的仓库，Agent 会收到什么样的指令"；
• 仓库中的 11 个样本覆盖了从空项目（01）、单框架批量（02/03/09/10）、多语言过滤（04/05/06）、超预算回退（07）、INFO.md 注入（08）到本文的 Go 双框架批量（11）等典型形态，可作为理解提示词组装行为的参考图谱；
• 若你是安全工程师，也可以把样本当作"Go + Gin/Chi 服务安全审查 checklist"来用：认证中间件顺序（Ginr.Use必须先于路由注册、Chir.Mount不继承中间件）、用户输入访问器（c.Query/chi.URLParam）、以及拼接 URL 传给http.Get的 SSRF 风险，都是可直接落到代码评审里的检查项。

相关源码路径速查：组装器 assemble.ts、核心提示 core.ts、框架高亮 highlights.ts、slug 笔记 slug-notes.ts、Agent 层包装 agents/shared.ts、场景定义 prompt-samples.fixtures.ts、生成测试 prompt-samples.test.ts、Go 匹配器 go-gin-route.ts 与 go-chi-route.ts。

• 应用安全
• 漏洞扫描
• 人工智能
• AI Agent