前端密钥与密码怎么处理:从 21 处硬编码,到五种落地改法

4 阅读22分钟

一句话结论:前端没有秘密,写进前端的东西一律按「已公开」对待。 所以前端要解决的不是「怎么把密钥藏好」,而是「怎么让前端根本不需要密钥」。密码同理——只要加密用的 key 跟代码一起发布,这层加密就只是把明文换成了「钥匙挂在门上」的密文。本文按「分类 → 判据 → 方案 → 顺序 → 门禁」展开,密码和密钥分开讲,最后拿一个真实项目的 21 处命中做归类,只取 OWASP、Vite、Stripe、高德、GitHub 官方文档与 npm 信息。

一、一次「看起来合规」的登录

某 SaaS 前端要过安全评审,评审项里有一条:密码不得明文传输。

最省事的落地方式是:登录前用 SM4 把密码加密,请求体里放密文。评审看到抓包里没有明文,过了;测试看接口通了,过了;演示时一切正常。这一层就这样活了两年多。

直到有人问了三个问题:

  1. 加密用的 key 从哪来?
  2. 这个 key 跟着谁一起发到了浏览器?
  3. 拿到 key 的人能做什么?

三个问题的答案分别是「源码里的一个常量」「跟业务代码同一个 js 包」「能离线还原任何一个抓到的密码」。于是这层加密的实际效果只剩下一个:让人以为已经处理过了。

更麻烦的是它的连带损失——服务端日志、网关日志、监控 SDK 采集到的请求体,全是密文。这看起来比明文「安全」,但它给了团队一个错觉:日志里没有明文,所以不用脱敏。等到 key 泄漏,这些日志就变成了明文密码的存档。

拿到这个 key 的人能做什么代价
任意访客(打开 F12 就行)解出自己抓到的任何一次登录密码零成本
能看网关日志的人批量还原历史密码一次 grep
拿到一张弱口令密文表的人不解密也能识别哪些账号用了弱口令见第五章 ECB 部分

先把结论摆在这里,后面逐条论证:密码不该在浏览器里做对称加密,密钥不该放进任何会发给浏览器的文件。

二、密码和密钥不是一回事

很多讨论一开口就乱,是因为把两样东西混成了一件。它们的处置方式完全不同。

对象是什么前端能做的前端绝不能做的正确位置
用户密码用户脑子里的凭据采集、经 TLS 传输对称加密、哈希、缓存、打印服务端存哈希(Argon2id / bcrypt)
应用密钥系统对系统的凭据什么都不做出现在任何会发给浏览器的字节里服务端运行时环境变量或密钥库
会话令牌短期身份凭据存储、随请求携带长期明文存 localStorageHttpOnly Cookie 优先
可公开标识设计上就公开的 id正常使用无限制地裸奔配好域名限制与配额

这张表能解释两类最常见的错:

  • 把令牌当密钥藏。 前端拿到 token 就必然能被读走,加密存储只会让「读」多一步。真正要控制的是它的生命周期与作用域,不是它存得够不够隐蔽。
  • 把密钥当令牌用。 密钥泄漏后换一次就行——这个思路没错,但很多项目连「换」这一步都没有,因为它压根不在台账上,没人知道它的存在。

三、前端没有秘密:四条证据

在动手改之前,先接受一个事实:只要是浏览器执行过的代码,就等于公开源码。四条证据,每条都能自己验。

第一条:构建产物就是源码。 压缩只改名字,不改字符串字面量。密钥是字符串,所以它在产物里原样躺着。

第二条:VITE_ 前缀不是保密开关。 它恰恰是「注入客户端」的开关。Vite 官方文档的原话是:VITE_* 变量不应包含 API key 这类敏感信息。反过来验一次最直观——不带前缀的变量在浏览器里是 undefined,带前缀的才拿得到值。也就是说,前缀决定它会不会进包,而不是决定谁能看见。

// 反例:以为加前缀等于「只在服务端可见」
const secret = import.meta.env.VITE_API_SECRET; // 值被原样写进 js 产物
// 没有前缀的变量在浏览器里永远是 undefined,这才是 Vite 的隔离机制

// 正例:允许出现在前端的,只能是「本来就是公开的」那类
const mapKey = import.meta.env.VITE_AMAP_JS_KEY; // 仍需配域名白名单与配额

