Local Deep ResearchLDRSemgrep 自定义安全规则完全指南从 12 类漏洞检测到 SSRF 防护的源码级剖析【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research本指南以仓库 .semgrep/rules/README.md 为核心系统讲解 Local Deep ResearchLDR项目为自身代码库定制的 Semgrep 安全规则集覆盖硬编码密钥、SQL/命令/代码注入、路径穿越、反序列化、SSRF、XSS、CSRF 等 12 类漏洞并结合 .semgrep/rules/ldr-security.yaml、.semgrep/rules/check-safe-requests.yaml 两个规则文件的真实内容以及 src/local_deep_research/security/safe_requests.py 的安全请求封装实现与 .github/workflows/semgrep.yml 的 CI/CD 集成深入讲解每条规则的检测原理、适用场景、本地运行方法与扩展方式。读完本文你将掌握如何在本仓库内运行、验证、扩展这套 LDR 专属安全规则并理解规则如何与项目源码中的 SSRF 防护层相互印证。LDRLocal Deep Research是一个支持本地与云端 LLM、聚合 arXiv/PubMed 等 10 搜索引擎的深度研究工具。由于它天然需要发起大量外部 HTTP 请求、处理用户提供的文档与搜索词、并可能暴露 Web 端点其安全面覆盖了经典的注入类漏洞与 LLM 应用特有的 SSRF服务端请求伪造风险。.semgrep/rules/目录下的自定义规则正是为这道安全面量身定制的门禁。一、为什么 LDR 需要一套自定义 Semgrep 规则Semgrep 是静态分析工具通过 YAML 规则文件定义代码模式无需执行代码即可扫描语法树。官方规则库如p/security-audit覆盖面广但存在两个问题一是规则过于通用无法体现 LDR 的架构约定例如必须走safe_requests封装而非直接调用requests二是官方规则缺少对项目特有 API如 SQLAlchemy 的session.execute、Flask 的render_template_string的精准约束。LDR 的解决方案是双轨并行这一点可从 .github/workflows/semgrep.yml 看出通用规则运行p/security-audit与p/secrets两个官方规则包项目自定义规则运行--config.semgrep/rules/指向本目录。自定义规则与通用规则互补官方包负责广撒网自定义规则负责精准打击——把 LDR 开发者约定的安全编码规范禁用os.system、禁用yaml.load、禁用直接requests.get、必须参数化 SQL 等固化成可自动执行的规则。二、规则全景ldr-security.yaml 的 12 类漏洞检测.semgrep/rules/ldr-security.yaml 是核心规则文件。README 中列出了 12 类规则而实际文件内实现了16 条规则README 之外还包含 SQL 字符串格式化执行、SSL 校验关闭、危险文件权限 3 类额外检测以及独立的 SSRF URL 抓取提醒。下表按 README 分类整理并标注实际 severity 与 CWE 映射规则 ID检测目标SeverityCWEOWASP 2021hardcoded-secret-detection硬编码 API Key/密码/TokenERRORCWE-798A07 身份认证失效sql-string-concatenationSQL 字符串拼接注入ERRORCWE-89A03 注入sql-execute-with-string-formatsession.execute(f...)等格式化执行ERRORCWE-89A03 注入dangerous-eval-usageeval/exec/compile动态执行ERRORCWE-95A03 注入os-system-command-injectionos.system与shellTrueERRORCWE-78A03 注入path-traversal-risk用户输入拼入文件路径WARNINGCWE-22A01 失效访问控制unsafe-yaml-loadyaml.load反序列化ERRORCWE-502A08 软件与数据完整性失效unsafe-pickle-loadpickle.load(s)/cPickle.loadERRORCWE-502A08 软件与数据完整性失效weak-random-generationrandom模块用于安全场景WARNINGCWE-338A02 加密失败flask-debug-mode-enabledFlaskdebugTrueERRORCWE-489A05 安全配置错误insecure-ssl-verification-disabledverifyFalse关闭证书校验ERRORCWE-295A02 加密失败dangerous-file-permissionschmod 0o777/0o666WARNINGCWE-732A01 失效访问控制ldr-url-fetching-ssrfrequests.get/post、urlopen抓取 URLWARNINGCWE-918A10 SSRFldr-user-input-in-html用户输入进入 HTML 上下文WARNINGCWE-79A03 注入ldr-missing-csrf-protectionPOST 端点缺少 CSRF 提醒INFOCWE-352A01 失效访问控制ldr-password-in-logs密码写入日志/printERRORCWE-532A09 安全日志与监控失败三、逐类规则深度解析模式、原理与修复建议3.1 硬编码密钥检测CWE-798ERROR规则hardcoded-secret-detection使用pattern-either匹配四种赋值形态- pattern: $VAR sk-... - pattern: $VAR sk-... - pattern: password ... - pattern: api_key ... - pattern: secret ... - pattern: token ...其中sk-...模式专门针对 OpenAI 风格的 API Key 前缀LDR 支持 OpenAI 兼容的本地/云端模型这类密钥形态在项目中高度相关。触发后规则要求改用环境变量或安全配置存储凭据。这与项目中 .github/workflows/gitleaks.yml 等密钥泄露防线形成互补Semgrep 在代码库内查写死的密钥Gitleaks 在 git 历史中查已泄露的密钥。3.2 SQL 注入防护CWE-89ERRORLDR 的存储层基于 SQLAlchemy因此规则聚焦 SQLAlchemy 的注入面。sql-string-concatenation匹配三类字符串拼 SQL 的写法- pattern: | $QUERY ... $USER_INPUT ... - pattern: | $QUERY f...{$USER_INPUT}... - pattern: | $QUERY ... % ($USER_INPUT)sql-execute-with-string-format更进一步直接拦截执行层的危险调用- pattern: $SESSION.execute(f...) - pattern: $SESSION.execute(... ...) - pattern: $ENGINE.execute(f...)规则消息明确要求使用 SQLAlchemy 的参数化写法text()with parameters。两条规则双保险无论拼接发生在查询构造阶段还是执行阶段都会被捕获。3.3 代码注入与命令注入CWE-95 / CWE-78ERRORdangerous-eval-usage匹配eval($X)、exec($X)、compile($X, ...)三个动态执行入口防止任意代码执行。os-system-command-injection则覆盖 Python 中最常见的命令注入面- pattern: os.system($CMD) - pattern: subprocess.call($CMD, shellTrue) - pattern: subprocess.Popen($CMD, shellTrue) - pattern: subprocess.run($CMD, shellTrue)修复方向是改用subprocess的参数列表形式subprocess.run([ls, -l], ...)避免 shell 解释用户输入。对于 LDR 这类需要调用本地工具链如向量化、PDF 解析的项目这类规则能有效阻止命令拼接反模式混入代码库。3.4 路径穿越CWE-22WARNINGpath-traversal-risk匹配四类将用户输入拼入文件路径的写法- pattern: open($PATH $USER_INPUT, ...) - pattern: open(f{$PATH}/{$USER_INPUT}, ...) - pattern: Path($USER_INPUT) - pattern: os.path.join($PATH, $USER_INPUT)注意此类规则设为 WARNING 而非 ERROR因为部分场景如用户明确指定输出路径属于合理使用仅需提示开发者校验与净化。这与仓库中 src/local_deep_research/security/path_validator.py、src/local_deep_research/security/filename_sanitizer.py 等运行时校验模块形成呼应静态规则负责提醒运行时模块负责拦截。3.5 不安全反序列化CWE-502ERROR两条规则分别针对 YAML 与 pickle- id: unsafe-yaml-load pattern: yaml.load($X, ...) - id: unsafe-pickle-load pattern-either: - pattern: pickle.load($X) - pattern: pickle.loads($X) - pattern: cPickle.load($X)yaml.load在旧版本 PyYAML 中可执行任意对象构造pickle系列更是公认的任意代码执行入口。规则强制改用yaml.safe_load()pickle 则建议替换为 JSON 等安全格式。3.6 弱随机数CWE-338WARNINGweak-random-generation匹配random.random()、random.randint(...)、random.choice(...)提示安全敏感操作Token 生成、会话 ID 等必须使用secrets模块。LDR 作为涉及用户会话与 API 凭据的应用这一约束能防止开发者顺手用random生成可预测的凭据。3.7 生产环境调试模式CWE-489ERROR- pattern: app.run(debugTrue) - pattern: app.config[DEBUG] TrueFlask 调试模式会暴露 Werkzeug 调试器可远程执行代码与敏感堆栈信息属于信息泄露风险规则以 ERROR 级别硬性禁止。3.8 SSRF 提醒CWE-918WARNINGldr-url-fetching-ssrf匹配requests.get($URL)、requests.post($URL)、urllib.request.urlopen($URL)提醒开发者校验 URL 防止对内网资源的 SSRF 攻击。这条 WARNING 规则是 LDR 安全体系中最有特色的部分——项目不仅有静态提醒还有配套的强制规则与运行时实现详见第四节。3.9 XSS 与 CSRFCWE-79 / CWE-352ldr-user-input-in-html匹配两类把用户输入注入 HTML 上下文的写法- pattern: | render_template_string($TEMPLATE, user_input$INPUT) - pattern: | fhtml...{$USER_INPUT}.../html要求使用 Jinja2 自动转义。ldr-missing-csrf-protection则以 INFO 级别提醒 POST 端点模式为app.route($PATH, methods[POST])的函数体必须启用 CSRF 保护——INFO 级别说明它属于开发提醒而非阻断错误避免误报干扰正常开发流程。3.10 凭据日志泄露CWE-532ERROR- pattern: logger.info(..., password...) - pattern: logger.debug(..., password...) - pattern: logger.error(..., password...) - pattern: print(..., password...)禁止将密码写入任何日志级别或标准输出。LDR 项目在运行时侧还提供了 src/local_deep_research/security/log_sanitizer.py 与 src/local_deep_research/security/secure_logging.py 作为纵深防御——即使开发者在日志调用中意外传入敏感参数运行时也会在落盘前净化。四、SSRF 防护的完整闭环强制规则 运行时实现4.1 check-safe-requests.yaml把必须走封装变成 ERROR.semgrep/rules/check-safe-requests.yaml 是第二份规则文件包含 6 条规则全部针对SSRF 防护的架构强制——禁止绕过安全封装直接调用requests库规则 ID匹配模式要求unsafe-requests-getrequests.get(...)改用safe_get()unsafe-requests-postrequests.post(...)改用safe_post()unsafe-requests-sessionrequests.Session()改用SafeSession()unsafe-requests-putrequests.put(...)改用SafeSession()unsafe-requests-deleterequests.delete(...)改用SafeSession()unsafe-requests-patchrequests.patch(...)改用SafeSession()这 6 条规则的 severity 全部为 ERROR且通过paths.exclude精准放行例外区域paths: exclude: - **/security/safe_requests.py # 封装自身 - **/tests/** # 测试用例 - **/*_test.py - **/test_*.py - **/examples/** # 示例代码规则消息直接给出修复指引from ...security import safe_get访问 localhost 服务时用safe_get(url, allow_localhostTrue)。这意味着 LDR 代码库中任何新增的、未经过 SSRF 校验的 HTTP 调用都会在 CI 阶段被 ERROR 拦截——把安全架构约定从文档建议升级为硬性门禁。4.2 运行时实现safe_requests.py 的六重防护被规则强制使用的封装位于 src/local_deep_research/security/safe_requests.py提供safe_getL202、safe_postL353、SafeSessionL512、safe_get_with_retriesL699四个入口。其防护机制可拆解为六层URL 预校验每次请求前调用ssrf_validator.validate_url()拒绝命中内网/元数据地址的 URL校验逻辑在 src/local_deep_research/security/ssrf_validator.py。allow_localhost与allow_private_ips参数用于放行可信的自托管服务如 SearXNG、Ollama但云端元数据端点AWS/Azure/OCI 等始终被封锁。DNS 固定DNS Pinning通过dns_pinning.pinned_request()将解析并校验过的 IP固定为实际连接地址src/local_deep_research/security/dns_pinning.py堵住解析-连接间隙中的 DNS 重绑定攻击TOCTOU。逐跳重定向校验safe_get/safe_post关闭requests原生重定向手动跟随每个 301/302/303/307/308 跳转对每个目标 URL 重新执行 SSRF 校验最多跟随_MAX_REDIRECTS 10次L31-L34。凭据隔离_headers_for_redirect()与SafeSession.rebuild_auth()在跳转离开凭据作用域时剥离authorization、cookie以及*key/*token/*secret后缀的请求头防止 API Key 泄露给重定向目标L168-L199、L567-L585。响应大小护栏MAX_RESPONSE_SIZE 1GBL28_check_response_size()校验Content-Length缺失或可疑时安装有界读取器body guard防止内存耗尽L95-L148。超时与重试默认DEFAULT_TIMEOUT 30秒L23safe_get_with_retries对连接错误、超时、429/5xx 状态码执行指数退避重试_RETRY_BACKOFF_SECONDS (1, 2, 4)并解析Retry-After头上限 300 秒L662-L696。上述行为在 tests/security/test_check_response_size.py 等测试中得到验证例如SafeSession.send()的中间重定向分支测试形成规则强制使用封装 → 封装实现防护 → 测试验证防护的完整闭环。五、本地运行与 CI/CD 集成5.1 本地命令行使用README 给出的两条核心命令第一条仅运行 LDR 自定义规则第二条叠加官方审计规则包# 仅运行 LDR 自定义规则扫描 src/ 目录 semgrep --config.semgrep/rules/ src/ # 官方安全审计规则 LDR 自定义规则 semgrep --configp/security-audit --config.semgrep/rules/ src/可结合 severity 过滤如--severityWARNING或输出 JSON--json用于脚本消费。注意p/security-audit与p/secrets需要网络访问 Semgrep Registry 下载规则包。5.2 CI/CD 工作流semgrep.yml 的完整流程规则由 .github/workflows/semgrep.yml 驱动的 Semgrep 扫描工作流自动执行该工作流可被 release-gate.yml 等发布门禁调用workflow_call。关键设计扫描分两阶段第一阶段运行p/security-auditp/secrets--severityINFO全量收集第二阶段运行.semgrep/rules/自定义规则各产出独立 JSON崩溃检测扫描命令以|| true兜底随后检查 JSON 文件是否生成——若 Semgrep 崩溃未产出文件则输出::error::并失败退出避免静默跳过扫描结果合并与 SARIF 转换Python 脚本合并两个 JSON 为semgrep-combined-results.json再转换为 SARIF 2.1.0 格式上报 GitHub Security 标签页通过github/codeql-action/upload-sarif上传category: semgrep-security。工作流注释特别强调绝不能伪造空的 SARIF 文件否则会把所有已修复的历史告警误标为已修复L177-L182门槛汇总在 GitHub Actions Summary 中统计 ERROR/WARNING/INFO 数量ERROR 或 WARNING 大于 0 时标注需要处理。环境中还需注意 Python 3.12 的兼容细节工作流固定setuptools8282.0 移除了pkg_resources并固定semgrep1.87.0L35-L40。六、扩展规则新增规则三步走与模板README 给出了向.semgrep/rules/添加新规则的流程结合本仓库实践可细化为创建规则文件在.semgrep/rules/下新建 YAML 文件如my-rule.yaml参考 .semgrep/rules/ldr-security.yaml 的既有写法pattern-either、metadata、paths.exclude等本地验证semgrep --config.semgrep/rules/your-rule.yaml src/单独测试该规则确认命中率与误报率必要时用--validate校验规则语法文档同步在 .semgrep/rules/README.md 的规则清单中登记新规则ID、检测目标、Severity、CWE。项目规定的规则模板如下含 metadata 规范rules: - id: your-rule-id pattern: | # Your pattern here message: Description of the security issue languages: [python] severity: ERROR # or WARNING, INFO metadata: category: security cwe: CWE-XXX: Description owasp: AXX:2021 - Category实践要点metadata中的cwe与owasp字段会被 CI 工作流的 SARIF 转换读取.github/workflows/semgrep.yml直接影响 Security 标签页的告警信息完整性多模式规则优先使用pattern-either参见 ldr-security.yaml 中hardcoded-secret-detection的写法需要排除测试或封装自身时用paths.exclude精确放行参见 check-safe-requests.yaml。七、参考与延伸本仓库相关文件索引规则文档.semgrep/rules/README.md通用安全规则集.semgrep/rules/ldr-security.yamlSSRF 强制规则集.semgrep/rules/check-safe-requests.yamlSSRF 运行时封装src/local_deep_research/security/safe_requests.pyURL 校验器src/local_deep_research/security/ssrf_validator.pyDNS 固定实现src/local_deep_research/security/dns_pinning.py运行时日志净化src/local_deep_research/security/log_sanitizer.pyCI/CD 集成.github/workflows/semgrep.yml安全封装测试tests/security/test_check_response_size.py规则所映射的行业标准OWASP Top 10 2021、CWE Top 25、Semgrep 官方 Registry 规则包均可在公开标准文档中查阅本仓库通过metadata.cwe与metadata.owasp字段在每条规则上建立了到这两套标准的追踪链这也是静态分析结果可审计、可整改、可追溯的关键。【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考