public/FastapiAdmin
1
0
Fork 0
mirror of https://github.com/fastapiadmin/FastapiAdmin.git synced 2026-10-14 05:00:10 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
896320c83e8b976c26642b7c06948563f7c80d10
FastapiAdmin/AUDIT-REPORT.md
T

21 KiB
Raw Blame History

FastapiAdmin 全栈审计总报告

生成时间：2026-10-04 审计范围：后端（FastAPI）、Web 管理后台（Vue3）、移动端（uniapp）、部署编排（Docker/Nginx）、需求覆盖、测试与可验证性、交互与视觉一致性 参与：7 名审计成员并行执行 + 队长线上实测复核 方法：只读审查 + 真实命令执行（命令与退出码均记录在各分报告）；线上结论均由对生产环境的实测得出

0. 一句话结论

这是一个功能可用、但安全与质量债较重的单租户 RBAC 中后台：认证、权限、代码生成等核心能力具备，但存在多类可被直接利用的问题（公开密钥可伪造令牌、超管弱口令、代码生成即 RCE、部署面暴露），同时需求文档声称的 SaaS 多租户能力在代码中零实现——需求文档与实际产品是两件事。

1. 覆盖范围与缺口（必须先看）

维度 已覆盖 未覆盖 / 存疑
后端代码 216 个 py 文件 / 28519 行静态审查；ruff check 全量通过 需真实 MySQL/PostgreSQL/Redis 的行为未验证（本机三端口均不可达）
前端 Web 101 个 .vue；type-check exit 0；vitest 10/10 通过 无浏览器实机验证；无真机性能数据
移动端 uniapp 14 个页面；type-check exit 0 未跑 uni build 各平台产物；无真机验证；0 测试
部署编排 compose 校验、镜像构建、容器运行时、端口、证书、资源实测 未做真实压测；未验证灾备恢复演练
需求覆盖 逐行读 REQUIREMENTS.md Part1 + §11–§19 + §20–§22 + §28–§30 §23–§27、§38–§40 依「代码零实现」这一可穷举事实下结论，未逐行读正文表格
测试 pytest 与 vitest 真实执行 迁移链路 0 覆盖；无 CI

审计成员明确声明的抽样边界与存疑项，见各分报告末尾章节；本报告不把抽样结论伪装成全量结论。

2. 必须先止血的问题（可被直接利用）

2.1 [blocker] 生产使用源码公开的默认 SECRET_KEY

  • 证据：backend/app/config/setting.py:66 默认值硬编码；docker/docker-compose.yaml、docker/.env.example、backend/env/.env.prod 三处均无该键（grep 验证 + 线上容器 env 实测）
  • 后果：
    • backend/app/core/security.py:114,139 用该密钥签发/校验 JWT → 可离线伪造任意用户（含超管）令牌
    • backend/app/core/crypto_util.py:47-56 用同一密钥经 HKDF 派生 DATA_ENCRYPTION_KEY → 落库的加密字段（API Key、存储源口令）可被解密
    • 与 /api/v1/monitor/online/list 返回的 session_id 结合，可在不知道任何口令的情况下完成认证绕过
  • 为什么严重：攻击者只需要拿到源码（或知道该默认字符串），不需要任何其他条件

2.2 [blocker] 种子超管账号使用公开弱口令

  • 证据：安全审计经 PBKDF2 复算确认种子哈希对应 123456；backend/app/scripts/initialize.py 无环境判断，空库启动即写入；README 中公开该口令
  • 受影响账号：super、admin（均为超管）
  • 实测补充：种子账号的登录受滑块验证码保护，但安全审计判定该验证码无实质人机校验，不构成有效防线