第三条:运行时配置文件一样能下载。 有些项目为了「不打进包」,把配置抽成 _app.config.js,运行时再 fetch 回来。但这仍然是一个静态文件——任何人访问 /config.js 都能拿到。抽出去只是把「在 bundle 里搜」变成「在 Network 面板里看」。

第四条:git 历史比源码更长寿。 删掉一行代码不等于删掉这条记录。四行命令就能完成取证:

# 1) 产物里搜已知的密钥前缀(先扫已经暴露的)
grep -rnoE "sk_live_[A-Za-z0-9]{10}|sm4key|aesKey" dist | head

# 2) 按变量名扫源码(找同类,不只找这一个)
grep -rnE "(apiKey|secret|password|salt|iv)\s*[:=]\s*['\"][^'\"]{8,}" src | head -30

# 3) 按值形态扫(32/40 位十六进制串是国密与云厂商 key 的常见形态)
grep -rnoE "\b[0-9a-f]{32}\b" src | head

# 4) 回溯历史:这个密钥是什么时候进来的
git log --all -S "<密钥前缀>" --oneline

第 4 条最有价值。它回答的不是「谁写错了」,而是「哪一次搬迁、哪一个模板、哪一次赶工带进来的」——这决定了你要修的是一个文件,还是一类习惯。

四、一条判据:三问定生死

判断一个凭据能不能放前端,只用三个问题,全部满足才算合格。

问题不满足意味着
拿到它的人,能不能做出超出该用户权限的事?能,就是提权入口,不能放
能不能把使用范围限制在指定域名 / IP / 包名?不能,任何网站都能拿去刷,不该放
有没有时效或额度,出事能不能快速吊销?都没有,泄漏就是永久损失,绝不放

按这三问过一遍常见凭据,结论很干脆:

凭据能放前端吗一句话依据
Stripe pk_live_可以官方标注 Safe to expose: Yes,只能建 token,不能扣款
Stripe sk_ / rk_不可以官方标注 No,sk_ 拥有全部权限
地图 JS SDK key有条件可以必须配 Referer 白名单 + API 限制 + 日配额
地图「Web 服务」key不可以服务端型 key,能直连 REST 接口按量计费
云厂商 AccessKey不可以长期凭据,泄漏等于账号被接管
对称加密 key(SM4 / AES)不可以它的安全性完全等于「没人拿到它」
OAuth Client ID / Secret前者可以 / 后者不行Secret 可冒充应用换 token,公共客户端应改 PKCE

再补一条容易被忽略的:可公开不等于可以硬编码。 可公开的 key 也应该走配置注入、按环境区分、可一键吊销。因为它虽然不泄漏数据,但能被别人拿去刷你的账单——你依然需要一个止损开关。

顺带说一句合规口径。OWASP Top 10:2025 把这类问题归在 A02:2025 Security Misconfiguration(2021 年第 5 位升到第 2 位),弱点编号 CWE-798 Use of Hard-coded Credentials,官方标注利用可能性为 High,并专门点出「出站型」变体:前端去连后端时,把后端凭据直接写进了前端产物。OWASP 给的处理方式写得很直接——用身份联邦、短期凭证或平台 RBAC,替代在代码、配置、流水线里嵌静态密钥。这句就是全文的靶心。

五、密码怎么处理

这一章是核心。四条路线,先把结论列出来,再解释为什么只剩一条。

5.1 四条路线的对比

路线做法机密性抗重放结论
前端对称加密SM4 / AES 加密密码,key 写在源码无(key 同包)无(密文可重放)不可用
前端哈希SHA256 / SM3 算摘要再发无(摘要即密码)无更糟,见 5.3
前端非对称加密SM2 / RSA 公钥加密,私钥在服务端有需配 nonce合规要求时可接受
HTTPS 直传 + 服务端哈希前端不碰密码,服务端存 Argon2id有(TLS)靠会话与风控推荐

5.2 为什么前端对称加密的机密性是零

两个原因,一个是设计上的,一个是算法模式上的。

设计上的:key 和密文同路。 加密发生在浏览器,解密发生在服务端,那么浏览器必须持有加密能力所需的 key。这个 key 就在 js 里。攻击者不需要「破解加密」,他只需要「打开产物、搜一下、复制」。密码学的强度完全没有被使用——被绕过的从来不是算法,是密钥分发。

