Dillinger 安全审计清单实战：基于 OWASP Top 10 的 Web 应用与 API 巡检指南

• 前端
• 开发工具

本指南以开源仓库 vulnerability-scanner 技能 中提供的安全审计清单（Security Checklists）为核心骨架，逐条讲解 OWASP Top 10、认证、API、数据保护、安全响应头与快速审计命令的落地方式，并结合 Dillinger 仓库（gh_mirrors/di/dillinger）的真实源码印证每类检查项的实践形态。读完本文，你将得到一份可直接复制进安全报告或 PLAN.md 的可执行检查单，并掌握如何在真实 Next.js 全栈项目中验证访问控制、密钥管理、API 鉴权与配置加固。

清单文档定位：审计的“待办事项表”

checklists.md 是整个 vulnerability-scanner 技能体系中的速查层，与 SKILL.md 的原则层、scripts/security_scan.py 的自动化验证层形成三层配合：

• SKILL.md：提供安全专家思维、OWASP 2025 风险分类、供应链安全、攻击面测绘、风险优先级判定等“方法论”；
• checklists.md：把方法论压缩成可勾选的“待办事项”，供审计者在代码审查、发布前巡检、威胁建模时逐项核对；
• security_scan.py：用python security_scan.py <project_path>自动执行依赖、密钥、危险模式、配置四类扫描，输出 JSON 审计报告，用于验证清单中的检查项是否真正落实。

文档末尾明确指出其用法：将相关清单复制进你的 PLAN.md 或安全报告中（> Usage: Copy relevant checklists into your PLAN.md or security report.）。因此本文按同样顺序展开，并在每一节补充 Dillinger 仓库中的对应实现证据。

OWASP Top 10 审计清单

A01：访问控制失效（Broken Access Control）

• 所有受保护路由均做授权校验（Authorization on all protected routes）
• 默认拒绝策略（Deny by default）
• 已实现速率限制（Rate limiting implemented）
• CORS 配置正确（CORS properly configured）

在 Dillinger 中，“受保护路由授权”的典型实现是 API 层统一鉴权中间件：lib/api-auth.ts 中的validateApiKey(request)会先检查服务端是否配置了DILLINGER_API_KEY环境变量（未配置返回503），再校验请求头中的Authorization: Bearer <api-key>（缺失返回401，不匹配返回403）。这一函数被 app/api/v1/convert/route.ts、app/api/v1/render/route.ts、app/api/v1/export/html/route.ts、app/api/v1/export/pdf/route.ts、app/api/v1/webhooks/route.ts等所有 v1 接口统一调用，属于“默认拒绝、显式放行”的写法。而 OAuth 类回调路由（如app/api/github/callback/route.ts、app/api/dropbox/callback/route.ts、app/api/google-drive/oauth/route.ts等）则依赖各自云服务的授权码交换流程，属于另一套以服务端凭证为信任锚点的鉴权模型。

A02：加密失败（Cryptographic Failures）

• 密码使用 bcrypt/argon2 哈希，成本因子 ≥ 12（Passwords hashed, cost 12+）
• 敏感数据静态加密（Sensitive data encrypted at rest）
• 所有连接启用 TLS 1.2+（TLS 1.2+ for all connections）
• 代码与日志中无密钥泄露（No secrets in code/logs）

从源码结构看，Dillinger 本身不维护用户密码体系，其身份认证全部委托给第三方 OAuth（GitHub、Dropbox、Google Drive、OneDrive、Bitbucket 等），因此“密码哈希成本因子”主要适用于自建账号体系的场景；而“密钥不进代码”在本仓库中是硬性约束——所有云服务凭证均通过环境变量注入（参见 lib/env.ts 对NEXT_PUBLIC_APP_URL/NEXT_PUBLIC_BASE_URL的读取模式以及lib/api-auth.ts中对DILLINGER_API_KEY的读取）。审计时可用下方“快速审计命令”中的密钥扫描正则，确认api_key、token、password、AKIA...等模式未出现在源码或提交记录中。

A03：注入（Injection）

• 参数化查询（Parameterized queries）
• 对所有用户输入做校验（Input validation on all user data）
• 输出编码防 XSS（Output encoding for XSS）
• 无 eval() 或动态代码执行（No eval() or dynamic code execution）

仓库证据：app/api/v1/convert/route.ts在接收 HTML 输入时做了严格校验——typeof html !== "string" || !html.trim()时直接返回400，随后才交给 Turndown 服务转换，体现了“先校验、后处理”的输入验证模式。输出侧，lib/document.ts的sanitizeDownloadFilename（lib/document.ts）将导出文件名中所有非a-zA-Z0-9._-字符替换为下划线，防止文件名注入/路径穿越；lib/export.ts在生成下载文件名时同样先经过该函数清洗，再拼接扩展名。前端渲染 Markdown 预览的MarkdownPreview组件与编辑器侧需要特别注意dangerouslySetInnerHTML类用法，这是 A03 输出编码检查在 React/Next.js 项目中的重点关注点。

A04：不安全设计（Insecure Design）

