企业官网建设流程全解析

1. 从零认识 security-audit-skill：它到底解决什么问题

第一次看到security-audit-skill这个名字，很多人会以为它只是某个安全扫描工具的别名。实际上，它更像是一套面向编码智能体（coding-agent）的安全审计技能包——把安全审计这件事从“人工翻代码”变成“智能体按技能流程自动执行”。我最初接触它，是因为团队里用 coding-agent 做日常代码生成和重构，速度确实快，但随之而来的问题是：智能体写出来的代码，安全边界谁来兜底？靠人工 review 根本追不上生成速度。security-audit-skill就是在这个背景下进入视野的。

它的核心价值可以拆成三层。第一层是技能定义：把安全审计拆成可复用的技能单元，比如输入校验审计、依赖漏洞审计、权限边界审计、敏感信息泄露审计等，每个技能都有明确的触发条件、执行步骤和输出格式。第二层是与 coding-agent 的协同：智能体在生成或修改代码后，可以调用这些技能对产物做自检，而不是等上线后被动挨打。第三层是可扩展性：你可以按自己项目的技术栈补充自定义技能，比如针对特定框架的模板注入检查、针对特定云服务的配置审计。

适合谁来参考？如果你是用 coding-agent 做开发的工程师，这套东西能帮你把安全左移落到实处；如果你是安全工程师，它能帮你把重复的审计逻辑沉淀成技能，减少每次从零写规则的成本；如果你是技术负责人，它提供了一种把安全能力嵌入研发流程的思路，而不是靠事后补丁。哪怕你只是对“智能体怎么自己做安全审计”好奇，这套技能的设计思路也值得拆开看。

我实测下来最大的感受是：它不追求“一键扫出所有漏洞”这种不切实际的承诺，而是强调技能的可组合、可审计、可追溯。这一点比很多号称全自动的安全工具要务实得多。下面我会从设计思路、核心细节、实操过程、问题排查四个维度，把security-audit-skill拆透，尽量让你看完能直接在自己的 coding-agent 工作流里复现。

2. 内容整体设计与思路拆解

2.1 为什么是“技能”而不是“工具”

传统安全扫描工具的思路是：你给它一个代码库，它跑一堆规则，吐出一份报告。这个模式的问题在于上下文缺失。工具不知道这段代码是刚被智能体改过的、不知道这次改动的意图是什么、不知道项目当前处于什么阶段。而security-audit-skill选择“技能”这个抽象，本质上是把审计能力挂载到 coding-agent 的执行上下文里。

技能（skill）这个概念的妙处在于：它是一段有输入、有输出、有前置条件、有后置校验的可执行逻辑。coding-agent 在完成一次代码生成后，可以按技能定义去调用审计逻辑，审计结果又能反过来影响智能体的下一步动作——比如发现高危问题就阻止提交，发现中危问题就生成修复建议。这种闭环是纯工具模式做不到的。

我选择用技能模式落地，还有一个现实原因：规则会过时，技能可以迭代。安全规则库更新频繁，但技能定义可以保持相对稳定，只需要更新技能内部的规则实现。这样 coding-agent 的调用方式不用变，维护成本大幅降低。

2.2 技能拆分的粒度怎么定

这是设计时最纠结的地方。拆得太粗，一个技能包揽所有审计，调用一次跑半天，反馈太慢；拆得太细，几十个技能，coding-agent 不知道该调哪个，反而增加决策负担。我的经验是按“审计对象 + 风险类型”两个维度交叉拆分，粒度控制在“一次调用能在秒级到十秒级完成”这个区间。

具体来说，我把它拆成四类核心技能：

• 输入面审计技能：检查所有外部输入的处理路径，包括参数校验、类型转换、边界检查、编码处理。这类技能关注的是“脏数据能不能进来”。
• 依赖面审计技能：检查第三方依赖的版本、已知问题、许可证风险。这类技能关注的是“别人写的代码有没有坑”。
• 权限面审计技能：检查认证、授权、会话管理、资源访问控制。这类技能关注的是“谁能干什么”。
• 数据面审计技能：检查敏感数据的存储、传输、日志输出、脱敏处理。这类技能关注的是“数据会不会漏”。