算法模式上的:默认 ECB 会放大伤害。 前端常用的国密库在调用时如果没传 iv,默认走 ECB 模式(sm-crypto 的源码注释里明确写着「CBC 模式,默认走 ECB 模式」)。ECB 是分组独立加密,同样的明文块永远得到同样的密文块,于是:

  • 同一个密码在不同账号、不同时间加密出来完全相同——攻击者不需要解密,只要有一张「常见弱口令 → 密文」对照表,就能在数据层面批量识别谁用了弱口令;
  • 密码不足一个分组时要按 pkcs#7 补齐,补齐字节数是确定的(8 位密码固定补 8 个 08),连填充后的分组都一致,对照表的构造成本进一步降低。

怎么验自己有没有踩: 用同一个密码连打两次登录,比较请求体里的密文。两次相同 → ECB;两次不同 → 至少用了随机 IV 或非对称。这一步 30 秒能做完,比读代码快。

5.3 为什么「前端哈希」比加密更糟

有人会说:那把密码哈希一下再发,服务端存哈希比对,不就谁也拿不到明文了?

这条路更危险,因为它把哈希值本身变成了密码:

  • 如果服务端比对的是「前端算出来的摘要」,那攻击者抓到摘要就能直接登录——他不需要知道原密码。这就是 pass-the-hash:凭据从「你知道什么」退化成了「你抓到什么」。
  • 如果摘要不加盐,彩虹表直接命中常见密码;如果加盐,盐必须在前端,而盐也在包里,等于没加。
  • 前端哈希还会让服务端失去做密码强度校验、复用检测、风控画像的能力——它拿到的是一个摘要,看不出任何密码特征。

一条能记住的判据: 如果验证端需要的只是「客户端算出来的那个值」本身,那这个值就是密码。凡是能被原样重放的,都不是加密,是换了个编码。

5.4 推荐路线:HTTPS 直传,服务端存哈希

HTTPS 已经提供了传输层加密,前端再加一层对称加密不增加任何安全性,只增加一处泄漏点。正确的位置在服务端。

// 前端:不做任何加密,原样交给 TLS
import { http } from '@/utils/http';

export function login(username: string, password: string, captcha: string) {
  return http.post('/api/auth/login', { username, password, captcha });
}
// 服务端:只存哈希,登录时比对(示意,Node + argon2)
import argon2 from 'argon2';

// OWASP 密码存储备忘单给出的参考配置之一:Argon2id
const OPTS = { type: argon2.argon2id, memoryCost: 19456, timeCost: 2, parallelism: 1 };

// 注册 / 改密时
const passwordHash = await argon2.hash(plain, OPTS);

// 登录时:verify 内部做常数时间比较,不要自己写 ===
const ok = await argon2.verify(user.passwordHash, plain);

配套的三件事,缺一件这层就不成立:

  1. 全站强制 HTTPS,并开 HSTS。传输层是这条路线唯一的机密性来源。
  2. 密码重置与改密走同一套哈希,不要在某个分支里图省事存明文或 MD5。
  3. 登录失败不做「用户是否存在」的区分,错误信息统一,避免账号枚举——这跟前端加密没关系,但总被一起做错。

还有一个常见的误区:上前端加密是为了「防暴力破解」。不成立。防自动化靠的是验证码、频控、设备指纹、异常登录检测,这些都在服务端。前端加密挡不住脚本,脚本比你更会调你的加密函数。

5.5 合规必须国密时:SM2 公钥 + nonce

有些场景确实有硬性要求:「密码传输必须用国密算法」。这时不该回到对称加密,而应换成非对称——公钥放前端是安全的,这是非对称加密的设计前提。

// 前端:只用公钥加密,私钥永远在服务端
import { sm2 } from 'sm-crypto';

// 公钥可以公开,它只能加密,不能解密
const SM2_PUBLIC_KEY = import.meta.env.VITE_SM2_PUBLIC_KEY as string;

export async function buildCredential(plain: string) {
  // 一次性 nonce + 时间戳由服务端下发,二者一并加密
  const { nonce, ts } = await http.get('/api/auth/nonce');
  // 第三个参数 1 表示 C1C3C2 排列,必须与服务端约定一致
  return { cipher: sm2.doEncrypt(`${plain}|${nonce}|${ts}`, SM2_PUBLIC_KEY, 1), nonce };
}

