kdairatchi/flaw

文档 • 安装 • 快速开始 • GitHub Action • 规则 • 贡献 • 更新日志

flaw 读取你的 Crystal 源码并将其置于光下检查。每条规则都会查找特定的安全缺陷——硬编码密钥、命令注入漏洞、通过插值构建的 SQL、用于令牌的弱随机性、不可信的 YAML 加载等。发现结果会显示文件与行号，并可以输出为 JSON 或 SARIF 格式供 CI 和 GitHub Code Scanning 使用。

功能特性

### 扫描 - 83 条内置规则，涵盖安全、AI 冗余、设计令牌和可访问性——请查看 [`rules/`](rules/README.md) - 每条规则均可通过 `.flaw.yml` 或 CLI 标志覆盖严重性、路径忽略以及标签包含/排除 - 支持基于 `--since ` 的增量扫描（仅报告自指定 git 引用以来更改的文件/行） - 基线（`flaw baseline` 与 `--baseline .flaw-baseline.json`）用于仅拦截新发现 - `--fix` 可用于安全自动修复（例如弱哈希升级） - `--verify-secrets` 可探测提供者 API（AWS、GitHub）以验证 FLAW002 匹配 - 默认递归扫描 `.cr` 文件目录，跳过 `lib/` 与 `spec/` ### 命令 - `scan` — 分析代码并输出发现结果 - `browse` — 交互式 TUI 分拣（fzf + bat + 可选 tmux 弹出窗口） - `baseline` — 拍摄当前发现的快照，以便后续扫描忽略它们 - `audit` — 扫描 `shard.lock`，查找已知 CVE 的 shard - `rules` / `lint-rules` — 列出规则或验证 CI 中的 `rules/` 契约 - `init config` / `init rule` — scaffold 一个 `.flaw.yml` 或新建规则文件夹 - `regex` / `doctor` — 编写规则正则表达式并诊断环境 ### 输出 - 彩色输出，按文件分组并附带代码片段 - 用于流水线与代理的 JSON 格式 - 用于 GitHub Code Scanning 上传的 SARIF 2.1.0 ### 集成 - 单一静态二进制文件，零运行时依赖 - 可复用的 GitHub Action（`uses: kdairatchi/flaw@v0.1.0`） - 发现达到阈值时非零退出