2.3 [blocker] 代码生成模板导致权限即 RCE

  • 证据：生成模板 autoescape=False，把 function_name / column_comment / column_name 原样写入 .py；输出目录为 app/plugin/**，而 app/core/discover.py:52,74 在启动时 import 该目录
  • 后果：任何拥有代码生成权限的账号可通过构造字段注释写入任意 Python 代码，服务重启后执行
  • 相关：backend/app/modules/system/scheduler 侧 SCHEDULER_ALLOW_CODE_EXEC=True（setting.py:127）+ exec 带完整 builtins（ap_scheduler.py:562-563）无需 gencode 权限同样构成 RCE 面

2.4 [blocker] 仓库当前无法构建

  • 证据：docker/backend/Dockerfile 仍只 COPY requirements.txt，而依赖已拆分为 backend/requirements/；该目录未被 git 跟踪（git ls-files backend/requirements = 0）
  • 后果：新克隆的仓库按文档构建必然失败；deploy-artifacts.sh 因其自带 Dockerfile 生成逻辑而绕过该问题，但这掩盖了仓库本身的破损
  • 状态：本轮已将仓库 Dockerfile 改写为与新依赖结构一致（见 §4）

2.5 [high] 部署面暴露与错误默认值

项 证据 状态
API 文档公网可访问 /api/v1/docs、/redoc、/openapi.json 实测 200 已修（nginx 仅放行内网）
MySQL/Redis/Backend 端口对公网开放 外部实测 3306/6379/8001 均可达 已修（绑定 127.0.0.1）
生产 CORS 回落为 ["*"] 且 ALLOW_CREDENTIALS=True setting.py:243-248 待修
FORWARDED_ALLOW_IPS="*" docker-compose.yaml:119；叠加后端端口曾暴露 → 可伪造 XFF 绕过限流与登录 IP 记录 待修
登录失败返回 HTTP 500 实测：验证码过期走 custom_exception_handler → 500（业务异常被当服务器错误） 待修

3. 逻辑与契约缺陷（影响数据正确性）

  1. 通知状态枚举两端冲突（已复核）：后端权威 notice/model.py:16 = 0草稿/1已发布/2已归档，移动端一致；Web 端 views/module_system/notice/index.vue:116-117,189-190,254,403 却是 0启用/1停用 → 已归档公告在 Web 显示为灰色数字「2」，且筛选条件里不存在「已归档」。
  2. 移动端刷新令牌格式不符：app 发 {refresh_token} 对象，后端 auth/controller.py:57 为 Body(str) → 422；移动端 token 过期后必然强制登出。
  3. 移动端文件上传路径错误：app 调 /file/upload，真实路径为 /api/v1/common/file/upload → 404。
  4. 移动端生产 WebSocket 指向 localhost：app/.env.production:23 = ws://localhost:5180/ws → 线上 AI 对话不可用。
  5. 富文本默认上传地址畸形：web/src/components/forms/fa-wang-editor/index.vue:83 拼出 //file/upload（协议相对 + 缺 /common）→ 公告/工单插图必失败。
  6. Web 生产构建开关恒 false：web/vite.config.ts:28 判断 mode === "prod"，而脚本只传 production/development → minify、drop_console、gzip/brotli、剔除 vue-devtools 全部不生效。
  7. CRUDBase 权限注入不完整：base_crud.py:300-330 仅读路径注入数据权限，delete/clear/set（:225-251）不注入；6 处 set_available 无完整性校验 → 普通管理员可改任意部门/字典/公告、可停用超管。
  8. 部门/菜单成环导致权限查询 500：common_util.py:181-196 的 get_child_recursion 无 visited 集合。

4. 本轮已落地的修复（部署侧，全部有验证证据）

修复 证据
关闭公网数据面暴露：3306/6379/8001 仅绑 127.0.0.1 外部实测三端口均已关闭；四端 200
API 文档对外封堵（仅内网可访问） 外部 403，服务器本机 200，业务接口不受影响
容器改为非 root 运行（uid=1000 app） 容器内 id = app；日志/上传/迁移目录均可写
TLS 私钥与 .env 权限收紧到 600 stat 实测；nginx 仍可读取
隐藏文件不再对外服务 .DS_Store 由 200 变 403，并加 nginx deny 兜底
静态资源长缓存 哈希资源 max-age=31536000, immutable，图片 30 天，HTML 不缓存
nginx 升级 1.25.5 → 1.27.5 配置校验通过；TLS1.2/1.3 正常；保留 nginx:rollback-1.25
后端健康检查修复 由长期 unhealthy 变为 healthy（ALLOWED_HOSTS 放行 localhost）
后端依赖拆分（核心 / 数据库驱动 / 存储） MySQL 变体镜像 565MB → 521MB；PG 变体自检 asyncpg+psycopg 通过
部署脚本具备备份、回滚、轮转、变体构建 deploy-artifacts.sh 各子命令均实测通过（含回滚哨兵测试）
SSH 加固 密码登录禁用、root 仅密钥、密码已轮换

5. 修复路线（按风险×成本排序）

优先级 动作 影响面 预估
P0 注入强随机 SECRET_KEY + DATA_ENCRYPTION_KEY；轮换 super/admin 口令；若启用演示模式则关闭 会话作废需重新登录；落库密文保持可解 30 分钟
P0 修仓库 Dockerfile 与依赖跟踪，使「克隆即可构建」 无运行时影响 20 分钟
P1 前端 5 条 P0（生产开关、刷新令牌、上传路径、WS 地址、富文本上传） 需重建并部署前端 1–2 小时
P1 后端：日志级别、SCHEDULER_ALLOW_CODE_EXEC=False、模板 autoescape=True、CRUDBase 补权限注入、get_child_recursion 防环 需完整回归 1 天
P1 生产 CORS 显式白名单；FORWARDED_ALLOW_IPS 收敛；业务异常返回 4xx 需回归 半天
P2 建立 CI（后端 pytest + ruff、web type-check + vitest）；修复测试夹具（fakeredis、assert_route、隔离） 无运行时影响 1–2 天
P2 Web i18n 补齐（85/101 页面未接入）与通知枚举修正 需产品确认后端是否提供菜单 i18n 字段 2–3 天
P2 证书自动续期（当前 2027-03-06 到期，无续期与告警；ACME 路径被 301） 无运行时影响 半天
P3 清理死代码、any 治理、键盘可达性（76 处 @click 无 tabindex/role） 渐进 持续

6. 需要决策的事项

  1. 线上数据库口令与 OPENAI_API_KEY：两者均出现在 git 历史（旧库口令命中 10 个提交，已推送到 master/dev），且镜像内 .env.prod 曾包含真实值 → 建议按已泄露处理并重新签发。是否重写 git 历史取决于仓库可见性。
  2. 多租户规格错位：REQUIREMENTS.md v3.6.0 描述 SaaS 多租户（grep -ril tenant 在三端 0 命中），实为单租户后台；该文档是 CHANGELOG.md 重命名产生的纯文档提交。是「改文档」还是「立项实现」，只能由产品决定。
  3. /user/register 接口：无鉴权/无验证码/无开关（当前被 DEMO_ENABLE 挡住返回 400）。是否保留该接口、以及演示模式在生产是否应关闭。
  4. 后端是否提供菜单名 i18n 字段：Web 侧边栏菜单名来自数据库，补齐前端 i18n 后菜单仍为中文。
  5. 移动端范围：无批量操作、无导入导出是否已在需求中登记为范围外。

7. 本次审计对既有结论的修正（避免误判）

原表述 修正
任务背景称「Web 端使用 uno.config.ts」 不成立：Web 端为 Tailwind v4（@tailwindcss/vite + tailwindcss@^4.3.0），UnoCSS 仅存在于 app 端；两端令牌体系独立
安全报告称 /user/register 无鉴权可注册 接口确实无鉴权，但当前被演示模式拦截（实测 400）；风险取决于 DEMO_ENABLE
队长初判 nginx ssl_protocols 缺 TLS1.3 误判：nginx -T 显示 ssl_protocols TLSv1.2 TLSv1.3;，实测 TLS1.3 可用
队长初判 .DS_Store 清理后仍可访问 实为清理成功，后续 200 来自 SPA 回退（try_files → index.html），已用 deny 规则彻底封堵

8. 分报告索引

报告 覆盖
backend/audit-backend.md 后端架构与代码质量（22 条）
frontend/audit-frontend.md 前端与移动端工程（32 条）
backend/audit-testing.md 测试与可验证性
backend/audit-security.md 认证/授权/敏感信息（23 条）
backend/audit-requirements.md 需求覆盖对照
frontend/audit-uxui.md 交互与视觉一致性（590 行）
docker/audit-deploy.md 容器化与部署链路（799 行）

每份报告均包含：问题清单（级别 + 文件:行号 + 现象 + 影响 + 建议）、按优先级的修复清单、未验证/存疑项。

9. 修复进展（2026-10-04 更新）

9.1 已修复并验证（上线）

类别 修复内容 验证证据
部署面 MySQL/Redis/backend 端口收敛到 127.0.0.1 宿主机 socket 实测：公网监听数 0；服务器自连公网 IP 返回 ConnectionRefused
部署面 API 文档仅内网可访问 公网 403 / 内网 200
部署面 容器非 root（uid=1000）运行 容器内 id = app；日志/上传/迁移目录可写
部署面 TLS 私钥与 .env 权限 600；隐藏文件 403 stat 与 curl 实测
部署面 静态资源长缓存；nginx 升级 1.27.5；ACME 校验路径放行 响应头 max-age=31536000, immutable；证书 153 天
部署面 每日健康巡检（容器/接口/证书/磁盘/swap） systemd timer active，日志全绿
部署面 CI（backend: uv+ruff+pytest；frontend: type-check+vitest） workflow 语法与引用脚本已校验
密钥 SECRET_KEY 与 DATA_ENCRYPTION_KEY 轮换并注入；旧密钥保留于 OLD_KEYS 旧密钥加密样本仍可解密；用旧公开默认密钥伪造的令牌被拒（InvalidSignatureError）
口令 种子账号 super/admin/user 口令轮换 新口令与库内哈希匹配、旧口令 123456 被拒
策略 生产 CORS 不再回落通配；FORWARDED_ALLOW_IPS 收敛为应用网段；DEMO_ENABLE 显式化 恶意 Origin 无许可头；容器内环境变量实测
前端 5 条 P0（生产构建开关、令牌刷新、上传路径、WS/开发地址） type-check×2、build:prod、build:h5 均 exit 0；产物第一方 console 0 命中；H5 内 localhost:5180 0 命中
后端 业务异常按语义返回（客户端 4xx / 内部故障 500）；调度器 exec 默认关闭；代码生成按上下文转义 ruff 全过、pytest 47 passed；AST 级对抗载荷无法注入；线上验证码过期由 500 变 400
后端（复核未通过 → t14 pass） 代码生成注入面曾未真正关闭：column_type 未安全化即进入代码位置 mapped_column({{ sqlalchemy_type }}) 独立复核 t12 = needs_revision；队长复现载荷原样拼入 → t13 整改（类型白名单 + 结构闸门）、t14 复审 pass
后端（错误码收敛） 单一事实来源：删除全部显式 status_code（含构造器参数），HTTP 语义只由 RET.code → fastapi.status 映射决定；_DEFAULT_BUSINESS_STATUS 降为未登记码安全网 业务代码中 CustomException 带 status_code = 0；AST 护栏（注入违规即失败）；语义探针 400/401/403/404/500 全对
后端（异常写法统一） 删除 CustomException.internal 与 132 处包装：意外异常交全局处理器（5xx + 通用文案 + 日志），需运维上下文处 logger.exception(...) + raise；6 处 4xx→5xx 反转点补 except CustomException: raise grep CustomException.internal = 0；构造器传 status_code 抛 TypeError；AST 审计残留 0；97 用例通过；线上验证码过期仍 400 且保留业务文案
后端（全局兜底修正） SQLAlchemyError 非完整性错误由 400 改为 503（连接）/500（其它），文案不再拼 exc_type 读码 + 探针实测 409/503/503/500/500
前端（错误文案） 错误提示改为「后端 msg 优先 → 业务码兜底 → 状态码兜底 → 通用」，去掉按 code 白名单取文案的耦合（含 Blob 下载分支；401 排除在解析外以不影响静默续期） type-check exit 0；vitest 41 用例（含 500+4500 与 404+404 文案断言）；成功下载分支零改动
存储适配器（类型检查暴露的运行时缺陷） ① OSS：Client.uploader 是方法，原写法 self.client.uploader.upload_file(...) 在绑定方法上取属性 → 运行时 AttributeError（OSS 上传必失败）；② SFTP/FTP：config.host 可空却直接传给要求 str 的 connect(hostname/host) ① 改为 self.client.uploader().upload_file(...)（已按 SDK 签名核对 part_size/parallel_num）；② 补主机校验，缺主机时返回 400 业务异常；basedpyright 这三个文件由 4 error → 0；运行时探针：缺主机拦截、配主机放行
类型检查校准（新增 backend/pyrightconfig.json） 仓库此前无 pyright 配置，basedpyright 走自身默认：app/ 下 247 errors / 3799 warnings，143 条是 reportMissingTypeArgument 泛型注解类噪音，掩盖真缺陷 typeCheckingMode: basic + 显式保留能抓 bug 的规则为 error + tests/ 用 executionEnvironments 单独放宽 → 0 errors；做了红绿验证：合成 `str
类型检查暴露的两处真缺陷（我们上一轮引入） ① template_safety._SQLALCHEMY_TYPE_WHITELIST 对全大写常量二次赋值；② 同文件 normalize_column_type 假定 _TYPE_BASE_RE 必命中（用 # type: ignore 盖住，None 时 .group() 会崩）；③ node/service.py 两处 CustomException(msg=reason) 中 reason 为 `str None` → 客户端可能收到空文案

9.2 仍未处理（需后续立项或产品决策）

项 说明
会话失效机制 停用/删除/改密/撤权后旧会话仍有效（最长 7 天）——需应用侧改造
数据权限注入 CRUDBase 的删除/清空/改状态路径未注入数据权限
需求规格错位 文档声称的 SaaS 多租户在代码中零实现
Web i18n 与通知枚举 85/101 页面未接入 i18n；通知状态枚举与后端语义冲突
测试覆盖与夹具 夹具掩盖缺陷、迁移链路 0 覆盖（CI 已建立，但用例仍需补）
移动端其它缺陷 alova.ts:115-119 请求头写成 ContentType（缺连字符），修正需回归上传/表单/JSON 三类请求
密钥残留 旧数据库口令与 OPENAI_API_KEY 仍存在于 git 历史，建议按已泄露处理并重新签发
对外口径（异常统一后的取舍） 存储「测试连接」密钥环损坏、上传/下载失败、OAuth 渠道未配置、Redis 同步失败等已由具体原因变为通用 5xx 文案（细节只在日志）。若希望管理员在界面看到可操作原因，正确做法是为这些场景定义业务码，而不是回到「包装意外异常」
仍可能外泄的出口 ValueError 全局处理器返回 msg=str(exc)；建议改为通用文案 + 日志，或让我们的校验统一抛 CustomException
静默吞异常（既有） 48 处「记录日志但不 raise」的 best-effort 处理器（redis_crud、ap_scheduler、middlewares、discover 等），属审计「静默吞异常」主线，建议单独排一轮

9.3 本轮产生的回滚资产

  • 镜像：backend:prev（上一版）、nginx:rollback-1.25
  • 配置备份：docker-compose.yaml.bak-*、nginx.conf.bak-*、.env.bak-*
  • 静态成品备份：backups/{web,app-h5}-<时间戳>（每类保留 5 份）
  • 种子账号新口令：服务器 /root/.fa-seed-passwords（600，登录后请修改并删除）

10. 收尾状态

代码与部署

  • 本轮共 12 个提交（ce940119 … 本报告提交），已推送 GitHub master/dev 与 gitee gitee/dev。
  • 线上版本：后端含 t10/t11/t13/t15/t16/t19 全部修复；Web 含 t17/t18 错误文案修复；App 为 t9 修复版。
  • 部署方式：本机构建成品 → 服务器只接收镜像与静态产物（服务器无源码、无构建），细节见 DEPLOYMENT.md。

最终验证（部署后新跑）

项 结果
容器 backend / nginx / redis / mysql 全部 healthy；健康检查 exit 0
四端（公网） /、/web/、/app/、/api/v1/monitor/health/check 均 200
接口文档 公网 403；仅内网白名单可访问（本机 200）
Host 校验 正确域名 200；localhost 400；伪造域名 400（ALLOW_LOCALHOST_HOSTS=false）
数据面暴露 3306/6379/8001 无公网监听（宿主 ss + 服务器自连双向确认）
业务语义 验证码过期 → 400 且保留业务文案；无令牌 → 401；内部故障 → 5xx + 通用文案（细节仅日志）
密钥 旧公开默认密钥伪造令牌被拒；SECRET_KEY/DATA_ENCRYPTION_KEY 已注入并轮换
类型检查 basedpyright 全量 0 errors（backend/pyrightconfig.json）；ruff 全绿
测试 后端 pytest 97 passed；Web vitest 41 passed
巡检 fa-health-check.timer active，日志无 ALERT

团队

审计团队（7 名成员，t1–t19）已归档；本报告与 7 份分报告为全部交付物，残余项见 §9.2。

收尾后仍需人工处理（不阻塞上线）

  1. 轮换 OPENAI_API_KEY 与旧数据库口令（已进历史/镜像层，按已泄露处理）。
  2. 审计报告内含旧密钥的少量特征（前 4 字符与长度）用于佐证；若仓库将转为公开，建议先按上述轮换再考虑是否脱敏。
  3. §9.2 中的产品/架构决策项（会话失效、数据权限注入、多租户规格、i18n、移动端 ContentType）。
Reference in New Issue View Git Blame Copy Permalink