这四类覆盖了绝大多数 Web 服务和后端应用的常见风险面。每类下面再按技术栈细分，比如输入面审计里，针对不同语言的字符串处理、针对不同框架的请求解析，都有对应的子技能。这样 coding-agent 可以根据当前改动的文件类型和框架，精准调用对应技能，而不是无差别全量扫描。

2.3 与 coding-agent 的协同机制设计

技能定义好了，怎么让 coding-agent 用起来？这里有个关键设计决策：是让智能体主动调用，还是让流程强制触发。我两种都试过，最后采用的是混合模式。

主动调用适合探索性场景：智能体在生成代码后，自己判断“这段逻辑涉及用户输入，我应该跑一下输入面审计技能”。这种方式灵活，但依赖智能体的判断力，可能漏调。强制触发适合关键路径：比如任何涉及认证授权的代码改动，流程层面强制触发权限面审计技能，不管智能体怎么想。这种方式可靠，但可能产生冗余调用。

混合模式的具体实现是：在 coding-agent 的技能注册表里，给每个审计技能标注触发条件。触发条件可以是文件路径模式、代码变更类型、关键词命中、或者前一个技能的输出。智能体在每次代码变更后，会遍历注册表，匹配触发条件，命中的技能自动进入待执行队列。同时，智能体也可以在执行过程中手动追加技能调用。这样既保证了关键路径的覆盖，又保留了灵活性。

提示：触发条件的设计要避免“全命中”。我一开始把输入面审计的触发条件设成“任何文件变更”，结果每次改个注释都要跑一遍完整审计，反馈慢到没法用。后来改成“变更涉及请求处理、参数解析、字符串拼接相关文件”才合理。

2.4 输出格式与可追溯性设计

审计技能的输出不能只是一句“有问题”或“没问题”。我要求每个技能输出结构化结果，至少包含：技能标识、执行时间、审计对象、发现列表、每条发现的严重级别、证据片段、修复建议、置信度。这个结构让 coding-agent 能程序化处理结果，也让人工复核时能快速定位。

可追溯性方面，每次技能执行都会写入审计日志，日志里记录调用来源（是自动触发还是手动调用）、输入摘要、输出摘要、耗时。这样当出现“为什么这次没审出来”的疑问时，可以回溯到具体是哪次调用、输入是什么、技能版本是什么。我踩过的坑是：早期没记录技能版本，后来技能逻辑更新了，旧日志对不上，排查问题非常痛苦。加上版本号后，追溯清晰多了。

3. 核心细节解析与实操要点

3.1 技能定义文件的结构

每个security-audit-skill技能都是一个独立的定义文件，我用的格式是 YAML 加内嵌脚本。YAML 负责元信息，脚本负责执行逻辑。一个典型的技能定义长这样：

skill_id: input-validation-audit version: 1.2.0 category: input-surface trigger: file_patterns: - "**/controllers/**" - "**/handlers/**" - "**/api/**" change_types: - added - modified keywords: - "request" - "params" - "body" - "query" execution: script: scripts/input_validation_audit.py timeout_seconds: 30 max_findings: 50 output: schema: schemas/audit_result.json severity_levels: - critical - high - medium - low - info

这里有几个细节值得说。trigger里的file_patterns用的是 glob 模式，覆盖常见的请求处理目录。change_types限定只对新增和修改的文件触发，避免对未变更文件做无谓审计。keywords是辅助匹配，当文件路径不明确时，靠内容关键词兜底。execution里的timeout_seconds很关键——审计脚本不能无限跑，超时后要能优雅退出并返回部分结果。max_findings防止一次输出过多发现导致结果爆炸，超过上限时按严重级别截断。

注意：version字段必须严格维护。我吃过亏，技能逻辑改了但版本没升，导致审计日志里的版本号和实际行为对不上，排查问题时误导了很久。现在我的做法是：任何逻辑变更都升版本号，哪怕只是改了一个判断条件。

3.2 输入面审计技能的核心逻辑

