canship 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README-zh-CN.md +99 -116
  2. package/README.md +92 -109
  3. package/dist/cli.js +819 -98
  4. package/dist/index.js +814 -93
  5. package/package.json +1 -1
package/README-zh-CN.md CHANGED
@@ -10,9 +10,9 @@
10
10
  npx canship .
11
11
  ```
12
12
 
13
- 要求 Node.js ≥18，无运行时依赖。安装软件包可能联网；Git 检查仅使用本地历史。仓库中无法调用 Git 时，扫描标记为未完成。
13
+ 要求 Node.js ≥18，无运行时依赖。安装可能联网；Git 检查仅读取本地历史，仓库中无法调用 Git 时标记扫描未完成。
14
14
 
15
- > 本文对应 0.4.0，较早的 [npm 版本](https://www.npmjs.com/package/canship) 可能不包含下述全部功能。
15
+ > 本文对应 0.5.0。`npx canship` 运行 npm 默认版本；其他版本的文档请查阅对应 Git 标签。
16
16
 
17
17
  ## 检测范围
18
18
 
@@ -21,35 +21,30 @@ npx canship .
21
21
  | 硬编码凭据、私钥及含密码的数据库连接串 | P0 |
22
22
  | 公开环境变量中的私密值 | P0 |
23
23
  | 源码或公开环境变量中的 Supabase 管理员凭据 | P0 |
24
- | Git 跟踪及历史 `.env` 文件中的凭据或疑似私密值 | P0 |
25
- | Supabase 迁移中未启用行级安全（RLS）的表 | P1 |
26
- | Supabase 条件恒为真的 RLS 策略 | P1 |
24
+ | Git 跟踪或历史提交的 `.env` 文件，模板除外 | P0 |
25
+ | Supabase 未启用 RLS 的表及条件恒真的策略 | P1 |
27
26
  | 内容可被列举的 Supabase 公开存储桶 | P2 |
28
- | Firebase 无条件访问及固定日期测试规则（Firestore、Storage、Realtime Database） | P1 |
27
+ | Firebase 无条件访问及固定日期测试规则 | P1 |
29
28
  | 服务端数据操作未识别到鉴权 | P0 / P1 |
30
29
  | 携带凭据的 CORS 来源回显或通配符配置 | P1 / P2 |
31
30
 
32
- 识别 OpenAI、Anthropic、AWS、Stripe、GitHub、npm 等凭据格式及常见前端公开环境变量前缀。规则 ID、范围与限制见 `--list-rules`。
31
+ 识别 OpenAI、Anthropic、AWS、Stripe、GitHub、npm 等凭据格式。Firebase 检查覆盖 Firestore、Storage、Realtime Database。规则 ID 与范围见 `--list-rules`。
33
32
 
34
- ### 鉴权检查范围
33
+ ### 鉴权检查
35
34
 
36
35
  | 框架 | 检查入口 |
37
36
  |---|---|
38
- | Next.js | `app/` 下的 route 处理函数、Pages Router `/api`、`'use server'` 函数 |
37
+ | Next.js | `app/` 路由处理函数、Pages Router `/api`、`'use server'` 函数 |
39
38
  | SvelteKit | `+server` 端点及 `+page.server` 表单 action |
40
39
  | Nuxt | `server/api`、`server/routes` |
41
- | Remix / React Router | `app/routes` 中导出的 `loader`、`action` |
40
+ | Remix / React Router | `app/routes` 中的 `loader`、`action` 导出 |
42
41
  | Astro | `src/pages` 中的端点 |
43
42
 
44
- 支持路由组和工作区应用，不检查 SvelteKit 页面 load 与 remote function。已识别的 Next.js、Astro 中间件鉴权可抑制覆盖路由的结果；Server Function 需在函数内鉴权。SvelteKit hooks、Nuxt 中间件及本地鉴权函数可降低置信度，但不抑制结果。
43
+ 支持路由组、工作区应用、本地辅助函数链、身份别名与解构、实参约束及有界分支/异常分析。原始请求输入、常量、未等待的 Promise 或辅助函数名称本身，不构成本地鉴权依据。
45
44
 
46
- Supabase 检查重放本地迁移并读取支持的存储桶配置，不检查仅在控制台修改的配置或省略子句隐含的策略条件。
45
+ 已识别的 Next.js/Astro 中间件可抑制覆盖范围内的结果；Server Function 需在函数内检查。本地辅助函数、SvelteKit hooks、Nuxt 中间件可降低置信度，但保留结果。不检查 SvelteKit 页面 load 与 remote function。
47
46
 
48
- ### 置信度与证据
49
-
50
- `certain`（确定）与 `likely`（疑似）描述静态证据，不验证凭据有效性或线上状态。默认仅展示 `certain`；隐藏的 `likely` 仍影响退出码。
51
-
52
- 管理员客户端相关结果附带数据操作、导入和客户端构造位置。支持限定语法内的 Supabase 构造器别名、本地鉴权导入、重导出及返回函数的封装。鉴权解析最多 8 跳，证据链最多 24 步，截断时提示。间接鉴权证据仅降低置信度；导入关系不证明运行时数据流。
47
+ `certain`（确定）与 `likely`（疑似）描述静态证据，不验证凭据有效性或运行时安全。默认只展示 `certain`，隐藏的 `likely` 仍影响退出码。管理员客户端结果附带操作、导入、构造及鉴权函数位置。
53
48
 
54
49
  ## 命令行
55
50
 
@@ -57,21 +52,21 @@ Supabase 检查重放本地迁移并读取支持的存储桶配置，不检查
57
52
 
58
53
  | 参数 | 作用 |
59
54
  |---|---|
60
- | `-a`, `--all` | 所有格式包含 `likely` 结果 |
55
+ | `-a`、`--all` | 包含 `likely` 结果 |
61
56
  | `--json` | 输出 JSON |
62
57
  | `--fix-prompt` | 输出修复指令及独立的人工操作清单 |
63
58
  | `--report[=file]` | 写入 HTML，默认 `canship-report.html` |
64
59
  | `--sarif[=file]` | 写入 SARIF 2.1.0，默认 `canship.sarif` |
65
- | `--no-excerpts` | 省略源码摘录，不改变结果和退出码 |
66
- | `--changed-since=ref` | 按变更文件筛选报告，不改变扫描范围和退出码 |
60
+ | `--no-excerpts` | 省略源码摘录，保留结果和退出码 |
61
+ | `--changed-since=ref` | 展示与变更文件相关的结果，退出码仍基于全量扫描 |
67
62
  | `--only=ids` / `--skip=ids` | 选择或排除规则，支持逗号分隔及重复参数 |
68
- | `--list-rules` | 列出规则，不扫描；支持 `--json` |
69
- | `--baseline[=file]` | 抑制基线结果，默认 `canship-baseline.json` |
63
+ | `--list-rules` | 列出规则而不扫描，支持 `--json` |
64
+ | `--baseline[=file]` | 抑制已有结果，默认 `canship-baseline.json` |
70
65
  | `--baseline-write[=file]` | 记录结果后退出，默认路径同上 |
71
66
  | `--no-config` | 忽略项目配置 |
72
- | `--no-ignore-markers` | 不遵从源码忽略标记 |
73
- | `--best-effort` | 无结果时，允许不完整扫描退出 `0` |
74
- | `-h`, `--help` / `-v`, `--version` | 显示帮助或版本 |
67
+ | `--no-ignore-markers` | 不遵从源码忽略注释 |
68
+ | `--best-effort` | 允许没有结果的不完整扫描退出 `0` |
69
+ | `-h`、`--help` / `-v`、`--version` | 显示帮助或版本 |
75
70
 
76
71
  `--json` 与 `--fix-prompt` 互斥；HTML、SARIF 可与任一模式组合。
77
72
 
@@ -79,33 +74,64 @@ Supabase 检查重放本地迁移并读取支持的存储桶配置，不检查
79
74
 
80
75
  | 退出码 | 含义 |
81
76
  |---|---|
82
- | `0` | 无结果；扫描完整，或由 `--best-effort` 接受不完整状态 |
83
- | `1` | 存在 `certain` 的 P0/P1 结果 |
84
- | `2` | 存在其他结果，包括隐藏的 `likely` |
85
- | `3` | 参数或工具错误，或未被接受的不完整扫描 |
77
+ | `0` | 无结果，且扫描完整或已由 `--best-effort` 接受不完整状态 |
78
+ | `1` | 至少一条 `certain` 的 P0/P1 结果 |
79
+ | `2` | 其他结果，包括隐藏的 `likely` |
80
+ | `3` | 参数错误、工具错误或未被接受的不完整扫描 |
81
+
82
+ 退出码基于规则筛选、忽略标记及基线处理后的结果。结果优先于不完整状态；`--best-effort` 不改变 `1` 或 `2`。
83
+
84
+ ### 变更视图与报告
85
+
86
+ `--changed-since=origin/main` 比较本地共同祖先与工作区，包含未被 Git 忽略的新文件，不拉取远程。仍扫描全项目，仅展示主位置或证据位置发生变更的结果；仓库级结果及证据链截断的结果保留。隐藏结果仍影响退出码。缺少 Git、引用或共同历史时退出 `3`，`--best-effort` 不豁免。不能与 `--baseline-write` 组合。
87
+
88
+ JSON 使用 `schemaVersion: 1`；字段及筛选统计见 [结构定义](./schemas/scan-report-v1.schema.json)。须独立于退出码检查 `partial`、`errors`、`skipped`、`filesScanned`。兼容新增字段，拒绝不支持的结构版本。
89
+
90
+ SARIF 包含执行诊断与证据位置。`--list-rules --json` 返回独立的 `kind: "rule-catalog"` 文档。
91
+
92
+ ## 配置
93
+
94
+ 扫描目录中的 `canship.config.json` 支持 `baseline`、`only`、`skip`、`all`：
95
+
96
+ ```json
97
+ {
98
+ "skip": ["cors/wildcard-with-credentials"],
99
+ "all": false
100
+ }
101
+ ```
102
+
103
+ 命令行参数优先。`only`、`skip` 互斥，接受规则 ID 或命名空间。`--best-effort` 仅限命令行。不可信项目使用 `--no-config --no-ignore-markers`。
104
+
105
+ ### 忽略注释
86
106
 
87
- 统计以规则筛选、忽略标记和基线处理后的结果为准。结果退出码优先于不完整状态；`--best-effort` 不改变 `1` 或 `2`。
107
+ 独占注释行的 `canship-ignore-file` 排除整个文件；`canship-ignore-next-line` 抑制下一行，可限定规则：
88
108
 
89
- ### 变更文件视图
109
+ ```ts
110
+ // canship-ignore-next-line cors/wildcard-with-credentials
111
+ const corsOptions = { origin: '*', credentials: true }
112
+ ```
90
113
 
91
- `--changed-since=origin/main` 比较本地共同祖先与工作区，包含未被 Git 忽略的新文件，不拉取远程。仍扫描全项目，仅展示主位置或证据位置发生变更的结果；仓库级结果及证据链截断的结果保留。
114
+ 报告披露排除信息。主动抑制不标记扫描未完成，可使退出码降为 `0`。`--no-config` 不禁用这些注释。
92
115
 
93
- 隐藏结果仍影响退出码：此功能用于审阅，不是“仅新增问题阻断 CI”的策略。缺少 Git、引用或共同历史时退出 `3`，`--best-effort` 不豁免。不能与 `--baseline-write` 组合。
116
+ ### 基线
94
117
 
95
- ### 结构化报告
118
+ 记录已有结果，后续扫描再抑制：
96
119
 
97
- JSON 使用 `schemaVersion: 1`，包内附带 [结构定义](./schemas/scan-report-v1.schema.json)。调用方应兼容新增字段，拒绝不支持的结构版本。
120
+ ```powershell
121
+ npx canship --baseline-write
122
+ ```
98
123
 
99
- - `findings`：抑制及展示筛选后的结果。
100
- - `hiddenLikely`、`baselineSuppressed`、`baselineStale`：筛选与基线统计。
101
- - `partial`、`errors`、`skipped`、`filesScanned`：扫描完整性，须独立于退出码检查。
102
- - `changeView`：启用变更视图时的筛选统计及全量扫描统计。
124
+ ```powershell
125
+ npx canship --baseline
126
+ ```
127
+
128
+ 默认路径相对扫描目录，显式路径相对工作目录；读取与写入模式互斥。写入成功退出 `0`，不代表扫描无问题；扫描不完整或启用规则筛选时会提示。
103
129
 
104
- SARIF 包含执行诊断与证据关联位置。`--list-rules --json` 返回独立的 `kind: "rule-catalog"` 文档。
130
+ v2 指纹不受行号移动影响，凭据变化会改变指纹。缺失、损坏及 v1 基线均退出 `3`。基线不含摘录，但保留路径、规则和描述，提交前需审阅。
105
131
 
106
- ## 程序化 API
132
+ ## API
107
133
 
108
- 提供 Node.js ESM 入口及 TypeScript 类型：
134
+ 提供 Node.js ESM 入口与 TypeScript 类型：
109
135
 
110
136
  ```js