服务端要做三件事才算真的防住重放:校验 nonce 未被使用过、时间戳在 5 分钟窗口内、同一 nonce 只用一次。少了这三条,公钥加密只解决了「不被离线解密」,解决不了「抓到密文重放一次也能登录」。这是国密改造里最常漏的一环。

顺带提醒:SM2 加密同一明文每次结果不同(有随机数),所以 5.2 里那个「两次密文相同就是 ECB」的自检,在这一路线下也顺便通过了。

5.6 密码在链路上还有六个泄漏点

密码这条数据最难的地方在于:它不只出现在登录接口。下面六处,只要漏一处,前面所有努力都白做。

位置典型形态处置
控制台日志console.log('params', params)生产构建剔除;用 import.meta.env.DEV 包住
请求 URL把密码拼进 query只走请求体,永不放 URL
监控 SDK 请求采集自动上报 URL 与 body上报前统一脱敏,见下方代码
本地存储「记住密码」写进 localStorage不存;要记住就存脱敏后的账号名
异常上报与录屏报错堆栈里带上了表单值采集侧白名单字段,输入框默认掩码
网关与代理日志全量 body 落盘按字段脱敏后再落,保留期设短

监控 SDK 那条最容易被忽略,因为它默认就在工作:

// 上报前统一脱敏:不要指望「我不会打印它」,要指望「打印了也发不出去」
const SENSITIVE = /pass(word)?|pwd|token|secret|otp|captcha|idcard|phone/i;

function scrub(input: unknown, depth = 0): unknown {
  if (depth > 4 || input == null) return input;
  if (Array.isArray(input)) return input.map((v) => scrub(v, depth + 1));
  if (typeof input !== 'object') return input;
  return Object.fromEntries(
    Object.entries(input as Record<string, unknown>).map(([k, v]) =>
      SENSITIVE.test(k) ? [k, '***'] : [k, scrub(v, depth + 1)],
    ),
  );
}

怎么验: 打开生产站点,登录一次,然后去监控平台搜这次会话。请求体里的 password 字段应该是 ***。如果是明文,或者是一串能被你解开的密文,这条就是 P0。

六、密钥怎么处理:五种方案

方案按「侵入性」从低到高排,实际项目通常是组合使用。判断标准只有一条:这个 key 有没有必要出现在浏览器里。

6.1 方案一:干脆不要它(能力下沉)

最彻底的方案是让前端根本不需要这个能力:静态图由服务端生成并返回图片、短信与邮件由服务端发起、文件上传用服务端预签名的 URL 而不是长期 AccessKey、数据聚合在服务端做完只吐结果。

代价是要后端配合加接口;收益是这类风险永久消失,而不是「暂时藏好了」。凡是能这么做的,优先这么做。

6.2 方案二:BFF / 网关代理(最通用)

在浏览器和第三方之间加一层自己的服务,凭据留在服务端。改前是「浏览器带着 key 直连第三方」,改后是「浏览器带着用户会话连自己的 BFF,BFF 带上 key 转发」。

// bff.mjs —— 三件事:校验会话、路径白名单、按用户限流
import { createServer } from 'node:http';

const UPSTREAM = 'https://api.vendor.example.com';
const KEY = process.env.VENDOR_API_KEY; // 只存在于服务端运行时
const ALLOWED = ['/v1/search', '/v1/translate'];
const buckets = new Map();

function allow(userId) {
  const now = Date.now();
  const b = buckets.get(userId) || { tokens: 30, ts: now };
  b.tokens = Math.min(30, b.tokens + ((now - b.ts) / 1000) * 0.5); // 0.5 qps 回填
  b.ts = now;
  if (b.tokens < 1) return buckets.set(userId, b), false;
  b.tokens -= 1;
  buckets.set(userId, b);
  return true;
}