输入面审计是使用频率最高的技能，我重点拆一下它的实现思路。核心逻辑分四步：定位输入源、追踪数据流、检查校验点、评估风险。

定位输入源时，脚本会扫描代码中的请求对象访问模式。不同框架写法不同，比如有的用request.args.get，有的用req.body，有的用ctx.request.body。脚本维护一个模式库，覆盖主流框架的常见写法。这一步的目标是找出所有“外部数据进入系统”的入口。

追踪数据流是最难的部分。完整的数据流分析需要构建抽象语法树，成本高。我的折中方案是基于正则和启发式规则的轻量追踪：从输入源出发，沿着变量赋值、函数调用、字符串拼接的路径向下追，追到“数据被使用”的地方就停。比如输入被拼进 SQL 语句、被写入文件、被返回给前端，这些都是需要关注的使用点。轻量追踪会漏掉一些复杂路径，但胜在快，适合在 coding-agent 的快速反馈循环里用。

检查校验点时，脚本会在数据流路径上找校验逻辑。常见的校验包括类型检查、长度限制、白名单匹配、正则验证、转义处理。脚本会判断校验是否发生在数据使用之前，以及校验是否覆盖了所有分支。这里有个经验：校验的位置比校验的存在更重要。我见过很多代码有校验，但校验在数据已经被使用之后才执行，等于没校验。

评估风险时，脚本根据“输入源类型 + 数据流路径 + 校验情况 + 使用点类型”四个维度打分。比如“用户可控输入 + 直接拼进 SQL + 无校验”就是高危，“用户可控输入 + 经过白名单校验 + 用于日志输出”就是低危。打分规则我迭代了好几版，核心原则是宁可误报，不可漏报，因为漏报的代价远大于误报。

3.3 依赖面审计技能的实操要点

依赖面审计相对独立，核心是依赖清单解析 + 已知问题匹配 + 版本比对。不同语言的依赖清单格式不同，Python 是requirements.txt或pyproject.toml，JavaScript 是package.json或package-lock.json，Java 是pom.xml或build.gradle。脚本需要能解析这些格式，提取出依赖名和版本号。

已知问题匹配依赖一个本地维护的漏洞库。我不建议直接调用外部接口，因为 coding-agent 的执行环境可能没有外网访问，而且外部接口的延迟不可控。我的做法是定期同步漏洞数据到本地，技能执行时只查本地库。本地库的更新频率我设为每天一次，通过一个独立的同步任务完成。

版本比对是容易出错的地方。语义化版本（semver）的比对规则看似简单，但实际有坑：预发布版本、构建元数据、范围符号（^、~、>=）的处理都需要仔细。我建议直接用成熟的版本比对库，不要自己写。我早期自己写了一个比对函数，结果在1.0.0-alpha和1.0.0的排序上出了错，导致漏报了一个问题。

提示：依赖面审计要区分“直接依赖”和“传递依赖”。传递依赖的问题往往更隐蔽，因为开发者可能根本不知道它的存在。脚本在解析依赖清单时，要尽量展开传递依赖树，至少展开两层。

3.4 权限面审计技能的关键检查项

权限面审计关注的是“谁能对什么资源做什么操作”。核心检查项包括：认证是否强制、授权是否细粒度、会话是否安全、资源访问是否越权。

认证强制检查：脚本会找出所有对外暴露的接口，检查每个接口是否有认证中间件或认证逻辑。这里有个常见陷阱：有些接口通过路由配置声明了认证，但实际代码里认证中间件被条件跳过。脚本需要同时检查配置和代码，不能只看一处。

授权细粒度检查：脚本会分析资源访问逻辑，判断是否做了“当前用户是否有权访问该资源”的检查。典型的越权问题是：接口只检查了“用户已登录”，但没检查“该用户是否有权访问这个特定资源”。脚本会找资源 ID 的使用模式，判断是否有基于用户身份的过滤条件。

会话安全检查：脚本会检查会话令牌的生成、存储、传输、过期逻辑。常见问题包括令牌熵不足、令牌存在本地存储、令牌没有过期时间、令牌在 URL 中传递。这些检查项相对固定，适合做成规则库。