• 已完成威胁建模（Threat modeling done）
• 已定义安全需求（Security requirements defined）
• 业务逻辑已校验（Business logic validated）

威胁建模的四个标准提问（资产是什么、谁会攻击、如何攻击、影响多大）正是 SKILL.md 中“Security Expert Mindset”一节的要求，也是安全审计员 agent（security-auditor.md）每次审查前的固定动作。对 Dillinger 而言，业务逻辑校验的典型场景包括：文档导入导出的扩展名/内容一致性、OAuth 回调状态参数防 CSRF、API 请求体字段类型校验等。

A05：安全配置错误（Security Misconfiguration）

• 禁用不必要功能（Unnecessary features disabled）
• 错误信息已净化（Error messages sanitized）
• 已配置安全响应头（Security headers configured）
• 默认凭据已更改（Default credentials changed）

security_scan.py的scan_configuration()会自动检查"DEBUG": true、debug = True、NODE_ENV=development、CORS_ALLOW_ALL=true、Access-Control-Allow-Origin: *以及allowCredentials + origin: *的危险组合；同时检测是否存在next.config.js/next.config.mjs/middleware.ts/nginx.conf中的安全响应头配置（缺失会给出 medium 级“No security headers configuration found”建议）。Dillinger 的 next.config.mjs 目前仅包含包导入优化与服务端组件外部包声明，未配置响应头——若直接部署生产环境，应结合下文“安全响应头”一节补充 CSP/HSTS 等配置。

A06：易受攻击和过时的组件（Vulnerable and Outdated Components）

• 依赖保持最新（Dependencies up to date）
• 无已知漏洞（No known vulnerabilities）
• 移除未使用依赖（Unused dependencies removed）

对应security_scan.py的scan_dependencies()：它先检查 npm/yarn/pnpm/pip 的锁文件是否存在（缺失判为 high 级“Missing Lock File，供应链完整性风险”），再在存在package.json时执行npm audit --json，按 critical/high/moderate/low 统计漏洞并设置总体状态。Dillinger 仓库根目录同时存在 package.json 与 package-lock.json，锁文件已提交，满足“锁文件完整性”要求；定期运行npm audit即为该项清单的落地动作。

A07：身份认证失效（Identification and Authentication Failures）

• 提供 MFA（MFA available）
• 登出时会话失效（Session invalidation on logout）
• 已实现会话超时（Session timeout implemented）
• 暴力破解防护（Brute force protection）

Dillinger 的认证全部走 OAuth 第三方身份提供商（GitHub、Dropbox、Google Drive、OneDrive、Bitbucket 的 oauth/callback/unlink 路由），MFA 与暴力破解防护天然由 IdP 承担；仓库侧需要审计的是：令牌只保存在服务端/内存态、回调状态参数校验、unlink路由能正确清除本地会话与令牌。

A08：软件与数据完整性失效（Software and Data Integrity Failures）

• 依赖完整性已验证（Dependency integrity verified）
• CI/CD 流水线已加固（CI/CD pipeline secured）
• 更新机制已加固（Update mechanism secured）

锁文件（package-lock.json）提交、npm audit定期执行、构建产物签名与发布管道权限控制是 A08 的常见落地项；SKILL.md 的供应链安全章节还强调“验证包完整性（校验和）、锁定版本、关键依赖使用私有源、签名并验证构件”。

A09：日志与告警失效（Security Logging and Monitoring Failures）

• 安全事件已记录（Security events logged）
• 日志已受保护（Logs protected）
• 日志中无敏感数据（No sensitive data in logs）
• 已配置告警（Alerting configured）

注意security_scan.py的密钥扫描会覆盖.env*等配置文件（CONFIG_EXTENSIONS包含.env、.env.local、.env.development），这正是“日志/配置中不得出现明文密钥”的反向验证：一旦密钥模式出现在可被读取的文件中即判为 critical/high。审计时同样要检查生产日志输出是否过滤了 Authorization 头与回调参数。

A10：服务端请求伪造 SSRF（Server-Side Request Forgery）

• 已实现 URL 校验（URL validation implemented）
• 外部调用使用白名单（Allow-list for external calls）
• 已做网络分段（Network segmentation）

Dillinger 中的 SSRF 关注点集中在 PDF 导出（vercel.json 中app/api/export/pdf/route.ts依赖@sparticuz/chromium无头浏览器渲染）以及图片上传（app/api/upload/image/route.ts）等“服务器主动发起请求/渲染外部内容”的功能点，需确认目标 URL 校验与协议白名单。

认证清单（Authentication Checklist）

• 强密码策略（Strong password policy）
• 账户锁定（Account lockout）
• 安全密码重置（Secure password reset）
• 会话管理（Session management）
• 令牌过期（Token expiration）
• 登出失效（Logout invalidation）

对 Dillinger 这类纯 OAuth 应用，“强密码/锁定/重置”三项由 GitHub、Google 等 IdP 保证；仓库自身的会话管理责任在于：OAuth 令牌的生命周期与过期处理、unlink路由正确执行登出与令牌清除、各云服务status路由（app/api/github/status/route.ts、app/api/dropbox/status/route.ts等）如实反映连接状态。API 层则通过 Bearer Token 鉴权（见 app/api/v1/openapi/route.ts 的securitySchemes.bearerAuth声明）实现令牌化访问。