createServer(async (req, res) => {
  const userId = req.headers['x-user-id'];          // 换成校验自己签发的会话
  if (!userId) return res.writeHead(401).end('unauthorized');
  if (!ALLOWED.includes(req.url)) return res.writeHead(404).end('not found');
  if (!allow(userId)) return res.writeHead(429).end('too many requests');

  const upstream = await fetch(UPSTREAM + req.url, {
    method: req.method,
    // 只注入自己的凭据,绝不转发客户端传来的认证头
    headers: { authorization: 'Bearer ' + KEY, 'content-type': 'application/json' },
    body: ['GET', 'HEAD'].includes(req.method) ? undefined : req,
    duplex: 'half',
  });
  res.writeHead(upstream.status, { 'content-type': 'application/json' });
  res.end(Buffer.from(await upstream.arrayBuffer()));
}).listen(8787);

四个必须做的点,缺一条这层就白加:路径白名单(否则变成开放代理,攻击者拿你的 key 随便刷)、按用户限流(否则换个方式刷你的 BFF)、不转发客户端的认证头、不把上游错误原样透传(错误体里可能带上游 key 片段或内网地址)。

6.3 方案三:短期凭证(前端确实要直连时)

对象存储直传、设备通道这类场景绕不开直连,那就换成「有效期很短、权限很窄、可随时吊销」的临时凭据。

// 前端:先换凭证,再用它直连;长期密钥从不出现在浏览器
type Sts = { accessKeyId: string; accessKeySecret: string; securityToken: string; expiresIn: number };

async function upload(file: File) {
  const sts = await http.post<Sts>('/api/sts/upload', { scene: 'avatar' }); // 权限只含本目录 PUT
  const form = new FormData();
  form.append('OSSAccessKeyId', sts.accessKeyId);
  form.append('security-token', sts.securityToken);
  form.append('key', `avatar/${userId}/${Date.now()}.png`);
  form.append('file', file);
  // 直传对象存储;凭证 15 分钟过期,权限仅限 avatar/ 前缀
  return fetch(OSS_HOST, { method: 'POST', body: form });
}

