去年在推进一个内部代码安全项目时我们打算用 LLM 自动识别仓库中的敏感信息和泄露密钥。原以为“调用大模型 正则规则”就能直接上线结果在预演阶段就遇到大量误报和漏报有的把普通字符串当成了 GitHub Token有的把真实密钥当成注释忽略掉。后面静下心梳理了一套“生产前评估方案”才发现真正难的不是写 Prompt而是如何系统评估 LLM 在秘密扫描场景下的能力边界。这篇文章就围绕“GitHub 如何在生产前评估 LLM”这一主题结合秘密扫描的实战经验整理一套可落地的评估方案。你会了解为什么需要评估、评估哪些指标、如何构建测试集、怎样用 Python 脚本完成一次完整评测以及生产部署前需要规避的常见坑。无论你是安全工程师、后端开发还是刚接触 LLM 应用的算法同学都能按步骤复现这套流程。1. 背景与核心概念1.1 什么是秘密扫描为什么需要 LLM秘密扫描Secret Scanning通常指对源码、配置文件、日志、云平台对象存储中的敏感凭据进行自动检测。常见的敏感信息包括GitHub Personal Access TokenAWS Access Key ID / Secret Access Key阿里云、腾讯云等云厂商密钥数据库连接串、密码、私钥通用 API Key、Bearer Token传统方案以正则表达式和熵值检测Shannon Entropy为主。例如检测 AWS Key 的格式AKIA[0-9A-Z]{16}或者检测 Base64 字符串的熵值是否超过阈值。这种做法实现简单、可解释性强但缺陷也很明显模式匹配只能识别“已知格式”遇到自定义 Token 或混淆形式容易漏报。正则规则会命中大量示例代码、测试数据误报率高。没有上下文理解能力无法区分“示例占位符”和“真实密钥”。维护成本高需要持续更新规则。LLM 的出现让秘密扫描从“规则匹配”走向“语义理解”。它可以结合上下文判断一个字符串是否像真实密钥、是否处于可执行代码路径中、是否疑似已暴露的公网仓库等。但 LLM 并不是天然适配生产环境它存在幻觉、置信度不稳定、上下文长度限制、成本较高等问题所以上线前必须评估。1.2 生产前评估的核心任务“生产前评估”是指在 LLM 真正介入扫描流程之前用一批带标签的样本数据量化它在准确率、召回率、误报率、时延、成本等方面的表现并基于评估结果决定是否上线、用什么阈值、怎么兜底。这里要区分两个概念功能测试验证 LLM 能不能“大致识别”密钥。生产前评估验证 LLM 是否能在真实场景下稳定工作并给出可量化的质量指标。生产前评估还包含与已有规则引擎的对比测试、多轮阈值调优、失败样本分析等。只有通过这些环节你才有信心把 LLM 从“实验脚本”升级为“生产组件”。1.3 常见应用场景具体到 GitHub 生态LLM 秘密扫描评估常见于以下场景场景说明仓库默认分支扫描对 GitHub 仓库的新提交、历史提交进行秘密扫描发现泄露的凭据Pull Request 扫描在代码审查阶段拦截新增密钥避免敏感信息合入主分支组织级合规检查对组织内部所有仓库做周期扫描满足安全合规要求私有密钥轮换扫描已发生泄露的密钥在其他仓库中的复用情况近实时监控监听 webhook 或事件流对新推送代码进行快速检测在上述场景中LLM 可以作为“第二层检测器”运行在规则引擎之后先由正则初步过滤再由 LLM 做二次确认从而降低误报率并识别规则漏掉的复杂密钥。2. 环境准备与版本说明本文中的示例以 Python 为主需要准备一个可调用 LLM 的环境。你可以使用 GitHub Copilot、OpenAI API、Azure OpenAI、国内大模型平台的 API或者本地部署的模型服务。不同 API 的调用方式略有差异但核心评估流程一致。2.1 运行环境建议操作系统Windows 10/11、Ubuntu 20.04、macOS 均可Python3.9 或以上版本依赖库requests、python-dotenv、pandas可选LLM 接口OpenAI 兼容接口或任何可返回 JSON 的 HTTP 接口代码管理Git 命令行或 GitHub CLI以下命令安装基础依赖pip install requests python-dotenv pandas如果你的环境还没有准备好 Git 仓库样本可以先用一个本地文件夹模拟或者通过 GitHub 官方 API 拉取公开仓库的快照。注意拉取仓库时不要直接下载包含真实密钥的仓库建议使用你自己创建的测试仓库或公开的模拟样例。2.2 评估数据集准备评估数据集是生产前评估的地基。建议构建三类样本真实泄露样本从已公开的泄露报告、安全公告中提取去敏后的密钥片段。模拟泄露样本自己生成的假密钥但格式与真实密钥高度相似。正常代码样本包含 URL、Token 占位符、测试密钥、随机字符串的普通代码。数据集的格式统一为 JSON 行或 CSV至少包含字段类型说明idstr样本唯一 IDcontentstr代码片段或文本内容labelint1 表示包含真实密钥0 表示不包含secret_typestr密钥类型如github_token、aws_keysourcestr样本来源示例数据{id: 1, content: token ghp_123456789012345678901234567890123456, label: 1, secret_type: github_token, source: synthetic} {id: 2, content: print(hello world), label: 0, secret_type: none, source: normal}注意不要把真实密钥直接用于实验。生产前评估所用样本必须经过脱敏或由程序生成避免扩大泄露范围。2.3 LLM 调用配置为了安全密钥通过环境变量注入不写入代码。在项目根目录创建.env文件LLM_API_KEYyour_api_key_here LLM_API_BASEhttps://api.example.com/v1 LLM_MODEL_NAMEyour-model-name然后在 Python 中加载import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(LLM_API_KEY) api_base os.getenv(LLM_API_BASE) model_name os.getenv(LLM_MODEL_NAME)如果你的模型接口不是 OpenAI 兼容格式需要按官方文档修改请求方法。本文的代码示例以 OpenAI 兼容接口为例你只需要调整chat函数部分的 URL 和请求体。3. 秘密扫描评估的核心框架3.1 评估指标生产前评估不能只看“准确率”。在秘密扫描场景里不同指标的代表意义不同指标公式含义关注点精确率PrecisionTP / (TP FP)被判定为密钥的样本中真实密钥的比例越高误报越少召回率RecallTP / (TP FN)真实密钥样本中被正确识别的比例越高漏报越少F1 分数2 * P * R / (P R)精确率与召回率的调和平均综合平衡指标准确率Accuracy(TP TN) / Total所有样本中分类正确的比例样本均衡时才有参考价值误报率FPRFP / (FP TN)正常样本中被误判为密钥的比例越低越好漏报率FNRFN / (TP FN)真实密钥样本中被漏掉的比例越低越好在秘密扫描产品中通常更看重召回率因为漏掉一个真实令牌可能导致严重的数据泄露。但召回率也不能无限制提高否则误报会占满工单系统最终被人工忽略。3.2 评估流程一次完整的评估分为五个阶段样本准备划分训练集可选用于 Prompt 调优和测试集。基线测试先跑正则规则或现有扫描引擎得到基线指标。LLM 推理让 LLM 对测试集每个样本输出是否包含密钥并给出置信度。结果对比汇总 LLM 预测结果与真实标签计算各项指标。失败分析抽取误报和漏报样本分析 Prompt 缺陷、模型知识盲区或样本质量问题。下面是评估流程的简图准备样本 - 运行基线规则 - 调用 LLM 判断 - 汇总指标 - 失败分析 - 调整 Prompt / 阈值 - 再评估3.3 Prompt 设计的评估要点LLM 在秘密扫描任务中的表现高度依赖 Prompt。生产前评估时建议同时评估几类 Prompt 的差异零样本Zero-shot直接要求模型判断文本中是否有密钥。少样本Few-shot给出一两个正负示例后再让模型判断。结构化输出要求模型返回 JSON{is_secret: true/false, type: ..., reason: ...}。角色限定告诉模型“你是代码安全专家只关注敏感信息”。评估时要固定 Prompt 模板不要边测试边频繁修改否则结果不可比。4. 实战构建 LLM 秘密扫描评估脚本下面我们完成一个最小可运行评估脚本。脚本会读取测试数据集调用 LLM 判断每条样本是否包含密钥最后输出精确率、召回率、F1 等指标。4.1 创建项目结构先建一个干净的目录llm-secret-scanner-eval/ ├── .env ├── data/ │ └── test_samples.jsonl ├── eval_secret_scanner.py └── requirements.txtrequirements.txt内容requests2.31.0 python-dotenv1.0.0 pandas2.1.4安装依赖pip install -r requirements.txt4.2 准备测试数据集这里给出一个简单的生成脚本用来构造 10 条样本实际生产评估至少需要几百条# gen_samples.py import json import random samples [] # 模拟 GitHub Token samples.append({id: 1, content: const token ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghij;, label: 1, secret_type: github_token}) samples.append({id: 2, content: token os.environ.get(GITHUB_TOKEN), label: 0, secret_type: none}) # 模拟 AWS Key samples.append({id: 3, content: aws_access_key_id AKIAIOSFODNN7EXAMPLE, label: 1, secret_type: aws_key}) samples.append({id: 4, content: key AKIAIOSFODNN7EXAMPLE # 示例请勿使用, label: 0, secret_type: none}) # 模拟数据库密码 samples.append({id: 5, content: password: Pssw0rd!2024, label: 1, secret_type: database_password}) samples.append({id: 6, content: password_input input(Enter password:), label: 0, secret_type: none}) # 模拟通用 API Key samples.append({id: 7, content: api_key sk-proj-9f8s7d6f5s4d3f2s1d0f, label: 1, secret_type: api_key}) samples.append({id: 8, content: api_key get_api_key_from_vault(), label: 0, secret_type: none}) # 模拟私钥 samples.append({id: 9, content: -----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----, label: 1, secret_type: private_key}) samples.append({id: 10, content: print(begin processing), label: 0, secret_type: none}) with open(data/test_samples.jsonl, w, encodingutf-8) as f: for s in samples: f.write(json.dumps(s, ensure_asciiFalse) \n) print(生成完成共, len(samples), 条样本)运行python gen_samples.py4.3 编写核心评估脚本下面实现eval_secret_scanner.py。该脚本定义了一个scan_with_llm函数负责向 LLM 发送请求同时定义evaluate函数计算指标并输出结果。# eval_secret_scanner.py import json import os import time import requests from dotenv import load_dotenv load_dotenv() # LLM 配置 API_KEY os.getenv(LLM_API_KEY) API_BASE os.getenv(LLM_API_BASE) MODEL_NAME os.getenv(LLM_MODEL_NAME) # Prompt 模板 SYSTEM_PROMPT 你是一个代码安全检测专家。你的任务是从给定的代码片段中识别是否包含真实的敏感信息如 API 密钥、令牌、密码、私钥等。仅检测代码中硬编码的敏感凭据不检测环境变量引用、函数调用或明显的示例占位符。 请以 JSON 格式返回结果 { is_secret: true 或 false, secret_type: 密钥类型如果 is_secret 为 false 则为 null, confidence: 0 到 1 之间的数字 reason: 简要说明判断依据 } def call_llm(content: str) - dict: 调用 LLM 接口返回解析后的 JSON 结果。 这里使用 OpenAI 兼容接口请根据你的模型调整 URL 和请求体。 url f{API_BASE}/chat/completions headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } payload { model: MODEL_NAME, messages: [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: content} ], temperature: 0.1, max_tokens: 200 } try: resp requests.post(url, headersheaders, jsonpayload, timeout30) resp.raise_for_status() data resp.json() text data[choices][0][message][content].strip() # 提取 JSON 部分 if text.startswith(): text text.strip() if text.startswith(json): text text[4:] return json.loads(text) except Exception as e: print(fLLM 调用失败: {e}) # 失败时保守返回认为没有密钥避免误报 return {is_secret: False, secret_type: None, confidence: 0.0, reason: f调用异常: {e}} def scan_with_llm(content: str, threshold: float 0.5) - int: 返回 1 表示判定为密钥0 表示未判定为密钥。 threshold 是置信度阈值只有 is_secret 为 true 且 confidence 不低于阈值才算命中。 result call_llm(content) if result.get(is_secret) and result.get(confidence, 0) threshold: return 1 return 0 def evaluate(test_file: str, threshold: float 0.5): 读取测试集执行评估并输出指标。 y_true [] y_pred [] details [] with open(test_file, r, encodingutf-8) as f: for line in f: line line.strip() if not line: continue sample json.loads(line) label sample[label] content sample[content] pred scan_with_llm(content, threshold) y_true.append(label) y_pred.append(pred) details.append({ id: sample[id], label: label, pred: pred, content: content[:50] }) time.sleep(0.5) # 避免触发速率限制生产评估可去掉 # 计算指标 tp sum(1 for t, p in zip(y_true, y_pred) if t 1 and p 1) fp sum(1 for t, p in zip(y_true, y_pred) if t 0 and p 1) fn sum(1 for t, p in zip(y_true, y_pred) if t 1 and p 0) tn sum(1 for t, p in zip(y_true, y_pred) if t 0 and p 0) precision tp / (tp fp) if (tp fp) 0 else 0 recall tp / (tp fn) if (tp fn) 0 else 0 f1 2 * precision * recall / (precision recall) if (precision recall) 0 else 0 accuracy (tp tn) / len(y_true) if y_true else 0 fpr fp / (fp tn) if (fp tn) 0 else 0 print(f测试样本数: {len(y_true)}) print(fTP{tp}, FP{fp}, FN{fn}, TN{tn}) print(f精确率 Precision: {precision:.4f}) print(f召回率 Recall: {recall:.4f}) print(fF1 分数: {f1:.4f}) print(f准确率 Accuracy: {accuracy:.4f}) print(f误报率 FPR: {fpr:.4f}) # 输出失败样本 print(\n失败样本分析) for d in details: if d[label] ! d[pred]: print(f ID: {d[id]}, 真实label: {d[label]}, 预测: {d[pred]}, 内容: {d[content]}) return { tp: tp, fp: fp, fn: fn, tn: tn, precision: precision, recall: recall, f1: f1, accuracy: accuracy, fpr: fpr } if __name__ __main__: evaluate(data/test_samples.jsonl, threshold0.5)4.4 运行与验证确保.env文件已正确配置然后运行python eval_secret_scanner.py预期输出示例测试样本数: 10 TP4, FP1, FN1, TN4 精确率 Precision: 0.8000 召回率 Recall: 0.8000 F1 分数: 0.8000 准确率 Accuracy: 0.8000 误报率 FPR: 0.2000 失败样本分析 ID: 4, 真实label: 0, 预测: 1, 内容: key AKIAIOSFODNN7EXAMPLE # 示例请勿使用 ID: 7, 真实label: 1, 预测: 0, 内容: api_key sk-proj-9f8s7d6f5s4d3f2s1d0f实际结果取决于你的模型和 Prompt。上述输出仅作为格式参考。4.5 结果分析与阈值调优从失败样本中可以看到两个典型问题示例 AWS Key 被误报为真实密钥。模型缺少对“注释说明这是示例”的上下文理解或者 Prompt 对“示例占位符”的界定不够清晰。一种 OpenAI 风格的 Key 被漏报。模型可能没认出新格式的sk-proj-前缀也可能是置信度不够。这时候可以尝试调整两个方向修改 Prompt在系统提示中明确写明“如果字符串被注释为示例、测试、demo则不是真实密钥”。调整置信度阈值把阈值从 0.5 降到 0.3可能会召回更全但误报也会增加。为了找到最优阈值可以在测试集上遍历不同阈值画出 Precision-Recall 曲线。# threshold_tuning.py import json from eval_secret_scanner import scan_with_llm # 加载样本 samples [] with open(data/test_samples.jsonl, r, encodingutf-8) as f: for line in f: if line.strip(): samples.append(json.loads(line)) # 先获取每个样本的置信度简化处理真实环境建议缓存结果 results [] for s in samples: # 为了演示直接调用一次并拿到置信度 from eval_secret_scanner import call_llm r call_llm(s[content]) results.append({label: s[label], is_secret: r.get(is_secret), confidence: r.get(confidence, 0)}) # 遍历阈值 for threshold in [0.3, 0.4, 0.5, 0.6, 0.7, 0.8]: tp fp fn tn 0 for r in results: pred 1 if r[is_secret] and r[confidence] threshold else 0 if r[label] 1 and pred 1: tp 1 elif r[label] 0 and pred 1: fp 1 elif r[label] 1 and pred 0: fn 1 else: tn 1 precision tp / (tp fp) if tp fp else 0 recall tp / (tp fn) if tp fn else 0 f1 2 * precision * recall / (precision recall) if precision recall else 0 print(fthreshold{threshold:.1f} precision{precision:.2f} recall{recall:.2f} f1{f1:.2f})这段脚本演示了如何通过遍历阈值找到最佳平衡点。在实际项目中应该把 LLM 推理结果缓存下来避免重复调用浪费时间和成本。5. 常见问题与排查思路在实际评估过程中大家经常会遇到以下几类问题。5.1 LLM 接口报错或返回空值问题现象常见原因解决思路requests.exceptions.ConnectionError网络不通或 API Base 配置错误检查.env中的 API_BASE 是否可访问网络策略是否允许返回内容不是 JSON模型输出格式不稳定在 Prompt 中强制要求 JSON并使用response_format参数如果模型支持rate limit exceeded调用频率过高增加time.sleep或使用官方 SDK 的重试机制context length exceeded单条样本太长截断代码片段或按行拆分处理5.2 评估指标不合理如果精确率和召回率都很低不要急着调 Prompt先检查数据集质量。标签是否准确比如把注释中的示例当成真实密钥会导致模型无论如何都会误报。样本是否覆盖多种密钥类型如果测试集只有一种密钥结论不具备代表性。真实样本与模拟样本比例是否均衡建议真实泄露样本占 20%-30%其余为合成和正常代码。5.3 误报集中在某个特定模式比如模型会对长字符串变量名误判。可以在失败分析后在 Prompt 中增加负样本示例或对疑似字符串做熵值预过滤。5.4 LLM 调用成本太高如果测试集很大每次评估都调 API 会花不少钱。可以这样做先用规则引擎粗筛只让 LLM 处理规则命中的候选样本。在本地用小参数量模型先跑一遍收集失败样本再调用更强模型复核。开启结果缓存避免对同一份样本反复调用。6. 最佳实践与工程建议6.1 评估数据管理不要把评估数据直接放在公开仓库里。建议使用内部版本管理或 OSS 存储权限最小化。对真实泄露样本做脱敏替换掉能还原真实凭据的字符串。记录每个样本的来源和生成方式方便追溯。6.2 Prompt 版本化管理Prompt 也会“更新迭代”建议像管理代码一样管理 Prompt 版本。保存每个版本的评估指标方便对比哪个 Prompt 更适合生产。# prompt_version.yaml version: 1.2 date: 2025-06-01 changes: - 增加对 sk-proj 前缀的识别 - 强化示例密钥判断逻辑 eval_f1: 0.87 eval_recall: 0.926.3 双阶段扫描架构生产环境不要只依赖 LLM。建议采用“规则引擎 LLM 复核”的架构第一层正则、熵值、GitHub 官方 Secret Scanning 规则高召回、低精度。第二层LLM 对第一层命中的候选结果做二次判断降低误报。第三层人工或定时任务抽样复核持续优化。这种架构可以在保证召回的同时控制误报率同时减少 LLM 调用量降低成本。6.4 日志与告警LLM 判断结果应该记录以下字段样本 ID、仓库地址、文件路径、提交 SHA模型名称、Prompt 版本输出置信度、secret_type、reason最终处置状态确认、忽略、待人工不要只记录一个布尔值否则后续排查和复盘会非常困难。6.5 安全与合规调用云端 LLM 时禁止把未经脱敏的真实验证数据直接发送给外部 API。必须确认数据是否允许出域。是否有数据保留策略。是否使用私有化部署模型。否则一旦发生二次泄露就是严重事故。7. 总结与学习路线本文从秘密扫描业务背景出发解释了为什么要在生产前评估 LLM给出了评估指标、评估流程、Prompt 设计要点并提供了一份可运行的 Python 评估脚本。你可以把这份脚本应用到自己团队的代码安全流程中也可以根据本文章节中的阈值调优方法找到适合你业务场景的置信度阈值。接下来如果你要继续深入建议按以下顺序学习掌握现有规则引擎的能力边界例如 GitHub Advanced Security 的 secret scanning 规则。学习更多 LLM 结构化输出方法比如 function calling、JSON mode减少解析异常。尝试用更多真实场景样本扩充测试集比如不同编程语言、不同密钥格式。探索语义嵌入 分类模型的方式用一个小模型先过滤简单样本把 LLM 留给复杂样本。生产安全无小事。LLM 能提高秘密扫描的上限但也会带来新的不确定性和成本。请务必在充分评估后再推上线并始终保留人工审核和灰度回滚的通道。如果你在评估过程中遇到其他问题欢迎在评论区交流也可以收藏这篇文章作为日常参考。