111
137
  import { scan, summarize, listRules } from 'canship'
@@ -115,13 +141,13 @@ console.log(summarize(result))
115
141
  console.log(listRules())
116
142
  ```
117
143
 
118
- `scan()` 返回全部置信度结果，支持 `only`、`skip`、`honorIgnoreMarkers`（默认 `true`）、`noExcerpts`（默认 `false`）。不读取项目配置、不应用基线、不写报告、不设置进程退出码。无效参数或根目录抛出异常；扫描缺口保留在结果中。
144
+ `scan()` 返回全部置信度结果，支持 `only`、`skip`、`honorIgnoreMarkers`（默认 `true`）、`noExcerpts`（默认 `false`）。不加载配置、不应用基线、不写报告、不设置退出码。无效参数或根目录抛出异常；扫描缺口保留在结果中。
119
145
 
120
- `summarize()` 返回结果数、阻断数、疑似数、`partial` 及默认 CLI 退出码。`listRules()` 返回独立的规则目录副本。
146
+ `summarize()` 返回结果统计、`partial` 及默认 CLI 退出码。`listRules()` 返回独立的规则目录副本。
121
147
 
122
148
  ## GitHub Action
123
149
 
124
- 保存为 `.github/workflows/canship.yml`。Action 安装指定 npm 版本，扫描检出目录并生成统计摘要；不安装或执行项目依赖，SARIF 需显式启用上传。
150
+ 保存为 `.github/workflows/canship.yml`。Action 安装指定 npm 扫描器并输出统计摘要，不安装或运行项目依赖；SARIF 需显式启用上传。
125
151
 
126
152
  ```yaml
