canship 0.2.0 → 0.3.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.
- package/README-zh-CN.md +199 -0
- package/README.md +199 -204
- package/dist/cli.js +491 -293
- package/package.json +7 -2
- package/schemas/scan-report-v1.schema.json +95 -0
- package/README.zh-CN.md +0 -206
package/README-zh-CN.md
ADDED
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
# canship
|
|
2
|
+
|
|
3
|
+
面向 JavaScript / TypeScript 项目的本地静态扫描器，检测凭据暴露与访问控制配置错误。扫描不执行项目代码、不上传文件、不联网。
|
|
4
|
+
|
|
5
|
+
本文档对应 0.3.x，适用于匹配的 [npm 版本](https://www.npmjs.com/package/canship) 或本地构建。
|
|
6
|
+
|
|
7
|
+
```powershell
|
|
8
|
+
npx canship .
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
要求 Node.js ≥18，无运行时依赖。`npx` 可能联网下载软件包；扫描仅使用本地文件与 Git 历史。Git 仓库中无法调用 Git 时，扫描标记为未完成。
|
|
12
|
+
|
|
13
|
+
[English](./README.md)
|
|
14
|
+
|
|
15
|
+
## 检测范围
|
|
16
|
+
|
|
17
|
+
| 检查项 | 级别 |
|
|
18
|
+
|---|---|
|
|
19
|
+
| 硬编码凭据、私钥及含密码的数据库连接串 | P0 |
|
|
20
|
+
| 公开环境变量中的私密值 | P0 |
|
|
21
|
+
| Supabase 管理员密钥暴露至客户端 | P0 |
|
|
22
|
+
| Git 跟踪及历史 `.env` 文件中的凭据或疑似私密值 | P0 |
|
|
23
|
+
| Supabase 迁移记录中未启用行级安全（RLS）的表 | P1 |
|
|
24
|
+
| Firebase 无条件访问及固定日期测试规则 | P1 |
|
|
25
|
+
| Next.js API 数据操作未识别到鉴权 | P0 / P1 |
|
|
26
|
+
| 携带凭据的 CORS 来源回显或通配符配置 | P1 / P2 |
|
|
27
|
+
|
|
28
|
+
支持 OpenAI、Anthropic、AWS、Stripe、GitHub、npm、Slack、SendGrid 等凭据格式及常见前端公开环境变量前缀。API 鉴权检查仅覆盖 Next.js `/api`，支持 App Router、Pages Router、路由组和工作区应用。
|
|
29
|
+
|
|
30
|
+
置信度分为确定（`certain`）和疑似（`likely`），仅描述静态证据，不验证凭据有效性或线上状态。默认只展示确定结果；隐藏的疑似结果仍影响退出码。
|
|
31
|
+
|
|
32
|
+
## 用法
|
|
33
|
+
|
|
34
|
+
省略路径时扫描当前目录。
|
|
35
|
+
|
|
36
|
+
| 参数 | 说明 |
|
|
37
|
+
|---|---|
|
|
38
|
+
| `-a`, `--all` | 展示疑似结果 |
|
|
39
|
+
| `--json` | 输出 JSON |
|
|
40
|
+
| `--fix-prompt` | 输出修复指令及独立的人工操作清单 |
|
|
41
|
+
| `--report[=file]` | 写入 HTML，默认 `canship-report.html` |
|
|
42
|
+
| `--sarif[=file]` | 写入 SARIF 2.1.0，默认 `canship.sarif` |
|
|
43
|
+
| `--best-effort` | 无结果时，允许不完整扫描退出 `0` |
|
|
44
|
+
| `--baseline[=file]` | 应用基线，默认 `canship-baseline.json` |
|
|
45
|
+
| `--baseline-write[=file]` | 写入当前结果为基线后退出，同上默认路径 |
|
|
46
|
+
| `--only=ids` | 仅执行匹配规则，支持逗号分隔及重复参数 |
|
|
47
|
+
| `--skip=ids` | 排除匹配规则，支持逗号分隔及重复参数 |
|
|
48
|
+
| `--no-config` | 忽略项目配置 |
|
|
49
|
+
| `--list-rules` | 列出规则及限制，不扫描；支持 `--json` |
|
|
50
|
+
| `--no-excerpts` | 所有报告省略源码摘录，不改变结果和退出码 |
|
|
51
|
+
| `-h`, `--help` | 显示帮助 |
|
|
52
|
+
| `-v`, `--version` | 显示版本 |
|
|
53
|
+
|
|
54
|
+
`--json` 与 `--fix-prompt` 互斥；HTML、SARIF 可与任一模式组合。报告正文为英文，`--all` 对所有格式生效。
|
|
55
|
+
|
|
56
|
+
### 退出码
|
|
57
|
+
|
|
58
|
+
| 退出码 | 含义 |
|
|
59
|
+
|---|---|
|
|
60
|
+
| `0` | 无结果，且扫描完整或由 `--best-effort` 接受不完整扫描 |
|
|
61
|
+
| `1` | 存在 `certain` 的 P0/P1 结果 |
|
|
62
|
+
| `2` | 存在其他结果，包括被隐藏的 `likely` |
|
|
63
|
+
| `3` | 参数或工具错误，或未被接受的不完整扫描 |
|
|
64
|
+
|
|
65
|
+
结果退出码优先于不完整状态；`--best-effort` 不改变 `1` 或 `2`。
|
|
66
|
+
|
|
67
|
+
### 机器可读输出
|
|
68
|
+
|
|
69
|
+
JSON 使用独立于包版本的 `schemaVersion: 1`，npm 包附带 [结构定义](./schemas/scan-report-v1.schema.json)。调用方应兼容新增字段、拒绝不支持的结构版本；`--list-rules --json` 为独立的 `kind: "rule-catalog"` 文档。
|
|
70
|
+
|
|
71
|
+
`findings` 为抑制和筛选后的结果；`hiddenLikely`、`baselineSuppressed`、`baselineStale` 提供相关统计。完整性需另查 `partial`、`errors`、`skipped`、`filesScanned`；SARIF 提供执行状态与诊断通知。
|
|
72
|
+
|
|
73
|
+
## GitHub Action
|
|
74
|
+
|
|
75
|
+
保存为 `.github/workflows/canship.yml`，在推送和 PR 时扫描并生成统计摘要。安装扫描器需要联网，扫描不联网；不安装或执行项目依赖，默认不上传 SARIF。
|
|
76
|
+
|
|
77
|
+
示例固定 Action 提交，安装 npm 版 `0.2.1`；`version` 不使用仓库中的未发布源码。Action 兼容 0.2.1 无 `schemaVersion` 的报告。
|
|
78
|
+
|
|
79
|
+
```yaml
|
|
80
|
+
name: canship
|
|
81
|
+
on: [push, pull_request]
|
|
82
|
+
permissions:
|
|
83
|
+
contents: read
|
|
84
|
+
jobs:
|
|
85
|
+
scan:
|
|
86
|
+
runs-on: ubuntu-latest
|
|
87
|
+
steps:
|
|
88
|
+
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803
|
|
89
|
+
with:
|
|
90
|
+
fetch-depth: 0
|
|
91
|
+
persist-credentials: false
|
|
92
|
+
- uses: Tasomei/canship@37cf06e014168968a88679157564e5c489f99c50
|
|
93
|
+
with:
|
|
94
|
+
version: '0.2.1'
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
| 输入 | 默认值 | 说明 |
|
|
98
|
+
|---|---|---|
|
|
99
|
+
| `path` | `.` | 检出目录内的扫描路径 |
|
|
100
|
+
| `version` | `0.2.1` | 精确 npm 版本，不接受范围或标签 |
|
|
101
|
+
| `fail-on` | `blocking` | `blocking`：确定的 P0/P1；`any`：全部结果；`none`：仅报告结果 |
|
|
102
|
+
| `only` / `skip` | 未设置 | 互斥，逗号分隔的规则选择器 |
|
|
103
|
+
| `baseline` | 未设置 | 相对扫描目录的已有基线 |
|
|
104
|
+
| `use-config` | `false` | 启用项目配置 |
|
|
105
|
+
| `upload-sarif` | `false` | 上传 SARIF 至 GitHub 代码扫描 |
|
|
106
|
+
| `category` | `canship` | 每个扫描目标使用独立分类 |
|
|
107
|
+
|
|
108
|
+
输出：`exit-code`、`findings`、`blocking`、`partial`。策略统计包含疑似结果，基线与忽略仍生效；扫描不完整、工具错误或报告不兼容始终失败，包括 `fail-on: none`。
|
|
109
|
+
|
|
110
|
+
上传 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，需要其他版本时应使用独立扫描任务。
|
|
111
|
+
|
|
112
|
+
## 配置与基线
|
|
113
|
+
|
|
114
|
+
扫描目录中的 `canship.config.json` 支持 `baseline`、`only`、`skip`、`all`：
|
|
115
|
+
|
|
116
|
+
```json
|
|
117
|
+
{
|
|
118
|
+
"skip": ["cors/wildcard-with-credentials"],
|
|
119
|
+
"all": false
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
命令行参数优先；`only`、`skip` 互斥，接受规则 ID 或命名空间。未选规则不执行，`ruleSelection.removed` 仅统计已执行规则中被过滤的结果。扫描不可信项目时使用 `--no-config`；`bestEffort` 仅限命令行设置。
|
|
124
|
+
|
|
125
|
+
### 忽略标记
|
|
126
|
+
|
|
127
|
+
独占注释行的 `canship-ignore-file` 排除整个文件；`canship-ignore-next-line` 忽略下一行，可附规则 ID：
|
|
128
|
+
|
|
129
|
+
```ts
|
|
130
|
+
// canship-ignore-next-line cors/wildcard-with-credentials
|
|
131
|
+
const corsOptions = { origin: '*', credentials: true }
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
报告披露忽略、规则筛选和基线抑制信息；主动排除不标记为未完成。
|
|
135
|
+
|
|
136
|
+
### 基线
|
|
137
|
+
|
|
138
|
+
记录已有结果：
|
|
139
|
+
|
|
140
|
+
```powershell
|
|
141
|
+
npx canship --baseline-write
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
仅报告新增结果：
|
|
145
|
+
|
|
146
|
+
```powershell
|
|
147
|
+
npx canship --baseline
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
默认基线位于扫描目录，显式路径相对工作目录。写入成功退出 `0`，不代表无问题；扫描不完整或启用规则筛选时会提示。
|
|
151
|
+
|
|
152
|
+
基线格式为 v2，移动行号不改变指纹，替换凭据会改变。缺失、损坏及 v1 基线均退出 `3`。基线不含源码，但包含路径、规则和问题描述，提交前需审阅。
|
|
153
|
+
|
|
154
|
+
## 隐私与限制
|
|
155
|
+
|
|
156
|
+
- 静态分析可能误报或漏报，不验证线上行为，不覆盖限流、注入、依赖漏洞或业务授权。无结果不等于安全。
|
|
157
|
+
- 脱敏仅覆盖已识别格式，未知秘密可能出现在源码摘录中。`--no-excerpts` 省略摘录，JSON 以 `excerptsOmitted` 标明；路径、名称、说明及基线不匿名化，分享前仍需审阅。
|
|
158
|
+
- Google/Firebase/Maps 的 `AIza...` 值按公开标识符处理，不单凭其值判定泄露。
|
|
159
|
+
- 读取上限：单文件 2 MiB，单次 128 MiB、10,000 个文件，目录 16 层。每文件跨规则最多 100 条结果，优先保留高严重度、高置信度结果。
|
|
160
|
+
- Git 历史每文件最多 100 个相关版本，单条 Git 命令超时 30 秒。超限、超时均报告检查缺口。
|
|
161
|
+
- 不跟随符号链接；嵌套仓库、子模块需单独扫描。范围内跳过项使扫描未完成，内置排除的构建和依赖目录除外。
|
|
162
|
+
|
|
163
|
+
## 开发
|
|
164
|
+
|
|
165
|
+
新增规则需包含应检出与不应检出的 [测试用例](./test/fixtures/)。
|
|
166
|
+
|
|
167
|
+
```powershell
|
|
168
|
+
npm ci
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
```powershell
|
|
172
|
+
npm run prepublishOnly
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
离线评估：
|
|
176
|
+
|
|
177
|
+
```powershell
|
|
178
|
+
npm run evaluate
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
评估集含 10 个构造用例、9 个固定版本上游示例及变体，同时纳入 `npm test`；[来源与许可](./test/fixtures/evaluation/) 随样本保存。断言覆盖规则、文件、严重度、置信度与扫描完整性，不代表真实项目检出率。
|
|
182
|
+
|
|
183
|
+
另有 5 个 [应用目录快照](./test/evaluation/projects.json)。准备阶段联网并校验 Git 对象摘要，目标须为 Git 仓库外的新目录：
|
|
184
|
+
|
|
185
|
+
```powershell
|
|
186
|
+
node scripts/fetch-evaluation-projects.mjs "$env:TEMP/canship-evaluation"
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
随后离线评估，不安装或运行样本依赖：
|
|
190
|
+
|
|
191
|
+
```powershell
|
|
192
|
+
npm run evaluate:projects -- "$env:TEMP/canship-evaluation"
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
CI 使用同一评估集，不验证 Git 历史或线上行为。
|
|
196
|
+
|
|
197
|
+
## 许可
|
|
198
|
+
|
|
199
|
+
[MIT](./LICENSE)。Supabase、Firebase 样本保留 Apache-2.0，Next.js、`cors` 样本保留 MIT；各样本附来源及许可证。
|
package/README.md
CHANGED
|
@@ -1,204 +1,199 @@
|
|
|
1
|
-
# canship
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
|
20
|
-
|
|
21
|
-
|
|
|
22
|
-
|
|
|
23
|
-
| Supabase
|
|
24
|
-
|
|
|
25
|
-
|
|
|
26
|
-
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
|
45
|
-
|
|
46
|
-
|
|
|
47
|
-
| `--
|
|
48
|
-
| `--
|
|
49
|
-
| `--
|
|
50
|
-
| `--
|
|
51
|
-
| `--
|
|
52
|
-
| `--
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
-
|
|
157
|
-
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
## License
|
|
203
|
-
|
|
204
|
-
[MIT](./LICENSE)
|
|
1
|
+
# canship
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
This documentation covers 0.3.x: use a matching [npm version](https://www.npmjs.com/package/canship) or local build.
|
|
6
|
+
|
|
7
|
+
```powershell
|
|
8
|
+
npx canship .
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
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.
|
|
12
|
+
|
|
13
|
+
[简体中文](./README-zh-CN.md)
|
|
14
|
+
|
|
15
|
+
## Checks
|
|
16
|
+
|
|
17
|
+
| Check | Severity |
|
|
18
|
+
|---|---|
|
|
19
|
+
| Hardcoded credentials, private keys, and database URLs containing passwords | P0 |
|
|
20
|
+
| Private values in public environment variables | P0 |
|
|
21
|
+
| Supabase admin keys exposed to clients | P0 |
|
|
22
|
+
| Credentials or suspected private values in Git-tracked and historical `.env` files | P0 |
|
|
23
|
+
| Supabase tables without Row Level Security (RLS) in migrations | P1 |
|
|
24
|
+
| Firebase unconditional access and date-based test rules | P1 |
|
|
25
|
+
| Next.js API data operations without recognised authentication | P0 / P1 |
|
|
26
|
+
| Credentialed CORS with reflected or wildcard origins | P1 / P2 |
|
|
27
|
+
|
|
28
|
+
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.
|
|
29
|
+
|
|
30
|
+
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.
|
|
31
|
+
|
|
32
|
+
## Usage
|
|
33
|
+
|
|
34
|
+
Omitting the path scans the current directory.
|
|
35
|
+
|
|
36
|
+
| Option | Description |
|
|
37
|
+
|---|---|
|
|
38
|
+
| `-a`, `--all` | Include likely findings |
|
|
39
|
+
| `--json` | Output JSON |
|
|
40
|
+
| `--fix-prompt` | Output remediation instructions and separate manual actions |
|
|
41
|
+
| `--report[=file]` | Write HTML; default: `canship-report.html` |
|
|
42
|
+
| `--sarif[=file]` | Write SARIF 2.1.0; default: `canship.sarif` |
|
|
43
|
+
| `--best-effort` | Permit exit `0` for an incomplete scan with no findings |
|
|
44
|
+
| `--baseline[=file]` | Apply a baseline; default: `canship-baseline.json` |
|
|
45
|
+
| `--baseline-write[=file]` | Write current findings as a baseline and exit; same default path |
|
|
46
|
+
| `--only=ids` | Run matching rules; comma-separated and repeatable |
|
|
47
|
+
| `--skip=ids` | Exclude matching rules; comma-separated and repeatable |
|
|
48
|
+
| `--no-config` | Ignore project configuration |
|
|
49
|
+
| `--list-rules` | List rules and limits without scanning; supports `--json` |
|
|
50
|
+
| `--no-excerpts` | Omit source excerpts from every report; preserve findings and exit status |
|
|
51
|
+
| `-h`, `--help` | Show help |
|
|
52
|
+
| `-v`, `--version` | Show version |
|
|
53
|
+
|
|
54
|
+
`--json` and `--fix-prompt` are mutually exclusive; HTML and SARIF work with either. Reports are in English. `--all` applies to every format.
|
|
55
|
+
|
|
56
|
+
### Exit codes
|
|
57
|
+
|
|
58
|
+
| Code | Meaning |
|
|
59
|
+
|---|---|
|
|
60
|
+
| `0` | No findings, with a complete scan or an incomplete scan accepted by `--best-effort` |
|
|
61
|
+
| `1` | At least one certain P0/P1 finding |
|
|
62
|
+
| `2` | Other findings, including hidden likely findings |
|
|
63
|
+
| `3` | Invalid arguments, a tool error, or an unaccepted incomplete scan |
|
|
64
|
+
|
|
65
|
+
Finding exit codes take precedence over incompleteness; `--best-effort` does not change `1` or `2`.
|
|
66
|
+
|
|
67
|
+
### Machine-readable output
|
|
68
|
+
|
|
69
|
+
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.
|
|
70
|
+
|
|
71
|
+
`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.
|
|
72
|
+
|
|
73
|
+
## GitHub Action
|
|
74
|
+
|
|
75
|
+
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.
|
|
76
|
+
|
|
77
|
+
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`.
|
|
78
|
+
|
|
79
|
+
```yaml
|
|
80
|
+
name: canship
|
|
81
|
+
on: [push, pull_request]
|
|
82
|
+
permissions:
|
|
83
|
+
contents: read
|
|
84
|
+
jobs:
|
|
85
|
+
scan:
|
|
86
|
+
runs-on: ubuntu-latest
|
|
87
|
+
steps:
|
|
88
|
+
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803
|
|
89
|
+
with:
|
|
90
|
+
fetch-depth: 0
|
|
91
|
+
persist-credentials: false
|
|
92
|
+
- uses: Tasomei/canship@37cf06e014168968a88679157564e5c489f99c50
|
|
93
|
+
with:
|
|
94
|
+
version: '0.2.1'
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
| Input | Default | Meaning |
|
|
98
|
+
|---|---|---|
|
|
99
|
+
| `path` | `.` | Directory within the checkout |
|
|
100
|
+
| `version` | `0.2.1` | Exact npm version; no ranges or tags |
|
|
101
|
+
| `fail-on` | `blocking` | `blocking`: certain P0/P1; `any`: all findings; `none`: findings only reported |
|
|
102
|
+
| `only` / `skip` | unset | Mutually exclusive, comma-separated rule selectors |
|
|
103
|
+
| `baseline` | unset | Existing baseline relative to the scanned directory |
|
|
104
|
+
| `use-config` | `false` | Enable project configuration |
|
|
105
|
+
| `upload-sarif` | `false` | Upload SARIF to GitHub code scanning |
|
|
106
|
+
| `category` | `canship` | Distinct SARIF category for each scan target |
|
|
107
|
+
|
|
108
|
+
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`.
|
|
109
|
+
|
|
110
|
+
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.
|
|
111
|
+
|
|
112
|
+
## Configuration and baselines
|
|
113
|
+
|
|
114
|
+
Place `canship.config.json` in the scanned directory. Supported keys: `baseline`, `only`, `skip`, `all`.
|
|
115
|
+
|
|
116
|
+
```json
|
|
117
|
+
{
|
|
118
|
+
"skip": ["cors/wildcard-with-credentials"],
|
|
119
|
+
"all": false
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
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.
|
|
124
|
+
|
|
125
|
+
### Ignore markers
|
|
126
|
+
|
|
127
|
+
A standalone `canship-ignore-file` comment excludes a file; `canship-ignore-next-line` suppresses the next line, with an optional rule ID:
|
|
128
|
+
|
|
129
|
+
```ts
|
|
130
|
+
// canship-ignore-next-line cors/wildcard-with-credentials
|
|
131
|
+
const corsOptions = { origin: '*', credentials: true }
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Reports disclose exclusions, rule selection, and baseline suppression. Deliberate exclusions do not mark the scan incomplete.
|
|
135
|
+
|
|
136
|
+
### Baselines
|
|
137
|
+
|
|
138
|
+
Record existing findings:
|
|
139
|
+
|
|
140
|
+
```powershell
|
|
141
|
+
npx canship --baseline-write
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Report only new findings:
|
|
145
|
+
|
|
146
|
+
```powershell
|
|
147
|
+
npx canship --baseline
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
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.
|
|
151
|
+
|
|
152
|
+
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.
|
|
153
|
+
|
|
154
|
+
## Privacy and limitations
|
|
155
|
+
|
|
156
|
+
- 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.
|
|
157
|
+
- 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.
|
|
158
|
+
- Google/Firebase/Maps `AIza...` values are public identifiers, not evidence of a leak on their own.
|
|
159
|
+
- 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.
|
|
160
|
+
- 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.
|
|
161
|
+
- 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.
|
|
162
|
+
|
|
163
|
+
## Development
|
|
164
|
+
|
|
165
|
+
New rules require positive and negative [test cases](./test/fixtures/).
|
|
166
|
+
|
|
167
|
+
```powershell
|
|
168
|
+
npm ci
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
```powershell
|
|
172
|
+
npm run prepublishOnly
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Offline evaluation:
|
|
176
|
+
|
|
177
|
+
```powershell
|
|
178
|
+
npm run evaluate
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
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.
|
|
182
|
+
|
|
183
|
+
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:
|
|
184
|
+
|
|
185
|
+
```powershell
|
|
186
|
+
node scripts/fetch-evaluation-projects.mjs "$env:TEMP/canship-evaluation"
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Then evaluate offline without installing or running sample dependencies:
|
|
190
|
+
|
|
191
|
+
```powershell
|
|
192
|
+
npm run evaluate:projects -- "$env:TEMP/canship-evaluation"
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
CI uses the same corpus. Git history and deployed behaviour are outside this evaluation.
|
|
196
|
+
|
|
197
|
+
## License
|
|
198
|
+
|
|
199
|
+
[MIT](./LICENSE). Supabase and Firebase fixtures retain Apache-2.0; Next.js and `cors` fixtures retain MIT. Each includes its source and licence.
|