API 安全清单（API Security Checklist）

• 必须认证（Authentication required）
• 每个端点独立授权（Authorization per endpoint）
• 输入校验（Input validation）
• 速率限制（Rate limiting）
• 输出净化（Output sanitization）
• 错误处理（Error handling）

Dillinger 的 v1 API 是清单的教科书式对应：所有端点（/api/v1/convert、/api/v1/render、/api/v1/export/html、/api/v1/export/pdf、/api/v1/webhooks）都在处理业务前先调用validateApiKey(request)完成“必须认证”；convert端点对请求体做类型与空值校验（400）；convert的 catch 分支返回通用错误文案"Failed to convert HTML to markdown"（500），避免泄露内部异常细节，即“错误处理”与“输出净化”的体现。OpenAPI 规范在 app/api/v1/openapi/route.ts 中完整声明了 bearerAuth 安全方案，可供审计者对照端点逐个核验授权。

数据保护清单（Data Protection Checklist）

• 静态加密（Encryption at rest）
• 传输加密（Encryption in transit）
• 密钥管理（Key management）
• 数据最小化（Data minimization）
• 安全删除（Secure deletion）

Dillinger 文档数据主要托管于第三方云盘（Dropbox、Google Drive、OneDrive、Bitbucket、GitHub 仓库），因此“静态加密/密钥管理”由云服务商与平台密钥体系共同承担；仓库侧可验证的是：OAuth 令牌是否仅存于服务端环境、DILLINGER_API_KEY是否通过环境变量而非硬编码注入、导出下载文件名是否经sanitizeDownloadFilename净化（数据最小化与安全处理的实践）。

安全响应头速查表（Security Headers）

security_scan.py的配置扫描器会专门查找next.config.js/next.config.mjs/middleware.ts/nginx.conf中是否存在安全响应头配置；在 Next.js 中通常建议在next.config.mjs的headers()或中间件中统一注入以上响应头。

快速审计命令（Quick Audit Commands）

实际执行（来自 security_scan.py 的 CLI 定义）：

# 全量扫描（依赖 + 密钥 + 代码模式 + 配置），输出 JSON 报告 python .agent/skills/vulnerability-scanner/scripts/security_scan.py <project_path> # 仅扫描某类风险 python .agent/skills/vulnerability-scanner/scripts/security_scan.py <project_path> --scan-type deps python .agent/skills/vulnerability-scanner/scripts/security_scan.py <project_path> --scan-type secrets python .agent/skills/vulnerability-scanner/scripts/security_scan.py <project_path> --scan-type patterns python .agent/skills/vulnerability-scanner/scripts/security_scan.py <project_path> --scan-type config # 输出人类可读的摘要而非 JSON python .agent/skills/vulnerability-scanner/scripts/security_scan.py <project_path> --output summary

--scan-type支持all|deps|secrets|patterns|config（默认all），--output支持json|summary（默认json）。扫描器默认跳过node_modules、.git、dist、build、__pycache__、.venv、venv、.next等目录；代码文件覆盖.js/.ts/.jsx/.tsx/.py/.go/.java/.rb/.php，配置文件覆盖.json/.yaml/.yml/.toml/.env*。汇总时只要存在 critical 即判定[!!] CRITICAL ISSUES FOUND，否则依次降级为 HIGH / REVIEW RECOMMENDED / SECURE。

如何把清单落进真实项目：以 Dillinger 为例

结合上文，一次完整的审计巡检可以这样编排：

1. 威胁建模：按 SKILL.md 的四个提问界定 Dillinger 的资产（用户文档、OAuth 令牌、DILLINGER_API_KEY）、攻击者（匿名爬虫、恶意第三方应用）与入口点（v1 API、OAuth 回调、上传/导出端点）。
2. 自动扫描：运行security_scan.py全量扫描，重点核对 A03（锁文件 + npm audit）、A04（密钥泄露）、A05（危险代码模式）、A02（调试/开发模式、CORS 配置）。
3. 人工核验清单：逐项检查 A01 的“所有 v1 路由是否都调用了validateApiKey”、A05 的“安全响应头是否已在 next.config.mjs/middleware 配置”、A07 的“OAuth 回调与 unlink 会话处理”、A10 的“PDF 导出/图片上传的 URL 校验”。
4. 输出报告：将勾选结果连同security_scan.py的 JSON/摘要输出一起复制进 PLAN.md 或安全报告，按“Critical/High/Medium/Low”分级列出修复项——这与清单文档的 Usage 说明一致。

关键提醒：清单只负责“发现问题”，优先级决策仍需结合 CVSS、EPSS 与资产价值（参考 SKILL.md 的风险决策树：EPSS > 0.5 即 CRITICAL，否则看 CVSS 分级），并始终追问一句：“攻击者会拿这个做什么？”

• 前端
• 开发工具