同一个思路解决过我见过的一类典型问题:设备通道的账号口令写在构建配置里,用户名和口令还完全相同,两个都原样进了产物。真正的风险不是「能不能连上」,而是「连上之后能订阅什么」——如果 broker 的 ACL 按用户名一刀切授权,任何拿到口令的人都能订阅全平台设备状态。正确做法是登录后换取一次性凭据,并且 broker 的 ACL 按主题前缀授权(例如只允许 tenant/{tenantId}/#)。

6.4 方案四:受限的可公开 key(第三方只给 key 时)

有些第三方只提供 key 这一种接入方式(地图、部分统计与推送服务)。这时该做的不是藏,而是把「可被滥用的范围」压到最小。以地图 key 为例,四层一起上才算合格:

层动作验收
应用限制配 HTTP Referer 白名单 / IP 白名单 / 应用包名非白名单域名调用返回域名不合法
API 限制只勾选实际用到的接口未勾选接口调用被拒
配额设日调用上限超限返回配额错误,而不是继续计费
账单告警设消费阈值告警阈值触发能收到通知

还要分清 JS API key 与 Web 服务 key:前者给浏览器用,靠域名限制收敛;后者是服务端型凭据,能直连 REST 按量计费,不能出现在前端。这两类混在一个配置文件里,是很多项目的通病——审计时只要一个 key 泄漏,往往意味着同一份配置里的其他 key 也一起暴露了。

6.5 方案五:边缘函数

没有自有服务器、又不想为一个转发接口新开服务时,用边缘函数(Cloudflare Workers、各云厂商的边缘运行时)做同一件事:请求到边缘,注入密钥,转发出去。它比 BFF 轻,但要额外注意两件事:密钥存在平台的环境变量里并开启加密存储;边缘侧同样要有限流,否则清理成本会转移成账单。

6.6 选型表

场景建议方案一句话理由
能改成服务端做的能力方案一 能力下沉风险永久消失,不用长期维护
第三方 REST 接口(搜索、翻译、AI)方案二 BFF / 网关最通用,凭据只在服务端,可加限流与审计
对象存储直传、设备通道方案三 短期凭证直连不可避免时,用短 TTL 换安全边界
地图、统计等前端 SDK方案四 受限 key第三方只给 key,只能靠限制与配额收敛
无自有服务端的小项目方案五 边缘函数成本最低的转发方案
数据库连接串、JWT 签名密钥、支付 secret一律不下前端没有任何「限制」能兜住这一类

七、21 处命中:七类归因

一个 Vue 3 + Vite 的中后台 SaaS 前端,2700 多次提交,2300 多个源码文件,按「变量名 + 值形态」双向扫,命中 21 处。按类型归成七组,加起来正好 21 条。

类型处数典型形态为什么能活这么久处置
对称加密密钥2登录密码的 SM4 key、本地存储的 AES key 与 IV从旧项目整体搬迁时一起复制过来删常量 + 改协议
通道凭据1设备通道账号口令写在构建配置「上线只要通就行」短期凭据 + ACL 收窄
第三方 key4地图 JS key、Web 服务 key、安全密钥、演示页 key没有「key 分类」这个概念限制 + 分离 + 删死配置
测试凭据3.env 明文口令、历史文档里的同一口令、mock 固定 token只忽略了 .env.local,没忽略 .env先轮换,再谈清理
内网与拓扑5内网 IP、开发代理目标、注释里的预签名 URL、内网仓库地址被当成「不算密钥」移出源码 + 改占位符
构建期泄漏3Dockerfile 注入口令、生产环境打印配置、不生效的 drop_console以为「配置了就是生效了」删打印 + 实现或删开关
工程门禁3提交钩子只有 lint、没有任何 CI、忽略规则不完整靠人眼 review装三道门

三个观察比数字更有用:

第一,21 条里没有一条是「有人故意写错」。 全部是三种动作的副产品:搬迁(整体复制)、合规(形式化落地)、赶上线(先跑通再说)。这意味着只修代码不改动作,三个月后会有一批新的。

第二,P0 的位置有个共同特征:它是被很多地方调用的工具函数。 那处加密密钥被登录、改密、重置、校验、新建用户共 5 个调用点引用。反过来说,这也是好消息——改一个文件就能提升整个系统的水位。审计时优先找这种「被 5 处以上调用的加解密/签名工具」,性价比最高。

第三,那条最危险的配置从来没被用过。 构建配置里写着 VITE_DROP_CONSOLE = true,但构建工具里压根没有实现这个开关。于是 console.log('env >>>', config) 一直留在生产包里,每次页面加载都打印一份完整配置。这次打印的内容不敏感,但它是一条「以后谁往配置里加敏感项就自动泄漏」的通道。留着一个不生效的安全配置,比没有更危险,因为它会让人误以为已经处理过了。

八、改的顺序:先轮换,再改代码

顺序错了,改法再对也会出事。按下表从下往上做,每一步都能独立回滚。

步对象前置条件回滚
6密码协议切换(去掉前端加密,或改 SM2)服务端已能接受新格式前端保留旧开关
5对称密钥轮换服务端同时支持新旧两套回退到只认旧 key
4短期凭据接口上线前后端联调通过切回静态配置
3通道口令轮换broker ACL 已改为按租户前缀授权broker 保留旧账号 24 小时
2第三方 key 轮换控制台已建新 key 并配好限制旧 key 暂不删除
1测试环境口令已通知使用方改回旧口令

四个坑,每一个都真实发生过:

  1. 先改代码后轮换。 代码改成从服务端取 key,服务端还认旧 key,中间会出现「老客户端能登、新客户端不能登」的混乱期。
  2. 只改一处。 那个加密密钥有 5 个调用点,漏一个就出现「登录正常、改密码失败」这种只在特定路径复现的问题。
  3. 轮换后不回查。 要查两件事:服务端日志里是否还有用旧 key 的请求(说明有客户端没更新)、第三方控制台的调用量是否异常(说明有人正在用你的 key)。
  4. 先清历史再轮换。 git filter-repo 会重写所有提交哈希,全员必须重新克隆。在口令还没轮换时先清历史,等于什么都没解决,只是把证据藏起来了。顺序永远是:先轮换,后清理。

九、三道门:让那一行没有地方可写

止血是删掉那一行,防复发是让它「没有地方可写」。三道门按成本从低到高。

9.1 第一道:提交前(本地,零成本)

#!/bin/sh
# .husky/pre-commit
pnpm exec lint-staged

# 只扫暂存区,命中即阻断提交;误报写进 .gitleaks.toml 白名单
if command -v gitleaks >/dev/null 2>&1; then
  gitleaks protect --staged --redact --verbose || {
    echo "检测到疑似密钥,提交已阻断。"
    exit 1
  }
fi

9.2 第二道:CI(覆盖全仓与全历史)

# .gitlab-ci.yml 片段
secret-scan:
  stage: test
  image: zricethezav/gitleaks:latest
  script:
    - gitleaks detect --source . --redact --verbose --no-banner
  allow_failure: false

除了通用规则,把本项目的高风险形态固化成自定义规则,命中率会明显提高:

# .gitleaks.toml —— 前端特有的形态,通用规则覆盖不到
[[rules]]
id = "frontend-symmetric-key"
description = "前端源码中的对称加密密钥"
regex = '''(?i)(sm4key|aeskey|cipheriv|secretkey)\s*[:=]\s*['"][0-9a-f]{32}['"]'''
tags = ["crypto", "frontend"]

[[rules]]
id = "map-web-service-key"
description = "服务端型地图 key 不应出现在前端"
regex = '''(?i)(webservice\w*key|serverkey)\s*[:=]\s*['"][0-9a-f]{32}['"]'''
tags = ["api-key"]

工具选型不用纠结:gitleaks 适合全历史与暂存区扫描,trufflehog 会实际验证凭据是否可用(适合 CI 卡口,误报少但慢),detect-secrets 适合先建基线、之后只报新增,secretlint 适合按项目规则接入。四个都是活跃维护的开源项目,装一个就比不装强。

9.3 第三道:上线前(扫产物,不看源码)

# 产物里不该出现的四类东西,期望全部零命中
grep -rniE "sk_live_|AKIA[0-9A-Z]{16}|sm4key|aesKey" dist
grep -rE "192\.168\.[0-9]+\.[0-9]+|10\.[0-9]+\.[0-9]+\.[0-9]+" dist
grep -c "env >>>" dist/assets/entry/*.js
ls dist/**/*.map 2>/dev/null    # 生产是否发布了 sourcemap

再加两条人工验收:用非白名单域名调用一次地图接口,应该被拒;用匿名身份读一次别人的数据,应该失败。这两条的判据不是「key 藏好了没」,而是「拿着它能不能越权」。

十、上线前 12 条自查

#一句话验收动作
01同一密码连续登录两次,请求体密文不同(不是 ECB)
02抓包拿到的登录密文,重放一次应该被拒(nonce 生效)
03前端源码与产物里搜不到任何对称加密 key
04服务端存的是 Argon2id / bcrypt 哈希,不是明文或 MD5
05登录请求体里的密码字段,在监控平台显示为 ***
06全站强制 HTTPS,HSTS 已开,HTTP 请求被 301
07第三方 key 用非白名单域名调用被拒
08服务端型 key(地图 Web 服务、支付 secret)在 src 与 dist 零命中
09产物里无内网地址、无配置打印、未发布 sourcemap
10提交钩子能拦住一个故意写进 .env 的假密钥
11CI 全历史扫描为绿,且失败会阻断合并
12每个生产 key 都有台账:用途、限制方式、轮换人、上次轮换日期

第 12 条最像流程、最不技术,但它决定了前三道门会不会在半年后变成摆设。

十一、小结

三句话收尾:

  • 前端没有秘密。 判断一个东西能不能放前端,不要问「藏得够不够深」,要问「被别人拿去能干什么」。
  • 密码不要在前端加工。 对称加密的 key 同路,哈希的摘要就是密码。要么 HTTPS 直传由服务端存哈希,要么用 SM2 公钥加 nonce——除此之外的第三条路都是自我安慰。
  • 密钥要么别要,要么短期。 能下沉到服务端的下沉,不能的走 BFF 或短 TTL 凭证,剩下的才轮到「受限的可公开 key」,而且必须配齐域名限制、配额与账单告警。

这件事还有一层不太好听但真实的原因:硬编码密钥的危险不只在于「能被利用」,还在于「你无法证明它没被利用」。产物里躺了两年的 key,你不知道有没有人搜过。所以发现之后的第一动作永远是轮换,而不是先研究影响面——研究可以并行,轮换不能等。

你们项目里有没有那种「加了密但等于没加」的登录?或者某个 VITE_ 变量其实一直是公开的?评论区聊聊,我最想听的是第二种——它通常要等一次外部通报才会被发现。

参考资料: