把 LLM 接入秘密扫描Secret Scanning最危险的不是模型精度不够而是没有一套生产前评估流程就直接上线。GitHub 的 secret scanning 要在海量仓库代码中识别 API 密钥、GitHub Personal Access Token、AWS Access Key、私钥等敏感信息。传统规则引擎擅长确定性和覆盖率LLM 可以补上语义理解能力回答“这段代码到底是真实凭据还是文档示例、测试数据、占位符”。但要判断一个候选模型是否适合生产不能只靠几条 Prompt 示例和肉眼观察必须建立一套覆盖数据标注、指标定义、离线评测、灰度验证的评估体系。这篇文章围绕秘密扫描场景说明生产前评估 LLM 需要准备什么数据、计算哪些指标、如何搭流水线、灰测阶段要盯哪些信号。这里说的“评估”并不是模型训练完成后的通用 benchmark而是把模型放到 GitHub 生产流量前评估它作为“秘密扫描检测器”这一具体任务是否可靠。生产前评估的重点不是模型能力有多强而是模型在误报、漏报、延迟、成本和不可解释行为上是否可控。1. 先拆解秘密扫描的检测链路再确定 LLM 的介入点和评估目标1.1 秘密扫描解决什么问题秘密扫描要回答的问题非常具体在仓库代码、提交历史、Issue、评论和依赖文件中是否出现了不应该出现的敏感凭据。以 GitHub secret scanning 为代表的方案会持续监测推送到仓库的内容并匹配已知凭据格式比如 AWS Access Key、GitHub Token、Slack Token、Stripe Key、SSH 私钥块等。这里的难点不是“能不能找到 token”而是“找到之后怎么处置”。如果检测结果大量是误报安全团队会被无效告警淹没真实事件反而被忽略。如果检测结果大量漏报真实凭据就可能流入公开仓库或下游系统造成数据泄露。生产前评估 LLM 的核心目标就是在这两个风险之间找到可接受的平衡点。1.2 传统规则检测的边界传统秘密扫描主要依赖正则表达式、字符熵、固定前缀和后缀校验。它的优点是确定性强、延迟低、可控性好适合覆盖格式固定的凭据。缺点是面对变体和上下文时会失效。例如文档示例中的sk_live_xxx会被当成真实密钥。测试环境中的固定 token 会被当成生产凭据。经过 Base64 编码、URL 编码、换行拆分的凭据会绕过正则。随机生成的高熵字符串会被误判为密钥。传统方案无法理解“这个 token 出现的位置是不是生产代码”“这段代码是不是演示用途”“这个环境变量是不是来自测试配置”。LLM 的语义理解能力正好可以补上这一环但代价是延迟更高、结果不稳定、成本不可忽略。1.3 LLM 介入后的检测流程与评估目标生产前评估不能脱离检测链路单独做。合理的设计不是让 LLM 扫描所有代码而是让它对规则预筛出的候选片段做二次判断代码推送或仓库变更发生后规则引擎产生候选片段。候选片段连同前后若干行上下文一起进入 LLM。LLM 输出该片段是否包含真实 secret、置信度、理由。结果进入告警或人工复核队列。在这种链路里需要回答三个问题召回是否足够真实 secret 是否因为 LLM 的误判被丢弃。精度是否可控普通代码是否被 LLM 标成高风险。性能是否可承受候选片段进入 LLM 后延迟和成本是否符合生产要求。维度传统规则规则预筛 LLM确定性高同一输入同一结果低模型输出可能抖动格式覆盖只覆盖已知格式可处理变体和编码上下文理解弱无法判断代码用途强可结合前后代码判断误报控制依赖正则质量可由 LLM 二次判断延迟毫秒级百毫秒到秒级可解释性正则命中原因明确依赖模型输出的理由维护成本需要维护规则库需要维护数据集和评估流程这张表也解释了为什么生产前评估要同时关注数据、指标和灰测。LLM 不是替代规则引擎而是嵌入到规则引擎之后的“语义仲裁层”。2. 生产前评估的第一步构建带上下文的秘密扫描评估数据集2.1 正样本与负样本怎么构造评估 LLM 能否用于秘密扫描第一件事不是调 Prompt而是准备一份接近线上输入分布的数据集。数据集的根本原则是覆盖真实场景的典型输入同时不能泄露真实凭据。正样本的来源可以包括企业内部脱敏后的真实告警记录密钥部分替换为格式合法但无效的假值。根据常见 secret pattern 生成的合成样本例如模拟 AWS 临时凭证、GitHub PAT、私钥块。代码片段中包含真实凭据出现的典型上下文比如config.py中读取环境变量、部署脚本中写入密钥。负样本的来源可以包括文档示例和 README 中的占位符例如your-api-key-here。测试代码中固定写入的假 token。示例仓库中明显是演示用途的配置。高熵随机字符串但实际不是任何凭据。普通代码中变量名包含 key 或 token但值只是普通字符串。这里要特别强调不要为了测试效果直接把网络上或内部系统里的真实密钥放进数据集。这既是安全风险也是合规风险。合成正样本只需要保持格式和上下文像真实样本不需要拥有真实密钥。注意评估数据集里的所有 secret 都应该是无效的、合成的、格式合法的假数据。真实凭据一旦进入测试集就等于在内部系统里复制敏感信息后续很难清洗干净。2.2 标签体系不是只有“是/否”数据标注不能只标true_label是 0 还是 1。秘密扫描场景中只有“包含/不包含 secret”这两个标签很难定位模型为什么错。建议至少记录以下字段字段含义示例id样本唯一 IDaws-0001secret_type凭据类型aws_access_key、github_tokencontext_type上下文类型production_code、test_code、documentationtrue_label真实是否包含 secret1、0severity风险等级high、medium、lowsnippet带上下文的代码片段前后若干行源码reason标注依据人工判断说明context_type很重要。模型如果只是“看到 token 格式就报 true”会导致文档和测试代码大量误报。加入context_type后评估报告可以按上下文类型拆分快速判断模型到底是在哪一类样本上失效。2.3 数据划分与防泄漏数据集建议按仓库或项目划分训练集、验证集和测试集而不是按行随机划分。原因很简单同一个仓库内的代码高度相似按行随机切分会造成数据泄漏测试结果会虚高。假设一个项目里有 50 个样本随机划分后训练集和测试集可能都包含同一个项目的相似代码。模型在测试集上表现好不是因为它理解了秘密扫描而是因为它记住了项目风格。正确做法是先决定哪些仓库进入训练集哪些仓库进入验证集哪些仓库进入测试集再做样本划分。划分比例也没有绝对标准但需要保证测试集覆盖所有目标 secret 类型和上下文类型。如果底层安全团队计划支持 5 类 secret测试集里至少每类都有一定数量样本。2.4 JSONL 数据集 schema 示例推荐使用 JSONL 作为评估数据集格式每行一条样本方便增量追加和并行处理。一个最小样本如下{id: aws-0001, secret_type: aws_access_key, repo_name: demo-web, path: src/config.py, context_type: production_code, true_label: 1, severity: high, snippet: from config import settings\ns3 boto3.client(\n s3,\n aws_access_key_idAKIAFAKE1234567890ABCD,\n aws_secret_access_keyFAKE_SECRET_ACCESS_KEY,\n)\n, reason: 生产代码中读取了 AWS 密钥配置}这个样本中的AKIAFAKE1234567890ABCD只是格式合法的假值不是真实密钥。测试时LLM 应该基于“这段代码位于配置文件或生产代码中”来判断它更像真实 secret而不是只因为字符串前缀匹配就报警。数据集准备好后还要写一个独立的 schema 校验脚本防止字段缺失、true_label 非法、snippet 为空。评估数据一旦脏了后续所有指标都没有意义。3. 用漏报率、误报率、延迟和成本共同定义上线门禁3.1 为什么不能只看准确率准确率Accuracy在秘密扫描场景里会欺骗人。假设候选片段中 95% 是普通代码只有 5% 是真实 secret模型全部输出“不包含 secret”准确率也有 95%。但漏报率是 100%真实凭据全部漏过这对安全系统是灾难。生产前评估必须同时看漏报和误报。漏报代表真实 secret 被放过误报代表普通代码被打上高风险标签。两者对应不同的损失漏报真实凭据可能流入公开仓库事故级别高。误报安全团队需要人工复核成本持续累积。因此指标设计要以混淆矩阵为基础并按照 secret 类型、上下文类型分别计算而不是只看一个汇总数。3.2 从混淆矩阵推导关键指标在秘密扫描场景中定义如下TP真实 secret 被识别为 secret。FN真实 secret 被识别为普通代码。FP普通代码被识别为 secret。TN普通代码被识别为普通代码。核心指标包括指标公式作用Recall / TPRTP / (TP FN)衡量漏报数值越低漏报越严重PrecisionTP / (TP FP)衡量误报低精度意味着大量人工复核F12 * Precision * Recall / (Precision Recall)综合指标用于模型 A/BFPRFP / (FP TN)普通代码被误报的比例每万样本误报量FP / 总样本数 * 10000更直观评估复核成本P95 延迟延迟排序后 95 分位评估生产链路性能Token 消耗输入输出 token 总数评估成本单看 Precision 高也不可信。如果模型只在显而易见的示例代码上报告 secretPrecision 会很高但真实变体全部漏掉。所以门禁必须同时包含 Recall 下限和 Precision 下限并额外关注每万样本误报量。3.3 指标的门禁建议上线门禁不宜写死一个数字因为不同企业的人力投入和风险容忍度不一样。但可以把建议范围列出来方便在项目启动时评审。指标建议门禁说明Recall不低于 0.95安全场景中漏报代价更高先保召回Precision不低于 0.80低于该值会带来大量人工复核压力FPR不高于 0.5%候选片段规模大时FPR 微小的变化也会放大P95 延迟不超过 2 秒超过后可能阻塞代码推送链路平均 Token 成本不超过预算上限按每百万候选片段估算月度成本如果现有规则引擎的 Recall 本身只有 0.85直接要求 LLM 达到 0.95 可以理解但不能脱离基线。生产前评估应该与当前生产基线做对比而不是只标一个绝对数字。3.4 成本指标Token 消耗和延迟LLM 在秘密扫描中不是免费使用的。候选片段需要组装进 Prompt每次调用都会产生 Token 消耗。对 GitHub 这种仓库规模候选片段可能每天以万甚至百万计成本必须纳入门禁。建议在评估时记录每个样本的输入 Token、输出 Token、延迟和调用失败次数。报告里至少要包含平均输入 Token平均输出 Token单样本平均延迟P95 延迟超时或解析失败率如果模型输出不稳定还要记录重试次数。重试会显著抬高成本和延迟即使离线测试的准确率很高上线后也可能因为重试导致链路拥塞。4. 实现离线评估流水线从 JSONL 数据集到分组评估报告4.1 候选片段抽取与格式化评估数据集不能只有单行代码。LLM 判断上下文时需要看到 secret 所在的前后几行。建议在生成 JSONL 时片段包含目标行前 5 到 10 行和后 5 到 10 行。除了源码片段还需要从数据集本身读取secret_type。原因是 LLM 在不知道秘密类型的情况下输出不稳定。加上secret_type_hint后Prompt 可以更聚焦也可以减少模型把 AWS Key 和 GitHub Token 混淆的情况。4.2 评估脚本核心实现下面是一个简化但可运行的评估脚本框架重点展示如何遍历 JSONL、调用模型、解析输出并收集延迟。import json import time from collections import defaultdict def build_prompt(snippet: str, secret_type_hint: str) - str: return ( You are a secret scanning assistant. Determine whether the following code snippet contains a real secret.\n fSecret type hint: {secret_type_hint}\n fCode snippet:\n\n{snippet}\n\n Answer with JSON: {contains_secret: true/false, confidence: 0.0-1.0, reason: ...} ) def parse_model_response(raw: str) - dict: # 实际项目中需要去掉 markdown 代码块标记并容错解析 JSON start raw.find({) end raw.rfind(}) 1 if start -1 or end 0: raise ValueError(fno json found in model output: {raw}) body raw[start:end] return json.loads(body) def estimate_tokens(*texts: str) - int: # 简化估算方式4 个字符约等于 1 个 token return sum(len(t) // 4 for t in texts) def evaluate_one(sample: dict, model_call) - dict: prompt build_prompt(sample[snippet], sample[secret_type]) start time.perf_counter() raw model_call(prompt) latency_ms (time.perf_counter() - start) * 1000 prediction parse_model_response(raw) return { id: sample[id], secret_type: sample[secret_type], context_type: sample[context_type], true_label: int(sample[true_label]), contains_secret: bool(prediction.get(contains_secret)), confidence: prediction.get(confidence, 0.0), reason: prediction.get(reason, ), latency_ms: latency_ms, tokens: estimate_tokens(prompt, raw), } def evaluate(dataset_path: str, model_call, output_path: str): rows [] with open(dataset_path, encodingutf-8) as f: for line in f: line line.strip() if not line: continue sample json.loads(line) rows.append(evaluate_one(sample, model_call)) report generate_report(rows) with open(output_path, w, encodingutf-8) as f: json.dump(report, f, ensure_asciiFalse, indent2) return reportmodel_call是解耦点。它可以是 OpenAI SDK、Anthropic SDK、本地 vLLM 服务或内部模型网关的封装。关键是评估脚本不关心具体模型只接收文本并返回模型输出。实际运行时可以这样生成 model_callimport requests def create_model_call(api_base: str, api_key: str, model_name: str): def call(prompt: str) - str: response requests.post( f{api_base}/v1/completions, headers{Authorization: fBearer {api_key}}, json{ model: model_name, prompt: prompt, temperature: 0, max_tokens: 200, }, timeout10, ) response.raise_for_status() return response.json()[choices][0][text] return call把 temperature 设置为 0 是出于可重复性考虑。虽然 LLM 即使在 temperature0 时也可能有微小随机性但低温度能显著降低输出抖动。生产评估报告的每一行要记录模型名、模型版本和 Prompt 版本便于回溯。4.3 输出分组报告generate_report不能只输出一个总指标。建议按secret_type和context_type分组输出混淆矩阵这样能快速看出模型在哪一类样本上表现差。def generate_report(rows): summary {tp: 0, fp: 0, tn: 0, fn: 0} by_type defaultdict(lambda: {tp: 0, fp: 0, tn: 0, fn: 0}) by_context defaultdict(lambda: {tp: 0, fp: 0, tn: 0, fn: 0}) latency_list [] token_total 0 for r in rows: key (r[true_label] 1, r[contains_secret] is True) summary[map_key(key)] 1 by_type[r[secret_type]][map_key(key)] 1 by_context[r[context_type]][map_key(key)] 1 latency_list.append(r[latency_ms]) token_total r[tokens] def calc_metrics(cell): tp cell[tp] fp cell[fp] tn cell[tn] fn cell[fn] precision tp / (tp fp) if tp fp else 0.0 recall tp / (tp fn) if tp fn else 0.0 f1 2 * precision * recall / (precision recall) if precision recall else 0.0 return { precision: round(precision, 4), recall: round(recall, 4), f1: round(f1, 4), } return { summary: { **calc_metrics(summary), samples: len(rows), latency_avg_ms: round(sum(latency_list) / len(latency_list), 2), latency_p95_ms: sorted(latency_list)[int(len(latency_list) * 0.95)], total_tokens: token_total, }, by_secret_type: { k: calc_metrics(v) for k, v in by_type.items() }, by_context_type: { k: calc_metrics(v) for k, v in by_context.items() }, }这里的map_key需要把true_label和contains_secret映射到tp/fp/tn/fn。例如true_label1且contains_secretTrue时是tp。实际实现要写完整这里略去。分组报告的意义在于A 模型整体 F1 比 B 模型高不代表 A 在每个 secret 类型上都更好。如果 A 在github_token上 Recall 低在aws_access_key上 Precision 低就不能直接上线。4.4 用 GitHub Actions 定时和版本化离线评估不能只在本地跑一次。模型版本、Prompt 模板、数据集都可能变化需要定期重跑。可以使用 GitHub Actions 的定时任务在每周固定时间跑完整评估并上传报告作为 artifact。name: llm-secret-scan-eval on: schedule: - cron: 0 2 * * 1 workflow_dispatch: jobs: evaluate: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Setup Python uses: actions/setup-pythonv5 with: python-version: 3.11 - name: Install dependencies run: pip install requests - name: Run evaluation env: MODEL_API_BASE: ${{ secrets.MODEL_API_BASE }} MODEL_API_KEY: ${{ secrets.MODEL_API_KEY }} MODEL_NAME: ${{ vars.MODEL_NAME }} run: | python evaluate_secret_detection.py \ --dataset datasets/test.jsonl \ --output reports/report.json \ --model $MODEL_NAME - name: Upload report uses: actions/upload-artifactv4 with: name: eval-report path: reports/report.json注意actions/checkoutv4和actions/setup-pythonv5只是示例落地时要以当前可用的 action 版本为准。模型 API Key 应该放在 GitHub Secrets 中不能写进代码库。报告文件建议用日期命名比如report-20250413.json并把它提交到专门的评估记录目录。这样后面可以回看“某个模型在某个数据集版本上的结果”。4.5 A/B 对比候选模型 vs 生产基线每次只跑一个模型会产生“当前模型还不错”的错觉。更稳妥的做法是同时跑生产基线和候选模型使用完全相同的测试集。对比时要看四个变化方向Recall 上升且 Precision 不降可以继续灰度。Recall 下降无论 Precision 多高都不能上线。Recall 不变Precision 大幅上升适合上线收益是减少人工复核。Recall 和 Precision 都下降直接淘汰。A/B 对比脚本可以在评估入口加一个--output-suffix参数把两次运行的报告分开存储再写一个小脚本合并成 delta 报告。5. 离线指标合格只是开始生产灰度还要做影子模式和人工复核5.1 影子模式推理但不告警离线评估指标合格后模型还不能直接参与告警。第一步应该先进入影子模式。影子模式的含义是生产环境的候选片段依然按原来的规则引擎走但 LLM 会对同一片段做一次推理结果只写入日志不产生真实告警。它的价值在于收集真实输入分布下的模型表现同时不影响线上稳定性。影子模式的输出需要保留以下信息候选片段 hash便于回查。规则引擎结果和 LLM 结果。模型名称和版本。Prompt 版本。推理延迟、Token 消耗。最终是否被生产链路采纳。收集一段时间后再对影子日志做抽样标注。因为影子模式没有告警人工复核压力小可以按风险等级抽样重点核对高置信但真实结果相反的情况。5.2 小流量 Canary 与人工复核队列影子模式稳定后可以把模型切到小流量 Canary。这个阶段可以让 LLM 结果参与告警但只对一小部分仓库或事件生效比如先覆盖 1% 的新推送事件。小流量阶段的所有 LLM 命中结果都要进入人工复核队列。没有人工复核的 Canary 没有意义因为只有人工结果才能计算线上 Precision 和 Recall。人工复核队列一般要包含原始代码片段。仓库名称、文件路径、提交信息。LLM 输出的置信度和理由。规则引擎命中的 pattern。复核结论要回填到评估系统成为下一轮数据集的候选正负样本。这一步让评估数据集从静态变成动态持续覆盖线上真实分布。5.3 线上监控指标生产灰测阶段不能只看离线指标还要盯线上运行指标。重点监控对象包括监控项含义告警建议每千次扫描 LLM 命中率模型报告 secret 的比例与基线趋势比较异常上升可能是误报人工复核驳回率复核后被判定为非 secret 的比例超过 30% 时要重点排查P95 推理延迟模型调用耗时超过 2 秒需要降级或扩容超时率模型调用超时比例超过 1% 需要处理调用失败率API 返回错误比例非 0 就要告警Token 消耗每百万 Token 成本和预算对照监控数据要能按仓库、secret 类型、上下文类型下钻。否则只能知道整体指标变差了不知道是哪个环节引起的。5.4 回滚条件灰度不是“上了就完事”要提前定义回滚条件。一旦触发自动或手动把模型从生产链路中摘除切回原规则引擎。需要回滚的情况包括P95 延迟明显超过离线评估结果。高严重级别 secret 的 Recall 下降。人工复核驳回率超预期。模型调用成本超预算 20% 以上。模型输出大量非法 JSON导致链路重试风暴。回滚要能快速执行。如果 LLM 是同步调用的可以通过配置中心开关关闭如果是异步任务要保证任务队列中的存量数据不会继续触发误报。生产环境一定要准备开关即使离线评估做得很充分线上问题仍然可能发生。6. 评估流程中的常见坑、排查顺序和最佳实践清单6.1 常见坑这套流程看起来不复杂但实际执行时很容易踩坑。下面三个坑最常出现。第一个坑是数据集里混入真实密钥。有人觉得“用真实密钥测模型更真实”但真实密钥一旦进入测试集所有样本都会变成敏感数据日志、报告、代码仓库都可能泄露。正确做法是使用合成数据保持格式和上下文相似。第二个坑是只看整体准确率。整体准确率在类别不平衡时没有意义必须按 secret 类型和上下文类型拆分。如果某个类型只有 5 个样本也要看单独的指标不能合并到整体里掩盖问题。第三个坑是忽略模型输出解析失败率。LLM 不保证每次输出都是合法 JSON如果解析失败率是 5%这部分样本在评估和线上都会被跳过结果可能严重偏乐观。评估脚本必须报告解析失败率线上解析失败要进入重试或降级逻辑。坑错误表现正确做法数据污染测试集包含真实密钥全部使用合成假密钥指标单一只看 Accuracy按类型分组看 Recall、Precision、FPR解析失败忽略JSON 解析异常样本被丢弃统计失败率并单独展示数据泄漏同仓库样本跨训练集和测试集按仓库划分数据集只测快乐路径不测试超时和限流压测 P95 延迟和超时率6.2 排查顺序当线上或离线结果异常时建议按固定顺序排查避免先改模型再改数据最后发现是 Prompt 写错了。第一步检查数据。测试集里的 snippet 是否完整上下文是否被截断true_label是否准确。最隐蔽的问题是context_type标错把文档示例标成生产代码会让模型学偏。第二步检查 Prompt。Prompt 是否明确要求输出 JSON是否给了secret_type_hint是否要求模型区分示例和真实凭据。Prompt 变更后即使模型不变也会导致指标变化。第三步检查模型行为。候选模型是否是预期版本temperature 是否设置正确是否因为上下文太长导致关键信息被截断。LLM 的上下文窗口有限把过长的代码片段放进去反而会引入噪声。第四步检查后处理。解析逻辑是否把模型输出错误地映射到了contains_secret失败样本是否被丢弃重试策略是否让部分样本重复计费。最后再检查指标计算。混淆矩阵是否写反Recall 和 Precision 的公式是否用错分组报告的 key 是否覆盖所有样本。6.3 最佳实践清单生产前评估 LLM 用于秘密扫描这里整理一份可复用的检查清单适合在项目启动和每次模型升级时使用。数据集至少覆盖 3 类 secret每类覆盖生产代码、测试代码、文档、配置文件等上下文。所有 secret 样本使用合成假值绝不放真实凭据。数据集按仓库划分禁止同仓库数据同时进入训练集和测试集。指标同时看 Recall、Precision、FPR 和解析失败率不只看 Accuracy。离线评估记录模型版本、Prompt 版本、数据集版本和报告路径。候选模型与生产基线跑同一测试集输出 delta 报告。离线门禁通过后先进影子模式再进小流量 Canary。Canary 阶段所有 LLM 命中结果进入人工复核队列。线上监控 P95 延迟、超时率、调用失败率和人工复核驳回率。定义回滚开关触发条件后能快速摘除模型。定期用线上人工复核结果扩充评估数据集再重新评估。模型升级时先用旧版本生成全量基线报告再跑新版本对比。6.4 下一步可以怎么做这套评估框架不只适用于秘密扫描也可以迁移到其他代码安全场景比如依赖漏洞告警分类、恶意代码检测、许可证风险判断等。核心方法是一致的先构造贴合生产分布的数据集用混淆矩阵指标做门禁再通过影子模式和人工复核回收线上结果。对团队而言建议先从一个候选模型和一个目标 secret 类型开始跑完整流程再逐步扩大。不要一开始就追求覆盖几十种密钥格式。秘密扫描的评估难点不在模型而在数据和流程是否稳定。只有数据可追溯、指标可对比、结果可回滚LLM 才真正具备走入生产环境的条件。