资源访问越权检查：脚本会追踪资源 ID 从请求到数据库查询的路径，判断查询条件里是否包含用户身份约束。比如SELECT * FROM orders WHERE id = ?和SELECT * FROM orders WHERE id = ? AND user_id = ?的区别，前者可能越权，后者安全。脚本通过分析查询语句的 WHERE 子句来判断。

3.5 数据面审计技能的敏感信息识别

数据面审计的核心是识别敏感信息 + 追踪其生命周期。敏感信息包括：密码、密钥、令牌、个人身份信息、支付信息、健康信息等。识别方式分两类：基于模式的识别和基于上下文的识别。

基于模式的识别靠正则表达式，比如信用卡号、身份证号、邮箱、手机号的模式。这类识别准确率高但覆盖有限，只能识别格式固定的敏感信息。基于上下文的识别靠变量名和函数名，比如变量名包含password、secret、token、key，或者函数名包含encrypt、decrypt、hash。这类识别覆盖广但误报多，需要结合上下文判断。

追踪生命周期时，脚本关注四个环节：存储、传输、日志、展示。存储环节检查敏感信息是否加密、是否明文落盘。传输环节检查是否用了安全协议、是否在 URL 或 Header 中暴露。日志环节检查敏感信息是否被打印到日志。展示环节检查敏感信息是否被完整返回给前端、是否需要脱敏。

我踩过的一个坑是：脚本把测试代码里的假密钥也报成了高危。后来加了过滤规则，排除测试目录、排除明显的占位符（如your-key-here、xxx、test），误报率才降下来。

4. 实操过程与核心环节实现

4.1 环境准备与技能包初始化

先把基础环境搭起来。我用的 coding-agent 支持技能注册机制，所以第一步是在 agent 的技能目录下创建security-audit-skill的根目录。目录结构我按功能划分：

security-audit-skill/ ├── skills/ # 技能定义文件 │ ├── input-validation-audit.yaml │ ├── dependency-audit.yaml │ ├── permission-audit.yaml │ └──># config.yaml skill_root: ./security-audit-skill log_dir: ./security-audit-skill/logs rule_dir: ./security-audit-skill/rules default_timeout: 30 max_findings: 100 blocking_levels: - critical - high warning_levels: - medium

注意：blocking_levels的设置要结合团队实际情况。如果一开始就设得太严，coding-agent 会频繁被阻断，影响开发效率，团队容易产生抵触。我的建议是初期只阻断critical，运行一段时间后再逐步收紧。

4.2 编写第一个审计技能：输入校验审计

从输入面审计开始，因为它的使用频率最高，也最能体现技能模式的价值。脚本的核心结构分四部分：解析输入、定位输入源、追踪数据流、生成发现。

解析输入时，脚本接收 coding-agent 传入的变更文件列表和文件内容。我用的接口是 agent 提供的get_changed_files()和read_file()。脚本先过滤出符合触发条件的文件，然后逐个读取内容。

定位输入源时，脚本用规则库里的模式匹配。规则库是一个 JSON 文件，结构如下：

{ "input_sources": [ { "pattern": "request\\.(args|form|json|data|values|get)\\b", "language": "python", "framework": "flask", "description": "Flask 请求对象访问" }, { "pattern": "req\\.(body|query|params|headers)\\b", "language": "javascript", "framework": "express", "description": "Express 请求对象访问" } ] }

脚本遍历规则库，对每个文件做模式匹配，记录匹配位置和匹配到的输入源类型。这一步会产出“输入源清单”，每个条目包含文件路径、行号、输入源类型、原始代码片段。

追踪数据流时，脚本从输入源出发，沿着变量赋值和函数调用向下追。实现上，我用了一个简化的数据流追踪器：先提取输入源被赋值的变量名，然后在后续代码里找这个变量名的使用。如果变量被重新赋值或传递给了其他变量，继续追踪新变量。追踪深度限制在 5 层，超过就停止，避免无限递归。

