canship 0.2.1 → 0.3.0

package/README-zh-CN.md

@@ -1,12 +1,14 @@
 # canship
 
-面向 JavaScript / TypeScript 项目的本地静态扫描器，检测凭据暴露和访问控制配置错误。不执行项目代码，不上传文件，扫描过程不联网。
+面向 JavaScript / TypeScript 项目的本地静态扫描器，检测凭据暴露与访问控制配置错误。扫描不执行项目代码、不上传文件、不联网。
+
+本文档对应 0.3.x，适用于匹配的 [npm 版本](https://www.npmjs.com/package/canship) 或本地构建。
 
 ```powershell
 npx canship .
 ```
 
-要求 Node.js ≥18，无运行时依赖。Git 用于读取本地历史；仓库中无法使用 Git 时，扫描标记为未完成。首次使用 `npx` 可能需要从 npm 下载软件包。
+要求 Node.js ≥18，无运行时依赖。`npx` 可能联网下载软件包；扫描仅使用本地文件与 Git 历史。Git 仓库中无法调用 Git 时，扫描标记为未完成。
 
 [English](./README.md)
 
@@ -16,18 +18,18 @@ npx canship .
 |---|---|
 | 硬编码凭据、私钥及含密码的数据库连接串 | P0 |
 | 公开环境变量中的私密值 | P0 |
-| 客户端可访问的 Supabase 管理员密钥 | P0 |
+| Supabase 管理员密钥暴露至客户端 | P0 |
 | Git 跟踪及历史 `.env` 文件中的凭据或疑似私密值 | P0 |
-| Supabase 表未启用行级安全（RLS） | P1 |
+| Supabase 迁移记录中未启用行级安全（RLS）的表 | P1 |
 | Firebase 无条件访问及固定日期测试规则 | P1 |
-| Next.js API 数据操作缺少鉴权 | P0 / P1 |
+| Next.js API 数据操作未识别到鉴权 | P0 / P1 |
 | 携带凭据的 CORS 来源回显或通配符配置 | P1 / P2 |
 
-识别 OpenAI、Anthropic、AWS、Stripe、GitHub、npm、Slack、SendGrid 等凭据格式及常见前端框架的公开环境变量前缀。API 鉴权检查限于 Next.js 的 `/api` 处理函数，支持 App Router、Pages Router、路由组和工作区应用。
+支持 OpenAI、Anthropic、AWS、Stripe、GitHub、npm、Slack、SendGrid 等凭据格式及常见前端公开环境变量前缀。API 鉴权检查仅覆盖 Next.js `/api`，支持 App Router、Pages Router、路由组和工作区应用。
 
-置信度分为确定（`certain`）和疑似（`likely`）。默认只展示确定结果；隐藏的疑似结果仍影响退出码。
+置信度分为确定（`certain`）和疑似（`likely`），仅描述静态证据，不验证凭据有效性或线上状态。默认只展示确定结果；隐藏的疑似结果仍影响退出码。
 
-## 参数
+## 用法
 
 省略路径时扫描当前目录。
 
@@ -35,32 +37,79 @@ npx canship .
 |---|---|
 | `-a`, `--all` | 展示疑似结果 |
 | `--json` | 输出 JSON |
-| `--fix-prompt` | 输出编程助手修复指令及独立的人工操作清单 |
-| `--report[=文件]` | 写入 HTML 报告，默认 `canship-report.html` |
-| `--sarif[=文件]` | 写入 SARIF 2.1.0 报告，默认 `canship.sarif` |
+| `--fix-prompt` | 输出修复指令及独立的人工操作清单 |
+| `--report[=file]` | 写入 HTML，默认 `canship-report.html` |
+| `--sarif[=file]` | 写入 SARIF 2.1.0，默认 `canship.sarif` |
 | `--best-effort` | 无结果时，允许不完整扫描退出 `0` |
-| `--baseline[=文件]` | 应用基线，默认 `canship-baseline.json` |
-| `--baseline-write[=文件]` | 记录当前结果为基线后退出 |
-| `--only=规则` | 仅执行匹配规则，支持逗号分隔及重复参数 |
-| `--skip=规则` | 排除匹配规则，支持逗号分隔及重复参数 |
+| `--baseline[=file]` | 应用基线，默认 `canship-baseline.json` |
+| `--baseline-write[=file]` | 写入当前结果为基线后退出，同上默认路径 |
+| `--only=ids` | 仅执行匹配规则，支持逗号分隔及重复参数 |
+| `--skip=ids` | 排除匹配规则，支持逗号分隔及重复参数 |
 | `--no-config` | 忽略项目配置 |
+| `--list-rules` | 列出规则及限制，不扫描；支持 `--json` |
+| `--no-excerpts` | 所有报告省略源码摘录，不改变结果和退出码 |
 | `-h`, `--help` | 显示帮助 |
 | `-v`, `--version` | 显示版本 |
 
-`--json` 与 `--fix-prompt` 互斥；HTML 和 SARIF 可与任一输出模式组合。报告正文为英文，各格式均用 `--all` 包含疑似结果。
+`--json` 与 `--fix-prompt` 互斥；HTML、SARIF 可与任一模式组合。报告正文为英文，`--all` 对所有格式生效。
 
 ### 退出码
 
 | 退出码 | 含义 |
 |---|---|
-| `0` | 无结果且扫描完整，或由 `--best-effort` 接受不完整扫描 |
+| `0` | 无结果，且扫描完整或由 `--best-effort` 接受不完整扫描 |
 | `1` | 存在 `certain` 的 P0/P1 结果 |
 | `2` | 存在其他结果，包括被隐藏的 `likely` |
 | `3` | 参数或工具错误，或未被接受的不完整扫描 |
 
-结果对应的退出码优先于不完整状态；`--best-effort` 不改变 `1` 或 `2`。JSON 用 `partial`、`errors`、`skipped` 保留完整性信息，SARIF 提供执行状态和诊断通知。
+结果退出码优先于不完整状态；`--best-effort` 不改变 `1` 或 `2`。
+
+### 机器可读输出
+
+JSON 使用独立于包版本的 `schemaVersion: 1`，npm 包附带 [结构定义](./schemas/scan-report-v1.schema.json)。调用方应兼容新增字段、拒绝不支持的结构版本；`--list-rules --json` 为独立的 `kind: "rule-catalog"` 文档。
+
+`findings` 为抑制和筛选后的结果；`hiddenLikely`、`baselineSuppressed`、`baselineStale` 提供相关统计。完整性需另查 `partial`、`errors`、`skipped`、`filesScanned`；SARIF 提供执行状态与诊断通知。
+
+## GitHub Action
+
+保存为 `.github/workflows/canship.yml`，在推送和 PR 时扫描并生成统计摘要。安装扫描器需要联网，扫描不联网；不安装或执行项目依赖，默认不上传 SARIF。
+
+示例固定 Action 提交，安装 npm 版 `0.2.1`；`version` 不使用仓库中的未发布源码。Action 兼容 0.2.1 无 `schemaVersion` 的报告。
 
-## 配置与忽略
+```yaml
+name: canship
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: Tasomei/canship@37cf06e014168968a88679157564e5c489f99c50
+        with:
+          version: '0.2.1'
+```
+
+| 输入 | 默认值 | 说明 |
+|---|---|---|
+| `path` | `.` | 检出目录内的扫描路径 |
+| `version` | `0.2.1` | 精确 npm 版本，不接受范围或标签 |
+| `fail-on` | `blocking` | `blocking`：确定的 P0/P1；`any`：全部结果；`none`：仅报告结果 |
+| `only` / `skip` | 未设置 | 互斥，逗号分隔的规则选择器 |
+| `baseline` | 未设置 | 相对扫描目录的已有基线 |
+| `use-config` | `false` | 启用项目配置 |
+| `upload-sarif` | `false` | 上传 SARIF 至 GitHub 代码扫描 |
+| `category` | `canship` | 每个扫描目标使用独立分类 |
+
+输出：`exit-code`、`findings`、`blocking`、`partial`。策略统计包含疑似结果，基线与忽略仍生效；扫描不完整、工具错误或报告不兼容始终失败，包括 `fail-on: none`。
+
+上传 SARIF 需 `security-events: write` 及 [GitHub 代码扫描支持](https://docs.github.com/en/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/upload-sarif-file)，Fork PR 可能无权限。上传前审阅报告中的路径与详情；不可信 PR 使用 `pull_request`，不要使用 `pull_request_target`。Action 为后续步骤设置 Node.js 22，需要其他版本时应使用独立扫描任务。
+
+## 配置与基线
 
 扫描目录中的 `canship.config.json` 支持 `baseline`、`only`、`skip`、`all`：
 
@@ -71,18 +120,20 @@ npx canship .
 }
 ```
 
-命令行参数优先；`only` 与 `skip` 互斥，接受完整规则 ID 或命名空间。无关规则不执行；`ruleSelection.removed` 仅统计已执行规则中被过滤的结果。扫描不可信项目时使用 `--no-config`；`bestEffort` 仅支持命令行设置。
+命令行参数优先；`only`、`skip` 互斥，接受规则 ID 或命名空间。未选规则不执行，`ruleSelection.removed` 仅统计已执行规则中被过滤的结果。扫描不可信项目时使用 `--no-config`；`bestEffort` 仅限命令行设置。
+
+### 忽略标记
 
-以独占注释行的 `canship-ignore-file` 排除整个文件，或用 `canship-ignore-next-line` 忽略下一行。后者可附加规则 ID：
+独占注释行的 `canship-ignore-file` 排除整个文件；`canship-ignore-next-line` 忽略下一行，可附规则 ID：
 
 ```ts
 // canship-ignore-next-line cors/wildcard-with-credentials
 const corsOptions = { origin: '*', credentials: true }
 ```
 
-报告披露忽略、筛选和基线抑制信息。主动忽略不使扫描标记为未完成。
+报告披露忽略、规则筛选和基线抑制信息；主动排除不标记为未完成。
 
-## 基线
+### 基线
 
 记录已有结果：
 
@@ -96,21 +147,22 @@ npx canship --baseline-write
 npx canship --baseline
 ```
 
-裸参数使用扫描目录，显式路径相对工作目录。写入成功退出 `0`；扫描不完整或启用规则筛选时会提示。
+默认基线位于扫描目录，显式路径相对工作目录。写入成功退出 `0`，不代表无问题；扫描不完整或启用规则筛选时会提示。
 
-基线格式为第 2 版，不含源码摘录，但披露路径、规则、标题和问题类型，提交前需审阅。指纹不含行号，移动行号不会产生新结果，替换凭据会。缺失、损坏及第 1 版基线均退出 `3`。
+基线格式为 v2，移动行号不改变指纹，替换凭据会改变。缺失、损坏及 v1 基线均退出 `3`。基线不含源码，但包含路径、规则和问题描述，提交前需审阅。
 
-## 限制
+## 隐私与限制
 
-- 静态启发式分析可能误报或漏报，不验证运行时行为、限流、注入、依赖漏洞及业务授权。无发现不代表项目安全。
-- 脱敏仅覆盖已识别格式；未知秘密可能出现在证据行中，报告应作为内部材料。Google/Firebase/Maps 的 `AIza...` 值按公开标识符处理。
-- 单文件最多读取 2 MiB；单次累计读取最多 128 MiB、10,000 个文件；目录最多 16 层。跨规则每文件最多输出 100 条结果，优先保留高严重度、高置信度结果。
-- Git 历史每文件最多检查 100 个相关版本，单条 Git 命令超时为 30 秒。超限或超时均披露检查缺口。
-- 不跟随符号链接；嵌套仓库及子模块需分别扫描。扫描范围内的跳过项使扫描未完成，已排除的构建和依赖目录除外。
+- 静态分析可能误报或漏报，不验证线上行为，不覆盖限流、注入、依赖漏洞或业务授权。无结果不等于安全。
+- 脱敏仅覆盖已识别格式，未知秘密可能出现在源码摘录中。`--no-excerpts` 省略摘录，JSON 以 `excerptsOmitted` 标明；路径、名称、说明及基线不匿名化，分享前仍需审阅。
+- Google/Firebase/Maps 的 `AIza...` 值按公开标识符处理，不单凭其值判定泄露。
+- 读取上限：单文件 2 MiB，单次 128 MiB、10,000 个文件，目录 16 层。每文件跨规则最多 100 条结果，优先保留高严重度、高置信度结果。
+- Git 历史每文件最多 100 个相关版本，单条 Git 命令超时 30 秒。超限、超时均报告检查缺口。
+- 不跟随符号链接；嵌套仓库、子模块需单独扫描。范围内跳过项使扫描未完成，内置排除的构建和依赖目录除外。
 
 ## 开发
 
-检测规则需同时包含应检出和不应检出的用例，参见 [测试夹具](./test/fixtures/)。
+新增规则需包含应检出与不应检出的 [测试用例](./test/fixtures/)。
 
 ```powershell
 npm ci
@@ -120,6 +172,28 @@ npm ci
 npm run prepublishOnly
 ```
 
+离线评估：
+
+```powershell
+npm run evaluate
+```
+
+评估集含 10 个构造用例、9 个固定版本上游示例及变体，同时纳入 `npm test`；[来源与许可](./test/fixtures/evaluation/) 随样本保存。断言覆盖规则、文件、严重度、置信度与扫描完整性，不代表真实项目检出率。
+
+另有 5 个 [应用目录快照](./test/evaluation/projects.json)。准备阶段联网并校验 Git 对象摘要，目标须为 Git 仓库外的新目录：
+
+```powershell
+node scripts/fetch-evaluation-projects.mjs "$env:TEMP/canship-evaluation"
+```
+
+随后离线评估，不安装或运行样本依赖：
+
+```powershell
+npm run evaluate:projects -- "$env:TEMP/canship-evaluation"
+```
+
+CI 使用同一评估集，不验证 Git 历史或线上行为。
+
 ## 许可
 
-[MIT](./LICENSE)
+[MIT](./LICENSE)。Supabase、Firebase 样本保留 Apache-2.0，Next.js、`cors` 样本保留 MIT；各样本附来源及许可证。

package/README.md

@@ -1,12 +1,14 @@
 # canship
 
-A local static scanner for JavaScript and TypeScript projects. Detects exposed credentials and access-control misconfigurations without executing project code, uploading files, or making network requests during scans.
+A local static scanner for JavaScript and TypeScript projects. Detects exposed credentials and access-control misconfigurations. Scans do not execute project code, upload files, or use the network.
+
+This documentation covers 0.3.x: use a matching [npm version](https://www.npmjs.com/package/canship) or local build.
 
 ```powershell
 npx canship .
 ```
 
-Requires Node.js ≥18; no runtime dependencies. Git is used for local history checks. Unavailable Git in a repository makes the scan incomplete. On first use, `npx` may download the package from npm.
+Requires Node.js ≥18; no runtime dependencies. `npx` may download the package; scans use only local files and Git history. Unavailable Git in a repository marks the scan incomplete.
 
 [简体中文](./README-zh-CN.md)
 
@@ -16,18 +18,18 @@ Requires Node.js ≥18; no runtime dependencies. Git is used for local history c
 |---|---|
 | Hardcoded credentials, private keys, and database URLs containing passwords | P0 |
 | Private values in public environment variables | P0 |
-| Client-accessible Supabase admin keys | P0 |
+| Supabase admin keys exposed to clients | P0 |
 | Credentials or suspected private values in Git-tracked and historical `.env` files | P0 |
-| Supabase tables without Row Level Security (RLS) | P1 |
+| Supabase tables without Row Level Security (RLS) in migrations | P1 |
 | Firebase unconditional access and date-based test rules | P1 |
-| Next.js API data operations without authentication | P0 / P1 |
+| Next.js API data operations without recognised authentication | P0 / P1 |
 | Credentialed CORS with reflected or wildcard origins | P1 / P2 |
 
-Recognises OpenAI, Anthropic, AWS, Stripe, GitHub, npm, Slack, SendGrid, and other credential formats, plus common frontend public environment prefixes. API authentication checks cover Next.js `/api` handlers, including App Router, Pages Router, route groups, and workspace applications.
+Supports OpenAI, Anthropic, AWS, Stripe, GitHub, npm, Slack, SendGrid, and other credential formats, plus common frontend public environment prefixes. API authentication checks cover only Next.js `/api`: App Router, Pages Router, route groups, and workspace applications.
 
-Confidence is `certain` or `likely`. Only certain findings are shown by default; hidden likely findings still affect the exit code.
+Confidence is `certain` or `likely`, describing static evidence rather than credential validity or deployed state. Only certain findings are shown by default; hidden likely findings still affect the exit code.
 
-## Options
+## Usage
 
 Omitting the path scans the current directory.
 
@@ -35,32 +37,79 @@ Omitting the path scans the current directory.
 |---|---|
 | `-a`, `--all` | Include likely findings |
 | `--json` | Output JSON |
-| `--fix-prompt` | Output assistant instructions and separate manual actions |
+| `--fix-prompt` | Output remediation instructions and separate manual actions |
 | `--report[=file]` | Write HTML; default: `canship-report.html` |
 | `--sarif[=file]` | Write SARIF 2.1.0; default: `canship.sarif` |
 | `--best-effort` | Permit exit `0` for an incomplete scan with no findings |
 | `--baseline[=file]` | Apply a baseline; default: `canship-baseline.json` |
-| `--baseline-write[=file]` | Record current findings as a baseline and exit |
+| `--baseline-write[=file]` | Write current findings as a baseline and exit; same default path |
 | `--only=ids` | Run matching rules; comma-separated and repeatable |
 | `--skip=ids` | Exclude matching rules; comma-separated and repeatable |
 | `--no-config` | Ignore project configuration |
+| `--list-rules` | List rules and limits without scanning; supports `--json` |
+| `--no-excerpts` | Omit source excerpts from every report; preserve findings and exit status |
 | `-h`, `--help` | Show help |
 | `-v`, `--version` | Show version |
 
-`--json` and `--fix-prompt` are mutually exclusive. HTML and SARIF may be combined with either. Reports are in English; use `--all` to include likely findings in any format.
+`--json` and `--fix-prompt` are mutually exclusive; HTML and SARIF work with either. Reports are in English. `--all` applies to every format.
 
 ### Exit codes
 
 | Code | Meaning |
 |---|---|
-| `0` | No findings and a complete scan, or an incomplete scan accepted with `--best-effort` |
+| `0` | No findings, with a complete scan or an incomplete scan accepted by `--best-effort` |
 | `1` | At least one certain P0/P1 finding |
 | `2` | Other findings, including hidden likely findings |
 | `3` | Invalid arguments, a tool error, or an unaccepted incomplete scan |
 
-Findings take precedence over incompleteness; `--best-effort` does not change `1` or `2`. JSON retains `partial`, `errors`, and `skipped`; SARIF includes execution status and diagnostic notifications.
+Finding exit codes take precedence over incompleteness; `--best-effort` does not change `1` or `2`.
+
+### Machine-readable output
+
+JSON uses `schemaVersion: 1`, independent of the package version; the npm package includes its [schema](./schemas/scan-report-v1.schema.json). Accept additive fields and reject unsupported schema versions. `--list-rules --json` is a separate `kind: "rule-catalog"` document.
+
+`findings` contains results after suppressions and filtering; `hiddenLikely`, `baselineSuppressed`, and `baselineStale` provide related counts. Check coverage separately through `partial`, `errors`, `skipped`, and `filesScanned`. SARIF includes execution status and diagnostic notifications.
+
+## GitHub Action
+
+Save as `.github/workflows/canship.yml` to scan on pushes and pull requests, with a counts-only summary. Scanner installation requires network access; scanning does not. Project dependencies are not installed or executed, and SARIF upload is disabled by default.
+
+The example pins the Action commit and installs npm version `0.2.1`; `version` does not use unreleased repository source. The Action accepts 0.2.1 reports without `schemaVersion`.
 
-## Configuration and suppressions
+```yaml
+name: canship
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: Tasomei/canship@37cf06e014168968a88679157564e5c489f99c50
+        with:
+          version: '0.2.1'
+```
+
+| Input | Default | Meaning |
+|---|---|---|
+| `path` | `.` | Directory within the checkout |
+| `version` | `0.2.1` | Exact npm version; no ranges or tags |
+| `fail-on` | `blocking` | `blocking`: certain P0/P1; `any`: all findings; `none`: findings only reported |
+| `only` / `skip` | unset | Mutually exclusive, comma-separated rule selectors |
+| `baseline` | unset | Existing baseline relative to the scanned directory |
+| `use-config` | `false` | Enable project configuration |
+| `upload-sarif` | `false` | Upload SARIF to GitHub code scanning |
+| `category` | `canship` | Distinct SARIF category for each scan target |
+
+Outputs: `exit-code`, `findings`, `blocking`, `partial`. Policies include likely findings; baselines and exclusions still apply. Incomplete scans, tool errors, and incompatible reports always fail, including with `fail-on: none`.
+
+SARIF upload requires `security-events: write` and [GitHub code scanning support](https://docs.github.com/en/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/upload-sarif-file); fork PRs may lack permission. Review paths and finding details before upload. Use `pull_request`, not `pull_request_target`, for untrusted PRs. The Action sets Node.js 22 for subsequent steps; use a separate scan job if another version is needed.
+
+## Configuration and baselines
 
 Place `canship.config.json` in the scanned directory. Supported keys: `baseline`, `only`, `skip`, `all`.
 
@@ -71,18 +120,20 @@ Place `canship.config.json` in the scanned directory. Supported keys: `baseline`
 }
 ```
 
-CLI options take precedence. `only` and `skip` are mutually exclusive and accept complete rule IDs or namespaces. Unrelated rules do not run; `ruleSelection.removed` counts only filtered findings from rules that ran. Use `--no-config` for untrusted projects. `bestEffort` is CLI-only.
+CLI options take precedence. `only` and `skip` are mutually exclusive and accept rule IDs or namespaces. Unselected rules do not run; `ruleSelection.removed` counts filtered findings only from executed rules. Use `--no-config` for untrusted projects. `bestEffort` is CLI-only.
+
+### Ignore markers
 
-A standalone comment containing `canship-ignore-file` excludes a file. `canship-ignore-next-line` suppresses the next line and accepts an optional rule ID:
+A standalone `canship-ignore-file` comment excludes a file; `canship-ignore-next-line` suppresses the next line, with an optional rule ID:
 
 ```ts
 // canship-ignore-next-line cors/wildcard-with-credentials
 const corsOptions = { origin: '*', credentials: true }
 ```
 
-Reports disclose exclusions, rule selection, and baseline suppression. Deliberate exclusions do not make the scan incomplete.
+Reports disclose exclusions, rule selection, and baseline suppression. Deliberate exclusions do not mark the scan incomplete.
 
-## Baselines
+### Baselines
 
 Record existing findings:
 
@@ -96,21 +147,22 @@ Report only new findings:
 npx canship --baseline
 ```
 
-Bare options use the scanned directory; explicit paths are relative to the working directory. A successful write exits `0`, with a warning for incomplete or selectively scanned input.
+The default baseline is in the scanned directory; explicit paths are relative to the working directory. A successful write exits `0`, regardless of findings; incomplete or selectively scanned input produces a warning.
 
-Baseline format v2 contains no source excerpts but discloses paths, rules, titles, and issue types. Review it before committing. Fingerprints exclude line numbers: moving lines preserves identity, replacing credentials changes it. Missing, malformed, and v1 baselines exit `3`.
+Baseline format v2 fingerprints survive line moves but change when credentials change. Missing, malformed, and v1 baselines exit `3`. Baselines omit source but retain paths, rules, and issue descriptions; review before committing.
 
-## Limitations
+## Privacy and limitations
 
-- Static heuristics may produce false positives or negatives. Runtime behaviour, rate limiting, injection, dependency vulnerabilities, and business authorisation are outside scope. No findings does not prove security.
-- Redaction covers recognised formats only; unknown secrets may appear in evidence. Treat reports as internal material. Google/Firebase/Maps `AIza...` values are treated as public identifiers.
-- Reads are limited to 2 MiB per file, 128 MiB and 10,000 files per scan, and 16 directory levels. Across rules, at most 100 findings per file are reported, prioritising severity and confidence.
-- Git history checks cover up to 100 relevant revisions per file. Each Git command has a 30-second timeout. Exceeded limits and timeouts are reported as incomplete coverage.
-- Symbolic links are not followed. Scan nested repositories and submodules separately. Skipped paths within scope make the scan incomplete; excluded build and dependency directories remain excluded.
+- Static analysis may produce false positives or negatives. Deployed behaviour, rate limiting, injection, dependency vulnerabilities, and business authorisation are outside scope. No findings does not prove security.
+- Redaction covers recognised formats only; unknown secrets may appear in source excerpts. `--no-excerpts` omits excerpts, recorded as `excerptsOmitted` in JSON. Paths, names, descriptions, and baselines are not anonymised; review before sharing.
+- Google/Firebase/Maps `AIza...` values are public identifiers, not evidence of a leak on their own.
+- Read limits: 2 MiB per file, 128 MiB and 10,000 files per scan, 16 directory levels. At most 100 findings per file across rules, prioritising severity and confidence.
+- Git history checks cover up to 100 relevant revisions per file, with a 30-second timeout per Git command. Exceeded limits and timeouts report coverage gaps.
+- Symbolic links are not followed; scan nested repositories and submodules separately. Skipped paths within scope mark the scan incomplete; built-in build and dependency exclusions do not.
 
 ## Development
 
-Detection rules require positive and negative cases; see [test fixtures](./test/fixtures/).
+New rules require positive and negative [test cases](./test/fixtures/).
 
 ```powershell
 npm ci
@@ -120,6 +172,28 @@ npm ci
 npm run prepublishOnly
 ```
 
+Offline evaluation:
+
+```powershell
+npm run evaluate
+```
+
+The corpus has 10 synthetic cases and nine pinned upstream examples and mutations, also run by `npm test`. [Sources and licences](./test/fixtures/evaluation/) accompany the fixtures. Assertions cover rules, files, severity, confidence, and coverage, not real-world detection rates.
+
+Five [application-directory snapshots](./test/evaluation/projects.json) provide additional evaluation. Preparation uses the network and verifies Git object hashes; the target must be a new directory outside Git:
+
+```powershell
+node scripts/fetch-evaluation-projects.mjs "$env:TEMP/canship-evaluation"
+```
+
+Then evaluate offline without installing or running sample dependencies:
+
+```powershell
+npm run evaluate:projects -- "$env:TEMP/canship-evaluation"
+```
+
+CI uses the same corpus. Git history and deployed behaviour are outside this evaluation.
+
 ## License
 
-[MIT](./LICENSE)
+[MIT](./LICENSE). Supabase and Firebase fixtures retain Apache-2.0; Next.js and `cors` fixtures retain MIT. Each includes its source and licence.

package/dist/cli.js

@@ -952,71 +952,68 @@ function endOfString(src, start, quote) {
   }
   return length;
 }
-function maskTemplate(src, out, start) {
+function maskTemplate(src, out, start, maskStrings = true) {
   const length = src.length;
+  const stack = [{ kind: "literal", from: start + 1 }];
   let i = start + 1;
-  let literalFrom = i;
-  while (i < length) {
+  while (i < length && stack.length > 0) {
+    const frame = stack[stack.length - 1];
     const ch = src.charCodeAt(i);
-    if (ch === BACKSLASH) {
-      i += 2;
+    if (frame.kind === "literal") {
+      if (ch === BACKSLASH) {
+        i = Math.min(i + 2, length);
+        continue;
+      }
+      if (ch === BACKTICK) {
+        if (maskStrings) blank(out, frame.from, i);
+        stack.pop();
+        i++;
+        continue;
+      }
+      if (ch === DOLLAR && src.charCodeAt(i + 1) === OPEN_BRACE) {
+        if (maskStrings) blank(out, frame.from, i);
+        stack.push({ kind: "expression", depth: 1 });
+        i += 2;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (ch === SLASH) {
+      const next = src.charCodeAt(i + 1);
+      if (next === SLASH || next === STAR) {
+        const close = next === SLASH ? src.indexOf("\n", i) : src.indexOf("*/", i + 2);
+        const stop = close === -1 ? length : close + (next === STAR ? 2 : 0);
+        blank(out, i, stop);
+        i = stop;
+        continue;
+      }
+    }
+    if (ch === DOUBLE_QUOTE || ch === SINGLE_QUOTE) {
+      const stop = endOfString(src, i, ch);
+      if (maskStrings) blank(out, i + 1, stop - 1);
+      i = stop;
       continue;
     }
     if (ch === BACKTICK) {
-      blank(out, literalFrom, i);
-      return i + 1;
+      stack.push({ kind: "literal", from: i + 1 });
+      i++;
+      continue;
     }
-    if (ch === DOLLAR && src.charCodeAt(i + 1) === OPEN_BRACE) {
-      blank(out, literalFrom, i);
-      let depth = 0;
-      let j = i + 1;
-      while (j < length) {
-        const inner = src.charCodeAt(j);
-        if (inner === SLASH) {
-          const next = src.charCodeAt(j + 1);
-          if (next === SLASH) {
-            const end = src.indexOf("\n", j);
-            const stop = end === -1 ? length : end;
-            blank(out, j, stop);
-            j = stop;
-            continue;
-          }
-          if (next === STAR) {
-            const close = src.indexOf("*/", j + 2);
-            const stop = close === -1 ? length : close + 2;
-            blank(out, j, stop);
-            j = stop;
-            continue;
-          }
-        }
-        if (inner === DOUBLE_QUOTE || inner === SINGLE_QUOTE) {
-          const stop = endOfString(src, j, inner);
-          blank(out, j + 1, stop - 1);
-          j = stop;
-          continue;
-        }
-        if (inner === BACKTICK) {
-          j = maskTemplate(src, out, j);
-          continue;
-        }
-        if (inner === OPEN_BRACE) depth++;
-        else if (inner === CLOSE_BRACE) {
-          depth--;
-          if (depth === 0) {
-            j++;
-            break;
-          }
-        }
-        j++;
+    if (ch === OPEN_BRACE) frame.depth++;
+    else if (ch === CLOSE_BRACE) {
+      frame.depth--;
+      if (frame.depth === 0) {
+        stack.pop();
+        const parent = stack[stack.length - 1];
+        if (parent.kind === "literal") parent.from = i + 1;
       }
-      i = j;
-      literalFrom = i;
-      continue;
     }
     i++;
   }
-  blank(out, literalFrom, length);
-  return length;
+  const last = stack[stack.length - 1];
+  if (maskStrings && last?.kind === "literal") blank(out, last.from, length);
+  return i;
 }
 function maskJsComments(src) {
   const length = src.length;
@@ -1041,10 +1038,14 @@ function maskJsComments(src) {
         continue;
       }
     }
-    if (ch === DOUBLE_QUOTE || ch === SINGLE_QUOTE || ch === BACKTICK) {
+    if (ch === DOUBLE_QUOTE || ch === SINGLE_QUOTE) {
       i = endOfString(src, i, ch);
       continue;
     }
+    if (ch === BACKTICK) {
+      i = maskTemplate(src, out, i, false);
+      continue;
+    }
     i++;
   }
   return stringOf(out);
@@ -2102,8 +2103,8 @@ var supabaseRlsRule = {
         line: entry.line,
         excerpt: null,
         why: [
-          `Supabase exposes your database to the browser directly, and the anon key that reaches it is public by design \u2014 it ships inside your frontend. Row Level Security is the only thing that decides who can read or write a row.`,
-          `No "ALTER TABLE ${renderIdent(entry.table)} ENABLE ROW LEVEL SECURITY" appears anywhere in your SQL, and new tables do not get it by default. If that is the real state, anyone who visits your site can list this entire table with a single request \u2014 and depending on your policies, write to it too.`,
+          `Supabase's browser clients use public identifiers. For exposed tables, database grants and Row Level Security determine which operations and rows a caller can access.`,
+          `After replaying the scanned migrations, the final recorded state of ${renderIdent(entry.table)} does not have RLS enabled. It may never have been enabled or may have been disabled by a later migration. Without RLS, any access granted to the caller is not restricted by row policies.`,
           `If you enabled RLS from the Supabase dashboard instead, this file simply cannot show it. Check the Authentication -> Policies page to confirm.`
         ],
         fix: [
@@ -2130,9 +2131,7 @@ var supabaseRlsRule = {
 // src/rules/firebase.ts
 import { basename as basename5 } from "path";
 function isRulesFile(file) {
-  const name = basename5(file.path).toLowerCase();
-  if (name.endsWith(".rules")) return true;
-  return name === "firestore.rules" || name === "storage.rules";
+  return basename5(file.path).toLowerCase().endsWith(".rules");
 }
 function productOf(path) {
   const name = basename5(path).toLowerCase();
@@ -2244,7 +2243,7 @@ var firebaseRulesRule = {
         excerpt: m[0].trim(),
         why: canWrite ? [
           `"if true" grants access unconditionally \u2014 no sign-in, no ownership check, nothing. The Firebase client SDK talks to your database straight from the browser, so these rules are the only access control that exists.`,
-          `Anyone who finds your project id can read every document here, overwrite it, or delete all of it. Project ids are not secret; they ship inside your frontend bundle.`
+          `Anyone can perform the allowed ${ops} operations on this matched path without authentication. Other operations depend on their own rules. Project ids are public identifiers, not access controls.`
         ] : [
           `"if true" grants read access unconditionally, so anyone who finds your project id can list every document in this collection. Project ids are not secret; they ship inside your frontend bundle.`,
           `Writes are still denied by default, so this is only a problem if the data is not meant to be public. If it is a public catalogue or announcements, ignore this \u2014 and consider adding "allow write: if false;" to make that intent explicit.`
@@ -2922,9 +2921,9 @@ var apiAuthRule = {
           line,
           excerpt,
           why: [
-            `This route uses the service_role key, which bypasses every Row Level Security policy you have. Whatever your database would normally refuse, this route performs.`,
-            `Nothing in this file checks who is calling \u2014 no session lookup, no token check, no 401 anywhere \u2014 and no middleware covers it. The URL is not a secret either: it is spelled out by the file path, and it appears in your frontend bundle as soon as anything calls it.`,
-            `So a single curl to ${url} gets the same access your admin key has.`,
+            `This route references a recognized admin client. Such clients can bypass normal per-user access checks; verify the effective credentials and granted permissions.`,
+            `The scan did not recognize an authentication guard protecting this operation or applicable middleware. Indirect wrappers and deployment-level controls may not be recognized; verify them before exposing this route.`,
+            `If ${url} is reachable without authentication, callers can trigger the admin-backed operations implemented by this handler.`,
             `If this endpoint is meant to be public \u2014 handing out a guest session, taking a waitlist signup \u2014 then the problem is not that it is open, it is that it is open *and* holds the admin key. Give it a client that can only do the one thing it needs.`
           ],
           fix: [
@@ -2950,8 +2949,8 @@ var apiAuthRule = {
           line,
           excerpt,
           why: [
-            `This route changes data, and nothing in the file checks who is calling \u2014 no session lookup, no token check, no 401 anywhere.`,
-            `Route URLs are not secret; this one is spelled out by its file path. Anyone who sends a request can trigger the same write.`,
+            `This route changes data, and the scan did not recognize an authentication guard before the operation. Indirect guards and runtime controls require manual verification.`,
+            `If this route is publicly reachable and no other control rejects the caller, unauthenticated requests can trigger this write.`,
             `If this is a public form \u2014 a waitlist, a contact box \u2014 that may be intentional. It is still worth rate limiting, because an open write endpoint is what gets a database filled with spam overnight.`
           ],
           fix: [
@@ -2968,8 +2967,31 @@ var apiAuthRule = {
 
 // src/rules/cors.ts
 var CORS_MARKER = /Access-Control-Allow-Origin|\bcors\s*\(/i;
-var ACAO = /['"]Access-Control-Allow-Origin['"]\s*(?:,|:)\s*(?:value\s*:\s*)?([^\n]+)/gi;
-var CORS_ORIGIN_OPTION = /\borigin\s*:\s*(true|['"`]\*['"`])/gi;
+var ACAO = /['"]Access-Control-Allow-Origin['"]\s*(?:,|:)\s*(?:value\s*:\s*)?/gi;
+function headerExpression(content, start) {
+  const closes = [];
+  let quote = null;
+  let end = start;
+  for (; end < content.length; end++) {
+    const ch = content[end];
+    if (ch === "\n" || ch === "\r") break;
+    if (quote !== null) {
+      if (ch === "\\") end++;
+      else if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === "`") quote = ch;
+    else if (ch === "(") closes.push(")");
+    else if (ch === "[") closes.push("]");
+    else if (ch === "{") closes.push("}");
+    else if (ch === ")" || ch === "]" || ch === "}") {
+      if (closes.at(-1) !== ch) break;
+      closes.pop();
+    } else if (closes.length === 0 && (ch === "," || ch === ";")) break;
+  }
+  return content.slice(start, end);
+}
+var CORS_ORIGIN_OPTION = /\borigin\s*:\s*/gi;
 var CORS_ORIGIN_PROPERTY_START = /\borigin\s*:\s*(?:async\s+)?(?:(function)\s*(?:[A-Za-z_$][\w$]*)?\s*)?\(/gi;
 var CORS_ORIGIN_METHOD_START = /\borigin\s*\(/gi;
 function closingParameterList(source, open) {
@@ -3010,6 +3032,8 @@ function readOriginCallback(content, match, kind) {
   }
   return {
     index: match.index,
+    parametersStart: open + 1,
+    parametersEnd: close,
     params: content.slice(open + 1, close),
     body: content.slice(bodyStart, bodyStart + 400)
   };
@@ -3118,31 +3142,63 @@ function classifyOrigin(raw) {
   return /\b(?:req|request|headers?|ctx|event)/i.test(compact) ? "reflected" : "unknown";
 }
 var PAIRING_DISTANCE = 25;
+function optionScopes(file, positions) {
+  const scopes = /* @__PURE__ */ new Map();
+  const wanted = [...new Set(positions)].sort((a, b) => a - b);
+  if (wanted.length === 0) return scopes;
+  const content = noiseMaskedOf(file);
+  const stack = [-1];
+  let next = 0;
+  for (let at = 0; at < content.length && next < wanted.length; at++) {
+    if (at === wanted[next]) {
+      scopes.set(at, stack[stack.length - 1]);
+      next++;
+    }
+    if (content[at] === "{") stack.push(at);
+    else if (content[at] === "}" && stack.length > 1) stack.pop();
+  }
+  return scopes;
+}
 function collectOrigins(file) {
   const marks = [];
   let m;
   const content = commentsMaskedOf(file);
   const contentLines = lineStartsOf(content);
+  const code = noiseMaskedOf(file);
+  const callbacks = originCallbacks(content).filter((callback) => code[callback.index] === content[callback.index]);
+  const callbackIndices = new Set(callbacks.map((callback) => callback.index));
+  const parameterRanges = [...callbacks].sort((a, b) => a.parametersStart - b.parametersStart);
+  let parameterRange = 0;
   ACAO.lastIndex = 0;
   while ((m = ACAO.exec(content)) !== null) {
+    if (code[m.index] !== content[m.index]) continue;
     const line = lineNumberAt(contentLines, m.index);
-    marks.push({ line, kind: classifyOrigin(m[1] ?? ""), excerpt: (file.lines[line - 1] ?? "").trim() });
+    const expression = headerExpression(content, ACAO.lastIndex);
+    ACAO.lastIndex += expression.length;
+    marks.push({ line, at: m.index, mode: "header", kind: classifyOrigin(expression), excerpt: (file.lines[line - 1] ?? "").trim() });
   }
   CORS_ORIGIN_OPTION.lastIndex = 0;
   while ((m = CORS_ORIGIN_OPTION.exec(content)) !== null) {
+    if (code[m.index] !== content[m.index]) continue;
+    while (parameterRange < parameterRanges.length && parameterRanges[parameterRange].parametersEnd < m.index) parameterRange++;
+    if (parameterRanges[parameterRange] && parameterRanges[parameterRange].parametersStart <= m.index) continue;
+    if (callbackIndices.has(m.index)) continue;
     const line = lineNumberAt(contentLines, m.index);
+    const expression = headerExpression(content, CORS_ORIGIN_OPTION.lastIndex);
+    CORS_ORIGIN_OPTION.lastIndex += expression.length;
     marks.push({
       line,
-      kind: (m[1] ?? "") === "true" ? "reflected" : "wildcard",
+      at: m.index,
+      mode: "option",
+      kind: expression.trim() === "true" ? "reflected" : classifyOrigin(expression),
       excerpt: (file.lines[line - 1] ?? "").trim()
     });
   }
-  for (const callback of originCallbacks(content)) {
+  for (const callback of callbacks) {
     const answer = callbackAnswer(callback.params, callback.body);
-    if (answer === null) continue;
-    if (ORIGIN_IS_CHECKED.test(callback.body.slice(0, answer.index))) continue;
+    const kind = answer !== null && !ORIGIN_IS_CHECKED.test(callback.body.slice(0, answer.index)) ? answer.kind : "unknown";
     const line = lineNumberAt(contentLines, callback.index);
-    marks.push({ line, kind: answer.kind, excerpt: (file.lines[line - 1] ?? "").trim() });
+    marks.push({ line, at: callback.index, mode: "option", kind, excerpt: (file.lines[line - 1] ?? "").trim() });
   }
   return marks;
 }
@@ -3150,11 +3206,16 @@ function collectCredentialLines(file) {
   const lines = [];
   let m;
   const content = commentsMaskedOf(file);
+  const code = noiseMaskedOf(file);
   const contentLines = lineStartsOf(content);
   ACAC_HEADER.lastIndex = 0;
-  while ((m = ACAC_HEADER.exec(content)) !== null) lines.push(lineNumberAt(contentLines, m.index));
+  while ((m = ACAC_HEADER.exec(content)) !== null) {
+    if (code[m.index] === content[m.index]) lines.push({ line: lineNumberAt(contentLines, m.index), at: m.index, mode: "header" });
+  }
   CORS_CREDENTIALS_OPTION.lastIndex = 0;
-  while ((m = CORS_CREDENTIALS_OPTION.exec(content)) !== null) lines.push(lineNumberAt(contentLines, m.index));
+  while ((m = CORS_CREDENTIALS_OPTION.exec(content)) !== null) {
+    if (code[m.index] === content[m.index]) lines.push({ line: lineNumberAt(contentLines, m.index), at: m.index, mode: "option" });
+  }
   return lines;
 }
 function nearestOrigin(origins, credLine) {
@@ -3184,10 +3245,12 @@ var corsRule = {
     if (credentialLines.length === 0) return [];
     const origins = collectOrigins(file);
     if (origins.length === 0) return [];
+    const scopes = optionScopes(file, [...origins, ...credentialLines].filter((mark) => mark.mode === "option").map((mark) => mark.at));
     const findings = [];
     const reported = /* @__PURE__ */ new Set();
-    for (const credLine of credentialLines) {
-      const origin = nearestOrigin(origins, credLine);
+    for (const credential of credentialLines) {
+      const candidates = origins.filter((origin2) => origin2.mode === credential.mode && (credential.mode === "header" || scopes.get(origin2.at) === scopes.get(credential.at)));
+      const origin = nearestOrigin(candidates, credential.line);
       if (!origin) continue;
       if (origin.kind !== "reflected" && origin.kind !== "wildcard") continue;
       if (reported.has(origin.kind)) continue;
@@ -3393,8 +3456,8 @@ async function scan(root, options = {}) {
   const { files, skipped, ignored, vendored } = collectFiles(root, git2 === "repo", gitExecutable);
   const findings = [];
   const errors = [];
-  const fileRules = FILE_RULES.filter((rule) => shouldRunRule(rule.id, options.only ?? [], options.skip ?? []));
-  const projectRules = PROJECT_RULES.filter((rule) => shouldRunRule(rule.id, options.only ?? [], options.skip ?? []));
+  const fileRules = FILE_RULES.filter((rule2) => shouldRunRule(rule2.id, options.only ?? [], options.skip ?? []));
+  const projectRules = PROJECT_RULES.filter((rule2) => shouldRunRule(rule2.id, options.only ?? [], options.skip ?? []));
   const incompleteSeen = /* @__PURE__ */ new Set();
   const ctx = {
     root,
@@ -3409,20 +3472,20 @@ async function scan(root, options = {}) {
     }
   };
   for (const file of files) {
-    for (const rule of fileRules) {
+    for (const rule2 of fileRules) {
       try {
-        if (!rule.appliesTo(file)) continue;
-        findings.push(...rule.check(file, ctx));
+        if (!rule2.appliesTo(file)) continue;
+        findings.push(...rule2.check(file, ctx));
       } catch (err) {
-        errors.push({ ruleId: rule.id, file: file.path, message: messageOf(err), kind: "crashed" });
+        errors.push({ ruleId: rule2.id, file: file.path, message: messageOf(err), kind: "crashed" });
       }
     }
   }
-  for (const rule of projectRules) {
+  for (const rule2 of projectRules) {
     try {
-      findings.push(...await rule.check(ctx));
+      findings.push(...await rule2.check(ctx));
     } catch (err) {
-      errors.push({ ruleId: rule.id, file: null, message: messageOf(err), kind: "crashed" });
+      errors.push({ ruleId: rule2.id, file: null, message: messageOf(err), kind: "crashed" });
     }
   }
   const { kept, ignored: ignoredFindings } = suppressIgnoredLines(
@@ -4188,9 +4251,10 @@ function applyBaseline(findings, baseline) {
   const kept = [];
   let suppressed = 0;
   for (const f of findings) {
-    const budget = remaining.get(fingerprintOf(f)) ?? 0;
+    const fp = fingerprintOf(f);
+    const budget = remaining.get(fp) ?? 0;
     if (budget > 0) {
-      remaining.set(fingerprintOf(f), budget - 1);
+      remaining.set(fp, budget - 1);
       suppressed++;
       continue;
     }
@@ -4326,6 +4390,29 @@ function renderSarif(result, opts) {
 `;
 }
 
+// src/report/json.ts
+function createJsonReport(result, options) {
+  return {
+    schemaVersion: 1,
+    version: options.version,
+    root: options.root,
+    filesScanned: result.filesScanned,
+    durationMs: result.durationMs,
+    partial: result.partial,
+    errors: result.errors,
+    skipped: result.skipped,
+    ignored: result.ignored,
+    ignoredFindings: result.ignoredFindings,
+    ruleSelection: result.ruleSelection,
+    vendored: result.vendored,
+    hiddenLikely: options.hiddenLikely,
+    baselineSuppressed: options.baselineSuppressed,
+    baselineStale: options.baselineStale,
+    excerptsOmitted: options.excerptsOmitted ?? false,
+    findings: result.findings
+  };
+}
+
 // src/config.ts
 import { existsSync as existsSync2, readFileSync as readFileSync4, statSync as statSync4 } from "fs";
 import { join as join3 } from "path";
@@ -4416,12 +4503,137 @@ function loadConfig(root) {
   return { config: parseConfig(text, path), path };
 }
 
+// src/rules/catalog.ts
+var rule = (id, name, severity, confidence, scope, limitation) => ({ id, name, severity, confidence, scope, limitation, reportsFindings: true });
+var RULE_CATALOG = [
+  rule(
+    "api/admin-db-access-without-auth",
+    "Admin database access without a recognized auth guard",
+    "P0",
+    "certain",
+    "Next.js App/Pages API handlers, including workspace applications.",
+    "Syntactic guards only; runtime authentication and business authorization are not verified."
+  ),
+  rule(
+    "api/db-write-without-auth",
+    "Database write without a recognized auth guard",
+    "P1",
+    "likely",
+    "Next.js App/Pages API handlers.",
+    "Session-scoped clients and indirect guards may need manual review."
+  ),
+  rule(
+    "cors/reflected-origin-with-credentials",
+    "Reflected origin with credentials",
+    "P1",
+    "certain",
+    "Response headers and cors middleware options.",
+    "Static pairing does not prove the deployed policy or cookie behavior."
+  ),
+  rule(
+    "cors/wildcard-with-credentials",
+    "Wildcard origin with credentials",
+    "P2",
+    "certain",
+    "Response headers and cors middleware options.",
+    "Browsers reject this combination; it is not proof of data exposure."
+  ),
+  rule(
+    "exposure/private-name-in-public-env",
+    "Private-looking name with a public env prefix",
+    "P0",
+    "likely",
+    "Environment files and source references using recognized public prefixes.",
+    "A variable name is not proof that its value is a secret."
+  ),
+  rule(
+    "exposure/secret-in-public-env",
+    "Recognized secret in a public env variable",
+    "P0",
+    "certain",
+    "Environment files using recognized public prefixes.",
+    "Credential validity and actual deployment are not verified."
+  ),
+  rule(
+    "exposure/supabase-service-role-in-client",
+    "Supabase admin credential exposed in source or public env",
+    "P0",
+    "certain",
+    "Recognized service_role JWTs in source; Supabase admin credentials in public environment variables.",
+    "Source presence is observable; actual browser delivery and key validity are not verified."
+  ),
+  rule(
+    "firebase/open-rules",
+    "Unconditional Firebase access",
+    "P1",
+    "varies",
+    "Firebase .rules files: unconditional writes are certain; public reads require review.",
+    "Public reads may be intentional; runtime rules and business authorization are not verified."
+  ),
+  rule(
+    "firebase/test-mode-rules",
+    "Date-based Firebase test rules",
+    "P1",
+    "certain",
+    "Firebase .rules files using a fixed timestamp cutoff.",
+    "Expired rules may deny access; deployment state is not verified."
+  ),
+  rule(
+    "gitleak/env-in-history",
+    "Private env values in local Git history",
+    "P0",
+    "varies",
+    "Relevant historical versions of environment files in the local repository.",
+    "History and resource limits apply; remote refs not available locally are not checked."
+  ),
+  rule(
+    "gitleak/env-tracked",
+    "Private env values tracked by Git",
+    "P0",
+    "varies",
+    "Tracked environment files; templates and public-only values are treated separately.",
+    "Unrecognized private values are heuristic findings, not verified credentials."
+  ),
+  rule(
+    "supabase/rls-not-enabled",
+    "Table without RLS in migrations",
+    "P1",
+    "certain",
+    "Supabase SQL migrations, replayed by application scope.",
+    "Migration state is not deployed database state; grants and policy correctness are outside this check."
+  ),
+  ...SECRET_PATTERNS.map((pattern) => ({
+    ...rule(
+      `secrets/hardcoded/${pattern.id}`,
+      pattern.name,
+      "P0",
+      "certain",
+      "Recognized credential formats in scanned text files.",
+      "Validity, revocation, and use are not checked; example contexts lower confidence."
+    ),
+    reportsFindings: !pattern.publicByDesign,
+    ...pattern.publicByDesign ? { limitation: "Treated as a public identifier; this format alone does not produce a finding." } : {}
+  }))
+];
+function renderRuleCatalog() {
+  return "canship rules\n\n" + RULE_CATALOG.map(
+    (item) => `${item.id}
+  ${item.name}
+  ${item.reportsFindings ? `${item.severity}; ${item.confidence}` : "Public identifier; not reported"}
+  Scope: ${item.scope}
+  Limit: ${item.limitation}`
+  ).join("\n\n") + "\n\nExample and fixture contexts may lower confidence. No credential validity or deployed configuration is verified.\n";
+}
+
 // src/cli.ts
-var VERSION = true ? "0.2.1" : "0.0.0-dev";
+var VERSION = true ? "0.3.0" : "0.0.0-dev";
+function finish(code) {
+  process.exitCode = code;
+}
+var ArgumentError = class extends Error {
+};
 function argumentError(message) {
-  process.stderr.write(`canship: ${cleanForOutput(message)}
-`);
-  process.exit(3);
+  throw new ArgumentError(cleanForOutput(message));
 }
 function optionalValue(arg, name, fallback) {
   if (arg === name) return fallback;
@@ -4480,7 +4692,9 @@ function parseArgs(argv) {
     sarif: null,
     noConfig: false,
     help: false,
-    version: false
+    version: false,
+    listRules: false,
+    noExcerpts: false
   };
   const positional = [];
   for (const arg of argv) {
@@ -4545,6 +4759,12 @@ function parseArgs(argv) {
       case "--no-config":
         args.noConfig = true;
         break;
+      case "--list-rules":
+        args.listRules = true;
+        break;
+      case "--no-excerpts":
+        args.noExcerpts = true;
+        break;
       case "--help":
       case "-h":
         args.help = true;
@@ -4587,6 +4807,8 @@ var HELP = `
         --sarif[=F]   Write a SARIF 2.1.0 log for CI code scanning
                       (default canship.sarif)
         --no-config   Ignore canship.config.json in the scanned directory
+        --list-rules  List rule IDs, scope, and limits; add --json for structured output
+        --no-excerpts Omit source excerpts from every report; paths and descriptions remain
     -h, --help        Show this help
     -v, --version     Show version
 
@@ -4609,12 +4831,20 @@ async function main() {
   if (args.help) {
     process.stdout.write(`${HELP}
 `);
-    return process.exit(0);
+    return finish(0);
   }
   if (args.version) {
     process.stdout.write(`${VERSION}
 `);
-    return process.exit(0);
+    return finish(0);
+  }
+  if (args.listRules) {
+    if (process.argv.slice(2).some((arg) => arg !== "--list-rules" && arg !== "--json")) {
+      argumentError("--list-rules only supports --json; scan options and paths cannot be combined with it");
+    }
+    process.stdout.write(args.json ? `${JSON.stringify({ schemaVersion: 1, kind: "rule-catalog", version: VERSION, rules: RULE_CATALOG }, null, 2)}
+` : renderRuleCatalog());
+    return;
   }
   if (args.json && args.fixPrompt) {
     argumentError("--json and --fix-prompt are mutually exclusive");
@@ -4625,7 +4855,7 @@ async function main() {
   if (!existsSync3(args.root) || !statSync5(args.root).isDirectory()) {
     process.stderr.write(`${red("canship:")} not a directory: ${cleanForOutput(args.root)}
 `);
-    return process.exit(3);
+    return finish(3);
   }
   let config;
   try {
@@ -4634,7 +4864,7 @@ async function main() {
     if (err instanceof ConfigError) {
       process.stderr.write(`${red("canship:")} ${cleanForOutput(err.message)}
 `);
-      return process.exit(3);
+      return finish(3);
     }
     throw err;
   }
@@ -4669,7 +4899,7 @@ async function main() {
 ${cleanForOutput(String(err))}
 `
       );
-      return process.exit(3);
+      return finish(3);
     }
     const accepted = scanned.findings.length;
     process.stdout.write(
@@ -4696,7 +4926,7 @@ ${cleanForOutput(String(err))}
 `
       );
     }
-    return process.exit(0);
+    return finish(0);
   }
   let baselineSuppressed = 0;
   let baselineStale = 0;
@@ -4712,12 +4942,13 @@ ${cleanForOutput(String(err))}
       if (err instanceof BaselineError) {
         process.stderr.write(`${red("canship:")} ${cleanForOutput(err.message)}
 `);
-        return process.exit(3);
+        return finish(3);
       }
       throw err;
     }
   }
   const displayRoot = cleanForOutput(args.root);
+  if (args.noExcerpts) result = { ...result, findings: result.findings.map((finding) => ({ ...finding, excerpt: null })) };
   const shown = showAll ? result.findings : result.findings.filter((f) => f.confidence === "certain");
   const hiddenLikely = showAll ? 0 : result.findings.filter((f) => f.confidence === "likely").length;
   if (args.fixPrompt) {
@@ -4737,26 +4968,14 @@ ${cleanForOutput(String(err))}
   } else if (args.json) {
     process.stdout.write(
       `${JSON.stringify(
-        {
+        createJsonReport({ ...result, findings: shown }, {
           version: VERSION,
           root: displayRoot,
-          filesScanned: result.filesScanned,
-          durationMs: result.durationMs,
-          // 空结果不能掩盖扫描未完成。
-          partial: result.partial,
-          errors: result.errors,
-          skipped: result.skipped,
-          ignored: result.ignored,
-          ignoredFindings: result.ignoredFindings,
-          ruleSelection: result.ruleSelection,
-          vendored: result.vendored,
-          // 隐藏详情时仍披露疑似结果数量。
           hiddenLikely,
-          // 明确披露基线抑制和过期条目数量。
           baselineSuppressed,
           baselineStale,
-          findings: shown
-        },
+          excerptsOmitted: args.noExcerpts
+        }),
         null,
         2
       )}
@@ -4805,7 +5024,7 @@ ${cleanForOutput(String(err))}
 ${cleanForOutput(String(err))}
 `
       );
-      return process.exit(3);
+      return finish(3);
     }
   }
   if (args.report) {
@@ -4837,17 +5056,19 @@ ${cleanForOutput(String(err))}
 ${cleanForOutput(String(err))}
 `
       );
-      return process.exit(3);
+      return finish(3);
     }
   }
-  if (verdictOf(result.findings).blocking > 0) return process.exit(1);
-  if (result.findings.length > 0) return process.exit(2);
-  if (result.partial && !bestEffort) return process.exit(3);
-  return process.exit(0);
+  if (verdictOf(result.findings).blocking > 0) return finish(1);
+  if (result.findings.length > 0) return finish(2);
+  if (result.partial && !bestEffort) return finish(3);
+  return finish(0);
 }
 main().catch((err) => {
-  process.stderr.write(`${red("canship: unexpected error")}
+  if (err instanceof ArgumentError) process.stderr.write(`canship: ${err.message}
+`);
+  else process.stderr.write(`${red("canship: unexpected error")}
 ${cleanForOutput(String(err))}
 `);
-  process.exit(3);
+  finish(3);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canship",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Static scanner for exposed credentials and open access rules in JS/TS front-end projects. Scans local files without executing project code or making network requests.",
   "keywords": [
     "security",
@@ -30,6 +30,7 @@
   },
   "files": [
     "dist",
+    "schemas",
     "README.md",
     "README-zh-CN.md",
     "LICENSE"
@@ -42,6 +43,9 @@
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
     "test": "node scripts/run-tests.mjs",
+    "evaluate": "tsx scripts/evaluate.ts",
+    "evaluate:projects": "tsx scripts/evaluate-projects.ts",
+    "test:package": "npm run build && node scripts/package-smoke.mjs",
     "prepublishOnly": "npm run typecheck && npm run test && npm run build"
   },
   "overrides": {
@@ -49,6 +53,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "ajv": "^8.20.0",
     "tsup": "^8.3.5",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2"

package/schemas/scan-report-v1.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "canship scan report v1",
+  "type": "object",
+  "required": ["schemaVersion", "version", "root", "filesScanned", "durationMs", "partial", "errors", "skipped", "ignored", "ignoredFindings", "ruleSelection", "vendored", "hiddenLikely", "baselineSuppressed", "baselineStale", "findings"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "version": { "type": "string", "minLength": 1 },
+    "root": { "type": "string" },
+    "filesScanned": { "$ref": "#/definitions/count" },
+    "durationMs": { "type": "number", "minimum": 0 },
+    "partial": { "type": "boolean" },
+    "vendored": { "$ref": "#/definitions/count" },
+    "hiddenLikely": { "$ref": "#/definitions/count" },
+    "baselineSuppressed": { "$ref": "#/definitions/count" },
+    "baselineStale": { "$ref": "#/definitions/count" },
+    "excerptsOmitted": { "type": "boolean" },
+    "ignored": { "$ref": "#/definitions/strings" },
+    "errors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["ruleId", "file", "message", "kind"],
+        "properties": {
+          "ruleId": { "type": "string" },
+          "file": { "type": ["string", "null"] },
+          "message": { "type": "string" },
+          "kind": { "enum": ["crashed", "incomplete"] }
+        }
+      }
+    },
+    "skipped": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "reason"],
+        "properties": {
+          "path": { "type": "string" },
+          "reason": { "enum": ["too-large", "unreadable", "directory-unreadable", "binary", "symlink", "nested-repository"] },
+          "detail": { "type": "string" }
+        }
+      }
+    },
+    "ignoredFindings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["file", "line", "ruleId"],
+        "properties": {
+          "file": { "type": "string" },
+          "line": { "type": "integer", "minimum": 1 },
+          "ruleId": { "type": "string" }
+        }
+      }
+    },
+    "ruleSelection": {
+      "anyOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "required": ["only", "skip", "removed"],
+          "properties": {
+            "only": { "$ref": "#/definitions/strings" },
+            "skip": { "$ref": "#/definitions/strings" },
+            "removed": { "$ref": "#/definitions/count" }
+          }
+        }
+      ]
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["ruleId", "severity", "confidence", "title", "file", "line", "excerpt", "why", "fix"],
+        "properties": {
+          "ruleId": { "type": "string", "minLength": 1 },
+          "severity": { "enum": ["P0", "P1", "P2"] },
+          "confidence": { "enum": ["certain", "likely"] },
+          "title": { "type": "string" },
+          "file": { "type": ["string", "null"] },
+          "line": { "anyOf": [{ "type": "integer", "minimum": 1 }, { "type": "null" }] },
+          "excerpt": { "type": ["string", "null"] },
+          "sourceFingerprint": { "type": "string" },
+          "why": { "$ref": "#/definitions/strings" },
+          "fix": { "$ref": "#/definitions/strings" },
+          "humanOnly": { "$ref": "#/definitions/strings" }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "count": { "type": "integer", "minimum": 0 },
+    "strings": { "type": "array", "items": { "type": "string" } }
+  }
+}