127
153
  name: canship
@@ -136,78 +162,47 @@ jobs:
136
162
  with:
137
163
  fetch-depth: 0
138
164
  persist-credentials: false
139
- - uses: Tasomei/canship@b4cbbfe6b5c4c88164b9388d121f7651032259a4
165
+ - uses: Tasomei/canship@dfc17be52684314c8631d665074c133bf1170888
140
166
  with:
141
- version: '0.4.0'
167
+ version: '0.5.0'
168
+ honor-ignore-markers: false
142
169
  ```
143
170
 
144
- 提交号固定 Action 实现；`version` 选择 npm 扫描器，不使用仓库源码。该固定提交默认安装 0.3.2；示例显式选择 0.4.0。
171
+ 提交号固定 Action 实现；`version` 选择 npm 扫描器，不使用仓库源码。该固定实现默认安装 0.4.0。
145
172
 
146
173
  | 输入 | 默认值 | 说明 |
147
174
  |---|---|---|
148
- | `path` | `.` | 检出目录内的扫描路径 |
149
- | `version` | `0.3.2` | 精确 npm 版本，不接受范围或标签 |
175
+ | `version` | `0.4.0` | 精确 npm 版本，不接受范围或标签 |
150
176
  | `fail-on` | `blocking` | `blocking`：确定的 P0/P1；`any`：全部结果；`none`：仅报告 |
151
- | `only` / `skip` | 未设置 | 互斥的规则选择器 |
152
- | `baseline` | 未设置 | 相对扫描目录的已有基线 |
153
177
  | `use-config` | `false` | 启用项目配置 |
178
+ | `honor-ignore-markers` | `true` | 遵从整文件及逐行忽略注释 |
154
179
  | `upload-sarif` | `false` | 上传至 GitHub 代码扫描 |
155
- | `category` | `canship` | 扫描目标的 SARIF 分类 |
156
-
157
- 输出：`exit-code`、`findings`、`blocking`、`partial`。统计包含基线与排除处理后的疑似结果。扫描不完整、工具错误或报告不兼容始终失败，`fail-on: none` 也不例外。
158
-
159
- 上传 SARIF 需 `security-events: write` 及 [代码扫描支持](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；需要其他版本时使用独立扫描任务。
160
-
161
- ## 配置与基线
162
-
163
- 扫描目录中的 `canship.config.json` 支持 `baseline`、`only`、`skip`、`all`：
164
-
165
- ```json
166
- {
167
- "skip": ["cors/wildcard-with-credentials"],
168
- "all": false
169
- }
170
- ```
171
-
172
- 命令行参数优先。`only`、`skip` 互斥，接受规则 ID 或命名空间。`--best-effort` 仅限命令行。扫描不可信项目时使用 `--no-config --no-ignore-markers`。
173
-
174
- ### 忽略标记
175
-
176
- 独占注释行的 `canship-ignore-file` 排除整个文件；`canship-ignore-next-line` 抑制下一行，可限定规则：
177
-
178
- ```ts
179
- // canship-ignore-next-line cors/wildcard-with-credentials
180
- const corsOptions = { origin: '*', credentials: true }
181
- ```
182
-
183
- 报告披露排除与抑制信息。主动排除不标记为未完成，可使退出码降为 `0`。`--no-config` 不禁用标记，`--no-ignore-markers` 才会禁用。
184
-
185
- ### 基线
186
-
187
- 记录已有结果：
188
180
 
189
- ```powershell
190
- npx canship --baseline-write
191
- ```
192
-
193
- 后续扫描抑制这些结果：
194
-
195
- ```powershell
196
- npx canship --baseline
197
- ```
181
+ 路径、规则筛选、基线及分类输入见 [action.yml](./action.yml)。
198
182
 
199
- 默认路径相对扫描目录，显式路径相对工作目录；读取与写入模式互斥。写入成功退出 `0`，不表示无问题；扫描不完整或启用规则筛选时会提示。
183
+ 输出：`exit-code`、`findings`、`blocking`、`partial`。统计包含抑制后的疑似结果。扫描不完整、工具错误或报告不兼容始终失败，`fail-on: none` 也不例外。
200
184
 
201
- 基线格式为 v2，移动行号不改变指纹，替换凭据会改变。缺失、损坏及 v1 基线均退出 `3`。基线不含源码摘录，但包含路径、规则和问题描述，提交前需审阅。
185
+ 上传 SARIF 需 `security-events: write` 及代码扫描支持；Fork PR 可能权限不足。上传前需审阅报告。不可信 PR 使用 `pull_request`，不要使用 `pull_request_target`。Action 设置 Node.js 22，必要时使用独立扫描任务。
202
186
 
203
187
  ## 隐私与限制
204
188
 
205
- - 静态检查可能漏报或将预期配置报为问题，不验证线上行为，不覆盖限流、注入、依赖漏洞或业务授权。无结果不等于安全。
206
- - 脱敏仅覆盖已识别格式。未识别的敏感值可能保留在摘录中；`--no-excerpts` 移除摘录，并设置 JSON `excerptsOmitted`。路径、名称、说明和基线不匿名化。
189
+ - 静态检查可能漏报或将预期配置报为问题，不验证线上行为、业务授权、限流、注入或依赖漏洞。无结果不等于安全。
190
+ - 脱敏仅覆盖已识别格式。未知敏感值可能保留在摘录中；`--no-excerpts` 移除摘录并设置 JSON `excerptsOmitted`。路径、名称、描述和基线不匿名化。
207
191
  - Google/Firebase/Maps 的 `AIza...` 密钥按公开标识符处理，不单凭其值判定泄露。
208
- - 读取上限：单文件 2 MiB，单次 128 MiB、10,000 个文件，目录 16 层。每文件跨规则最多 100 条结果，优先保留高严重度、高置信度结果。
209
- - Git 历史每文件最多 100 个相关版本，单条命令超时 30 秒；Supabase 策略及存储桶语句最多解析 4,000 个字符。超限报告扫描未完成。
210
- - 不跟随符号链接；嵌套仓库、子模块需单独扫描。范围内跳过项使扫描未完成，内置排除的依赖和构建目录除外。
192
+ - Supabase 检查依据本地迁移及支持的存储桶配置，不检查控制台专属改动或省略子句隐含的策略条件。
193
+ - 不跟随符号链接；嵌套仓库与子模块需单独扫描。范围内跳过项使扫描未完成，内置依赖/构建目录排除除外。
194
+
195
+ | 限制 | 上限 |
196
+ |---|---|
197
+ | 文件读取，含探测 | 单文件 2 MiB；单次 128 MiB、10,000 个文件 |
198
+ | 目录遍历 | 50,000 个条目、16 层 |
199
+ | 结果数量 | 每文件 100 条，优先保留高严重度、高置信度结果 |
200
+ | Git 历史 | 每文件 100 个相关版本；单条命令 30 秒 |
201
+ | 鉴权解析 | 8 跳；每个路由文件 128 个符号 |
202
+ | 身份/控制流 | 值解析 8 步；表达式 4,000 字符；每函数 512 个赋值/条件区域；分支/异常区域嵌套 8 层 |
203
+ | Supabase 策略/存储桶解析 | 单条语句 4,000 字符 |
204
+
205
+ 扫描或分析超限会报告未完成。证据链最多 24 步，截断时提示。身份获取函数名及导入关系仍属语法证据，不验证运行时实现。
211
206
 
212
207
  ## 开发
213
208
 
@@ -223,26 +218,14 @@ npm run prepublishOnly
223
218
  npm run test:package
224
219
  ```