检查校验点时，脚本在数据流路径上找校验函数调用。校验函数的模式也放在规则库里，比如validate_、check_、sanitize_、escape_开头的函数，或者re.match、re.fullmatch这类正则调用。脚本判断校验是否发生在数据使用之前，以及校验是否覆盖了所有分支。

生成发现时，脚本根据风险评分规则计算严重级别。评分规则我放在rules/input_patterns.json里，结构如下：

{ "risk_scoring": { "source_weights": { "user_input": 3, "header": 2, "cookie": 2, "internal": 1 }, "sink_weights": { "sql_query": 5, "file_write": 4, "command_exec": 5, "html_output": 3, "log_output": 1 }, "validation_discount": { "whitelist": 0.2, "type_check": 0.5, "length_check": 0.7, "none": 1.0 } } }

最终风险分 = 输入源权重 × 使用点权重 × 校验折扣。分数超过阈值的生成发现，按分数映射到严重级别。

4.3 技能注册与触发配置

脚本写好后，需要在 coding-agent 里注册技能。注册方式取决于 agent 的实现，我用的 agent 支持通过配置文件注册。在 agent 的技能注册表里加上：

skills: - id: input-validation-audit path: ./security-audit-skill/skills/input-validation-audit.yaml enabled: true priority: 10 - id: dependency-audit path: ./security-audit-skill/skills/dependency-audit.yaml enabled: true priority: 20 - id: permission-audit path: ./security-audit-skill/skills/permission-audit.yaml enabled: true priority: 15 - id:>trigger: file_patterns: - "**/auth/**" - "**/middleware/**" - "**/permissions/**" - "**/acl/**" change_types: - added - modified keywords: - "authenticate" - "authorize" - "permission" - "role" - "session"

权限面审计的触发条件更聚焦，只对认证授权相关的文件触发。这样避免了对普通业务代码做无谓的权限审计。

4.4 一次完整的审计执行记录

我拿一个实际项目做了一次完整执行，记录如下。项目是一个 Python Flask 写的订单服务，coding-agent 刚完成了一次“新增订单查询接口”的代码生成。

第一步：变更检测。agent 检测到controllers/order_controller.py和services/order_service.py有变更，变更类型为 modified。

第二步：触发匹配。输入面审计的触发条件命中controllers/路径，且变更文件内容包含request.args关键词，技能进入待执行队列。权限面审计的触发条件未命中，因为变更文件不在auth/或middleware/路径下。依赖面审计和数据面审计也未命中。

第三步：技能执行。输入面审计脚本启动，读取两个变更文件，定位到 3 个输入源：request.args.get('order_id')、request.args.get('user_id')、request.args.get('status')。追踪数据流发现，order_id被直接传入Order.query.get(order_id)，user_id被传入Order.query.filter_by(user_id=user_id)，status被传入Order.query.filter_by(status=status)。

第四步：校验检查。脚本发现order_id没有类型校验，直接用于数据库查询。user_id没有校验，但用于过滤条件。status没有校验，用于过滤条件。

第五步：风险评分。order_id的风险分 = 用户输入权重 3 × SQL 查询权重 5 × 无校验折扣 1.0 = 15，映射为high。user_id的风险分 = 3 × 5 × 1.0 = 15，但因为它用于过滤条件而非直接查询，脚本做了降权处理，最终为medium。status同理为medium。

第六步：输出结果。脚本生成 3 条发现，写入审计日志，返回给 agent。agent 根据blocking_levels配置，发现high级别命中阻断条件，阻止了代码提交，并生成了修复建议：对order_id增加类型校验和范围校验。

第七步：修复与复检。agent 根据建议修改代码，增加了order_id的整数校验和范围校验。修改后重新触发输入面审计，风险分降至 3 × 5 × 0.5 = 7.5，映射为low，不再阻断。代码提交通过。

这次执行从触发到完成耗时约 4 秒，其中脚本执行 2.3 秒，结果处理 1.7 秒。反馈速度在可接受范围内。

4.5 审计日志的查看与分析

每次技能执行都会写入日志，日志文件按日期分目录，按技能分文件。日志格式是 JSON Lines，每行一条记录。一条典型的日志记录：

{ "timestamp": "2025-01-15T10:23:45.123Z", "skill_id": "input-validation-audit", "skill_version": "1.2.0", "trigger_type": "auto", "changed_files": ["controllers/order_controller.py", "services/order_service.py"], "findings_count": 3, "findings": [ { "severity": "high", "file": "controllers/order_controller.py", "line": 42, "evidence": "order_id = request.args.get('order_id')", "sink": "Order.query.get(order_id)", "risk_score": 15, "suggestion": "增加整数类型校验和范围校验" } ], "duration_ms": 2340, "status": "completed" }

分析日志时，我主要看三个指标：发现数量趋势、严重级别分布、技能执行耗时。发现数量突然上升，可能是新代码引入了问题，也可能是技能规则更新导致误报增加。严重级别分布能反映整体安全状况。执行耗时如果持续上升，可能需要优化脚本或调整触发条件。

我每周会做一次日志汇总，把高频发现类型整理出来，反馈给团队做针对性培训。比如某段时间order_id类型校验缺失的问题反复出现，就说明团队对这个点的意识不够，需要专门强调。

5. 常见问题与排查技巧实录

5.1 技能不触发或触发过少

这是最常见的问题。表现是代码明明有变更，但审计技能没跑。排查思路按顺序来：

先查触发条件。打开技能定义文件的trigger段，对照变更文件的路径和内容，看是否命中。常见原因是file_patterns写得太窄，比如只写了controllers/，但实际变更在api/目录下。解决方法是放宽模式，或者增加更多模式。

再查技能注册状态。确认技能在 agent 的注册表里是enabled: true。我有一次调试时把技能禁用了，忘了改回来，排查了半天才发现。

然后查变更检测。确认 agent 是否正确检测到了文件变更。有些 agent 对未跟踪文件或忽略目录下的文件不触发变更检测。检查 agent 的忽略配置，确保审计相关目录不在忽略列表里。

最后查优先级和队列。如果多个技能同时触发，优先级低的可能被跳过或延迟。检查 agent 的技能队列配置，确认没有队列长度限制导致技能被丢弃。

提示：我建了一个“触发调试模式”，在 config 里加一个debug_trigger: true开关，打开后 agent 会输出每次变更的触发匹配详情，包括哪些技能命中、哪些没命中、没命中的原因。这个功能在排查触发问题时非常省时间。

5.2 误报太多导致团队抵触

误报是安全审计工具的通病，security-audit-skill也不例外。误报太多，团队会逐渐忽略审计结果，技能就形同虚设。我的应对策略分三层：

第一层是规则调优。分析误报案例，找出误报模式，在规则库里加排除条件。比如测试代码里的假密钥、示例代码里的占位符、框架自带的校验逻辑，都可以通过排除规则过滤掉。我维护了一个exclusions.json，记录所有排除模式。

第二层是置信度分级。每条发现除了严重级别，还标注置信度（high/medium/low）。高置信度的发现直接阻断，中置信度的生成警告，低置信度的只记录不提示。这样团队不会被低置信度的误报干扰。

第三层是反馈闭环。在审计结果里加一个“标记为误报”的入口，团队标记后，误报案例进入待分析队列。我每周分析一次，把确认的误报模式加入排除规则。这个闭环让误报率持续下降。

我实测下来，经过三轮调优，误报率从初期的 40% 降到了 8% 左右。剩下的 8% 主要是复杂数据流场景，需要人工判断。

5.3 审计脚本执行超时

脚本超时通常是因为数据流追踪太深或文件太大。排查和解决方法：

先看超时设置。确认timeout_seconds是否合理。默认 30 秒对大多数场景够用，但如果项目文件很大或数据流很复杂，可能需要调大。不过调大超时只是治标，根本还是要优化脚本。

再查追踪深度。数据流追踪的深度限制如果设得太大，遇到复杂代码会指数级展开。我一般把深度限制在 5 层，超过就停止追踪并标注“追踪截断”。这样既控制了耗时，又不会完全漏掉深层问题。

