mohelobeid/jwt-auditor

# jwt-auditor 一款命令行工具，用于解码 JSON Web Token 并对其进行审计，查找那些在真实系统中反复出现的错误：`alg: none` 降级攻击、弱 HMAC 密钥、RS256 到 HS256 的混淆攻击、永不过期的 token，以及被塞进 payload 中的密钥。 所有操作均针对 token 字符串在离线状态下运行。没有网络调用，也不依赖 PyJWT。签名相关代码仅使用标准库中的原生 `hmac`，因为了解“验证”实际上仅仅是“重新计算 HMAC 并进行比较”，是理解为何这类攻击中有一半能够奏效的最快途径。 ``` $ jwt-auditor audit eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiJ9.abc... ╭─── JWT Audit Summary ────╮ │ algorithm : HS256 │ │ risk score : 10.0 / 10 │ │ worst finding: critical │ ╰──────────────────────────╯ CRITICAL HMAC secret recovered from wordlist secret = 'secret' HIGH Payload may contain sensitive data ['user_password'] MEDIUM No expiration claim payload has no 'exp' ``` ## 为什么它很有用 JWT 无处不在：session token、API 密钥、OAuth access token、服务间身份验证。它们也很容易出错，而且这些错误往往是隐蔽的。一个使用密钥 `secret` 签名的 token 与一个使用 256 位随机密钥签名的 token 看起来毫无二致，直到有人拿字典对它进行破解。 这个工具以攻击者的视角来检查 token，然后告诉你防御者应该修复什么。将你从应用、预发布环境、或你已授权测试的漏洞赏金目标中获取的 token 提供给它，它就能一次性标出所有问题。 ## 功能 - **解码** 任何 JWT，还原其 header、payload 和 signature，且不会盲目信任它 - **`alg: none` 检测**，经典的签名剥离降级攻击 - **弱密钥破解**，支持使用内置列表或你自己的字典 - **RS256 到 HS256 混淆测试**，当你提供服务器的 public key 时，它能验证该漏洞 - **过期检查**：缺失 `exp`、已经过期，或具有可疑的超长有效期 - 对 `iat` 和 `nbf` 的 **时钟合理性检查** - **敏感数据检测**，捕获在 claim 中携带的密码和 PII - 针对 `iss`、`aud` 和 `sub` 的 **缺失 claim 提示** - **JSON 输出** 和 `--fail-level` 退出代码，使其可直接作为 CI 门禁 ## 教育价值 构建和阅读本项目将教会你： - JWT 的实际结构，深入剖析到不带 padding 的 base64url - 为什么 `alg: none` 在 2015 年左右的许多库中是一个真实存在的漏洞，以及为什么永远不要让 token 自行选择验证算法 - RS256 到 HS256 的混淆攻击是如何将 public key 变为签名密钥的 - 为什么 HMAC 验证必须使用恒定时间比较 - 哪些内容应该放在 token 中，哪些永远不该放，因为 payload 只是经过编码，并未加密 `learn/` 文件夹详细介绍了所有这些内容，从基础概念到逐行代码解析。 ## 前置条件 - **Python 3.12 或更高版本** - **[uv](https://github.com/astral-sh/uv)** 用于依赖管理。这也是本仓库标准化使用的工具。 - 对终端有基本的操作熟练度。你只需粘贴一个 token，然后阅读表格。 有帮助但非必需：熟悉 base64、HMAC 以及 bearer token 的概念。 ## 安装说明 ``` # 从项目目录 cd PROJECTS/beginner/jwt-auditor # 创建环境并安装工具以及 dev dependencies uv sync --all-extras # 确认它运行 uv run jwt-auditor --help ``` ## 运行说明 该工具包含三个命令：`decode`、`audit` 和 `crack`。每个命令都可以通过参数、`--input-file` 或 stdin 读取 token，因此可以轻松融入 pipeline。 ### 解码 token ``` uv run jwt-auditor decode eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhbGljZSJ9.sig ``` 添加 `--json` 以获取机器可读的输出。`decode` 永远不会检查签名。它只向你展示 token 所声明的内容。 ### 审计 token ``` # 使用内置 wordlist 运行每个检查 uv run jwt-auditor audit # 使用你自己的 wordlist 进行 secret check uv run jwt-auditor audit --wordlist rockyou.txt # 使用服务器公钥证明 RS 到 HS 混淆攻击 uv run jwt-auditor audit --public-key server_pub.pem # 在 medium 或更严重时使进程失败，用于 CI uv run jwt-auditor audit --fail-level medium ``` 通过管道传入 token，避免其落入你的 shell 历史记录中： ``` echo "$TOKEN" | uv run jwt-auditor audit ``` ### 破解 HMAC 密钥 ``` uv run jwt-auditor crack --wordlist rockyou.txt ``` 如果命中则返回退出代码 0 并打印密钥，如果没有匹配项则返回退出代码 1。 ## 配置 没有配置文件或环境变量。所有行为均通过 flag 控制： | Flag | Command | Meaning | |------|---------|---------| | `--input-file`, `-i` | all | 从文件读取 token | | `--json` | decode, audit | 输出 JSON 而不是表格 | | `--wordlist`, `-w` | audit, crack | 针对 HS token 尝试的密钥列表 | | `--public-key`, `-p` | audit | 用于测试算法混淆的 public key PEM | | `--max-lifetime` | audit | token 被视为长期有效的小时数阈值（默认 24） | | `--fail-level` | audit | 达到此严重级别或更严重时以非零状态退出（默认 `high`） | ## 架构 处理流程非常精简且单向： ``` token string │ ▼ decoder.py split into 3 parts, decode header and payload │ ▼ checks.py run each check, collect Finding objects │ (calls signatures.py for the secret and confusion checks) ▼ models.py AuditReport scores the findings │ ▼ output.py render a Rich table or JSON ``` 这些检查逻辑从不进行打印操作，也不导入 Rich，因此很容易对它们进行独立测试。有关完整的详细解析，请参阅 `learn/02-ARCHITECTURE.md`。 ## 安全注意事项 - **仅测试你获得授权的 token。** 破解你不拥有的系统的密钥不属于授权的安全测试。 - **Token 即凭证。** 相比于将活跃的 token 作为 shell 参数粘贴（这会导致其留在你的历史记录和进程列表中），优先选择通过 stdin 或文件输入。 - 本工具不验证 RSA 或 ECDSA 签名。它仅对其进行解码并针对算法处理方式发出警告。其核心目的是审计配置，而非充当用于生产环境流量的完整 JOSE 验证器。 ## 运行测试 ``` uv run pytest tests/ -v # 59 tests uv run pytest --cov=jwt_auditor # coverage uv run ruff check src/ tests/ # lint uv run mypy src/ # types ``` ## 许可证 基于 GNU Affero General Public License v3.0 发布。详见 [LICENSE](./LICENSE)。

标签：JWT, StruQ, 动态分析, 安全规则引擎, 密码学, 手动系统调用, 逆向工具