225
220
 
226
- 新增规则需包含应检出与不应检出的 [夹具](./test/fixtures/)。运行离线 [评估集](./test/fixtures/evaluation/)：
221
+ 新增规则须包含应检出与不应检出的 [夹具](./test/fixtures/)。运行离线评估：
227
222
 
228
223
  ```powershell
229
224
  npm run evaluate
230
225
  ```
231
226
 
232
- [应用快照](./test/evaluation/projects.json) 需先联网获取并校验来源，目标为 Git 仓库外的新目录：
233
-
234
- ```powershell
235
- node scripts/fetch-evaluation-projects.mjs "$env:TEMP/canship-evaluation"
236
- ```
237
-
238
- 随后离线评估：
239
-
240
- ```powershell
241
- npm run evaluate:projects -- "$env:TEMP/canship-evaluation"
242
- ```
243
-
244
- 项目评估使用临时副本，比较原项目及开放、受限测试变体的全部结果，不安装或运行样本依赖。这些测试不衡量真实项目检出率、Git 历史覆盖率或线上行为。
227
+ 应用评估见 [快照清单](./test/evaluation/projects.json)、[获取脚本](./scripts/fetch-evaluation-projects.mjs) 及 [离线评估器](./scripts/evaluate-projects.ts)。测试在临时副本中比较原项目与成对变体，不运行样本依赖；不衡量真实检出率、Git 历史覆盖率或线上行为。
245
228
 
246
229
  ## 许可
247
230
 
248
- [MIT](./LICENSE)。Supabase、Firebase 夹具保留 Apache-2.0，Next.js、`cors` 夹具保留 MIT；来源与许可证随夹具保存。
231
+ [MIT](./LICENSE)。Supabase/Firebase 夹具保留 Apache-2.0，Next.js/`cors` 夹具保留 MIT；来源与许可证随夹具保存。