然后查文件大小。单个文件超过一定行数（比如 5000 行）时，脚本处理会变慢。我的做法是对大文件做分片处理，或者跳过明显不相关的文件（如自动生成的代码、第三方库代码）。

最后查规则库大小。规则库太大时，模式匹配会变慢。我定期清理规则库，移除过时规则，合并重复规则。规则库控制在 500 条以内时，匹配速度比较理想。

5.4 审计结果与实际情况不符

有时候脚本报了一个问题，但人工看代码发现不是问题；或者脚本没报，但实际有问题。这类问题排查起来最费劲，因为涉及脚本逻辑和实际语义的差异。

漏报排查：先确认输入源是否被正确识别。如果脚本没识别到某个输入源，后面的追踪和检查都不会发生。检查规则库是否覆盖了该框架的写法。我遇到过一次漏报，原因是项目用了一个小众框架，请求对象的访问方式不在规则库里。补充规则后解决。

误报排查：先看数据流追踪是否走了错误路径。脚本的轻量追踪可能把不相关的变量关联起来，导致误判。检查追踪路径上的变量名是否被复用。我遇到过一次误报，原因是两个不同作用域的变量同名，脚本把它们当成同一个变量追踪了。后来加了作用域分析才解决。

语义差异排查：有些代码在语法上看起来有问题，但语义上是安全的。比如用了参数化查询但写法比较特殊，脚本没识别出来。这类问题需要在规则库里增加对该写法的识别，或者加白名单。

5.5 常见问题速查表

5.6 独家避坑技巧

技巧一：技能版本和规则库版本分开管理。技能逻辑变更升技能版本，规则库变更升规则库版本。两者独立，排查问题时能快速定位是逻辑问题还是规则问题。我早期把两者混在一起，版本号一升全升，根本分不清是哪个变了。

技巧二：审计日志加“输入指纹”。每次执行记录输入文件的哈希值，这样当发现结果异常时，可以确认输入是否和预期一致。有一次我发现审计结果和实际代码对不上，查了半天才发现 agent 读取的是缓存文件，不是最新版本。加了输入指纹后，这类问题一眼就能看出来。

技巧三：定期做“审计审计”。每隔一段时间，人工抽查一批审计结果，验证脚本的判断是否准确。我每月抽 20 条发现做人工复核，统计准确率和漏报率。这个习惯帮我发现了多个规则库的盲区。

技巧四：给技能加“干跑模式”。干跑模式下，技能只输出“会报什么”，但不实际阻断流程。新技能上线前先用干跑模式跑一周，观察误报情况，确认稳定后再开启阻断。这个做法避免了新技能上线初期对团队的冲击。

技巧五：把高频问题做成“修复模板”。对于反复出现的问题类型，我让 coding-agent 在生成修复建议时直接套用模板。比如“输入校验缺失”的修复模板就是“增加类型校验 + 增加范围校验 + 增加异常处理”。模板化后，修复速度明显提升，团队也更愿意接受审计建议。

6. 技能扩展与持续演进

6.1 自定义技能的开发流程

security-audit-skill的框架是开放的，你可以按自己的需求开发自定义技能。开发流程我总结为五步：定义审计目标、设计触发条件、编写执行脚本、定义输出格式、测试与调优。

定义审计目标时，要明确这个技能解决什么问题、覆盖什么范围、不覆盖什么范围。目标越具体，技能越容易做好。比如“检查所有数据库查询是否使用了参数化查询”就比“检查数据库安全”具体得多。

设计触发条件时，参考现有技能的触发配置，根据审计目标的特征来定。如果审计目标只和特定文件类型相关，就用file_patterns限定。如果和特定代码模式相关，就用keywords匹配。

编写执行脚本时，尽量复用现有脚本的框架和工具函数。我把数据流追踪、模式匹配、风险评分这些通用逻辑抽成了公共模块，新技能直接调用，减少重复开发。

定义输出格式时，严格遵循audit_result.json的 schema，确保结果能被 agent 统一处理。不要自定义格式，否则 agent 可能无法解析。