## 安装 ### 从源码构建 ``` git clone https://github.com/kdairatchi/flaw.git cd flaw shards build --release --no-debug --production ./bin/flaw version ``` ### Homebrew（预计随 v0.1.0 发布） ``` brew install kdairatchi/tap/flaw ``` ### 预编译二进制文件 从 [发布页面](https://github.com/kdairatchi/flaw/releases) 下载 — `linux-amd64`、`linux-arm64`、`macos-arm64`。 ## 快速开始 ``` flaw scan . # scan current directory, pretty output flaw scan src/ --format json # JSON for agents / pipelines flaw scan . --format sarif > flaw.sarif flaw scan . --fail-on high # CI: exit 1 if any high+ finding flaw scan . --since HEAD~1 --since-lines # only findings on lines changed since HEAD~1 flaw scan . --include-tag security # only run rules tagged 'security' flaw scan . --fix # apply safe autofixes in place flaw scan . --verify-secrets # live-probe AWS/GitHub keys from FLAW002 flaw browse src/ # interactive TUI triage (fzf + bat) flaw browse --tmux popup src/ # open picker in a tmux popup flaw baseline # snapshot current findings to .flaw-baseline.json flaw scan --baseline .flaw-baseline.json # suppress baselined findings flaw audit # scan shard.lock for known CVEs flaw doctor # diagnose Crystal version, AST backend, config flaw regex test '(?i)secret' input.cr # interactively tune rule regexes flaw rules # list built-in rules, grouped by tag flaw rules FLAW001 # show rule detail flaw lint-rules # validate rules/ directory contract flaw init config # drop a .flaw.yml config stub flaw init rule FLAW200 my-new-rule # scaffold a new rule folder + detector ``` ## GitHub Action ``` # .github/workflows/flaw.yml name: flaw on: [push, pull_request] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: kdairatchi/flaw@v0.1.0 with: args: scan . --fail-on high --format sarif > flaw.sarif - uses: github/codeql-action/upload-sarif@v3 with: sarif_file: flaw.sarif ``` ## 规则 flaw 提供了 **83 条规则**，分为两个 ID 范围。完整目录、严重性、标签、CWE 与 OWASP 映射请参考 [`rules/README.md`](rules/README.md)。 ### 安全规则（`FLAW0xx`）——24 条 真实漏洞。默认严重性为中等及以上；适用于 CI 中的 `--fail-on high`。 | ID | 严重性 | 缺陷 | |---|---|---| | [`FLAW001`](rules/FLAW001/README.md) | critical | 从字符串插值构建的命令 | | [`FLAW002`](rules/FLAW002/README.md) | high | 硬编码的密钥字面量 | | [`FLAW003`](rules/FLAW003/README.md) | high | 通过插值或连接构建的 SQL | | [`FLAW009`](rules/FLAW009/README.md) | high | 用于密码或完整性的弱哈希（MD5/SHA1） | | [`FLAW011`](rules/FLAW011/README.md) | high | 对用户可控 URL 的出站 HTTP 请求（SSRF） | | [`FLAW014`](rules/FLAW014/README.md) | high | 未禁用外部实体的 XML 解析（XXE） | | [`FLAW022`](rules/FLAW022/README.md) | high | 未规范化的归档条目提取（zip-slip） | | [`FLAW023`](rules/FLAW023/README.md) | critical | 启用了 `alg:none` 或验证被禁用的 JWT | | [`FLAW024`](rules/FLAW024/README.md) | high | CORS 通配符 / 回显来源并携带凭证 | | …以及另外 15 条 | | 请参见 [`rules/README.md`](rules/README.md) | ### `FLAW1xx` —— 卫生、AI 冗余、供应链与 LLM 应用规则 ——59 条 这是一个新领域：捕获 vibe-coded AI 粘贴、LLM 应用隐患（提示词角色注入、未封闭的工具结果、用户控制的 `max_tokens`）、MCP/Agent 供应链风险，以及设计/可访问性令牌漂移。分组包括： | 组别 | 范围 | 示例 | |---|---|---| | AI 冗余卫生 | `FLAW100`–`FLAW108` | 叙述性注释、助理样板文本、占位符、未完成的存根、静默 rescue、注释掉的认证 | | 设计 / 可访问性 | `FLAW106`、`FLAW109`、`FLAW111`、`FLAW118`–`FLAW121`、`FLAW127`–`FLAW131` | 原始颜色字面量、对比度失败、混合 CSS 单位、缺少 alt/lang、Tailwind 冲突 | | 安全接收器 | `FLAW112`–`FLAW117`、`FLAW122`–`FLAW126`、`FLAW132`–`FLAW148` | 动态 eval、DOM XSS、SSTI、原型污染、Log4Shell、NoSQL 注入、日志中的 PII、生产环境调试、云元数据、LOLBIN、不安全的 GitHub Actions、开放的安全组、发布的 source map | | LLM / MCP | `FLAW149`–`FLAW157` | 未固定版本的 MCP 源、本地项目配置授予执行权限、角色注入、未封闭的工具结果、用户控制的 `max_tokens`、非字面量的工具处理程序 URL、提交的 AI 工具配置 | 每条规则都位于 [`rules/`](rules/) 下的独立文件夹中，包含检测器、漏洞示例（`bad.cr`）、修复版本（`good.cr`）、元数据（`rule.yml`）与文档。可通过 `flaw init rule FLAW200 my-rule` 新增规则。 ## 规则验证器 `flaw lint-rules` 强制执行规则契约——确保每个文件夹匹配 `FLAWNNN`、包含所有四个必需文件、`rule.yml` 可解析并具备所需键、存在检测器文件，且每个 `bad.cr` 与 `good.cr` 行为符合声明。在 CI 中运行它，作为规则贡献的守门人。 ## 配置 项目根目录下的 `.flaw.yml`： ``` version: 1 exclude: - spec/ - lib/ - vendor/ rules: FLAW002: ignore: - "examples/fake-keys.cr" FLAW004: severity: critical FLAW005: disabled: true ``` ## 路线图 - **v0.2** — 新增 10 条规则，`--fix` 对简单情况的自动修复，更完善的 SARIF 来源信息 - **v0.3** — LSP 服务器（在编辑器中实时显示缺陷） - **v0.4** — 基线文件（仅拦截新发现） - **v0.5** — 自定义规则 DSL（YAML 中的社区规则） -v0.6** — 跨文件污点追踪（源 → 汇） - **v1.0** — 插件系统，托管规则文档位于 [`flaw.prowlrbot.com`](https://flaw.prowlrbot.com)（落地页位于 [`docs/`](docs/) — 通过 GitHub Pages 使用 `main` / `/docs` 启用），Caido 集成 ## 命名由来 在宝石学中，**flaw** 指晶体内部的裂缝、包裹体或瑕疵——训练有素的眼睛能通过捕捉光线发现它。flaw 对 Crystal 代码做同样的事：将你的程序置于光下，在他人发现之前展示出裂缝。 ## 安全 如发现潜在漏洞，请私下报告——参见 [SECURITY.md](SECURITY.md)。 ## 许可证 MIT © [kdairatchi](https://github.com/kdairatchi)

标签：AI红队测试, API安全, Crystal语言, GitHub Action, JSON输出, SARIF, SEO: Crystal静态分析, SEO: 安全扫描工具, SEO: 开源安全扫描, 不安全的YAML加载, 云安全监控, 云计算, 命令注入, 基线管理, 增量扫描, 威胁情报, 安全扫描, 安全漏洞检测, 开发者工具, 开源安全工具, 弱随机数, 时序注入, 源码分析, 硬编码密钥, 自动修复, 规则引擎, 逆向工程平台, 静态分析