测试与调优时，先用历史代码做回归测试，确认技能能正确识别已知问题。再用干跑模式跑一周，观察误报情况。调优到误报率可接受后，再开启阻断。

6.2 技能组合与流水线

单个技能的能力有限，多个技能组合起来才能覆盖完整的安全审计。我设计了一个审计流水线，按顺序执行技能，前一个技能的输出可以作为后一个技能的输入。

流水线的典型顺序是：依赖面审计 → 输入面审计 → 权限面审计 → 数据面审计。依赖面审计先跑，因为它不依赖代码变更，可以独立执行。输入面审计紧跟其后，因为它覆盖最广。权限面审计和数据面审计在最后，因为它们更聚焦。

技能之间可以传递上下文。比如输入面审计发现了一个用户可控输入，可以把“这个输入被用于数据库查询”的信息传给数据面审计，数据面审计再检查这个查询是否涉及敏感数据。这种上下文传递让审计更精准。

流水线的执行结果汇总成一份综合报告，按严重级别排序，高优先级的发现排在前面。报告里标注每条发现来自哪个技能，方便追溯。

6.3 与 CI/CD 流程的集成

security-audit-skill最终要嵌入研发流程才能发挥最大价值。我把它集成到了 CI/CD 流程里，作为代码提交前的检查环节。

集成方式是在 CI 配置里加一个审计步骤，调用 coding-agent 执行审计技能。审计通过则继续后续流程，审计不通过则阻断并输出报告。审计报告作为构建产物存档，方便后续查阅。

集成时要注意几点：审计步骤要能快速失败，不要等所有技能跑完才报错，发现阻断级别的问题就立即终止。审计结果要能追溯到具体提交，报告里记录 commit hash 和变更文件列表。审计超时要能优雅处理，超时后输出部分结果并标注超时，不要直接崩溃。

我实测下来，集成后代码提交前的平均审计耗时约 8 秒，对开发体验的影响可以接受。阻断的问题中，约 70% 是输入校验缺失，20% 是权限检查缺失，10% 是其他类型。这个分布帮我们明确了后续的培训重点。

6.4 技能库的版本管理与团队协作

当团队多人维护技能库时，版本管理和协作规范就很重要。我的做法是：技能库用 Git 管理，每个技能一个目录，变更走 Pull Request 流程。

技能目录结构统一为：

skills/input-validation-audit/ ├── skill.yaml # 技能定义 ├── script.py # 执行脚本 ├── rules.json # 规则库 ├── tests/ # 测试用例 │ ├── positive/ # 应报问题的用例 │ └── negative/ # 不应报问题的用例 └── CHANGELOG.md # 变更记录

每个技能必须有测试用例，覆盖正例和反例。PR 合并前必须跑通所有测试。CHANGELOG 记录每次变更的内容和原因，方便追溯。

团队协作时，我指定一个技能库维护者，负责审核 PR、合并变更、发布版本。其他成员可以提交 PR，但不能直接推送到主分支。这个规范避免了技能库被随意修改导致行为不一致。

6.5 后续演进方向

security-audit-skill目前主要覆盖静态审计，后续可以往几个方向演进。一是增加动态审计能力，在代码运行时采集行为数据，做运行时安全检查。二是引入机器学习，用历史审计数据训练模型，提升风险评分的准确性。三是扩展语言和框架覆盖，目前主要覆盖 Python 和 JavaScript，后续可以增加 Go、Java、Rust 等语言的支持。四是做跨项目知识共享，把不同项目的审计发现汇总分析，提炼出通用的安全模式。

不过这些都是后话。当前阶段，我的重点是把现有技能打磨稳定，把误报率降到 5% 以下，把审计耗时控制在 5 秒以内。基础打牢了，扩展才有意义。

我个人在实际操作中的体会是：安全审计这件事，工具能解决 80% 的重复劳动，但剩下 20% 的判断仍然需要人。security-audit-skill的价值不是替代人，而是把人从重复劳动里解放出来，让人专注于真正需要判断力的部分。这个定位想清楚了，技能的设计和调优方向就不会跑偏。