canship 0.1.1 → 0.2.1

package/README-zh-CN.md

@@ -0,0 +1,125 @@
+# canship
+
+面向 JavaScript / TypeScript 项目的本地静态扫描器，检测凭据暴露和访问控制配置错误。不执行项目代码，不上传文件，扫描过程不联网。
+
+```powershell
+npx canship .
+```
+
+要求 Node.js ≥18，无运行时依赖。Git 用于读取本地历史；仓库中无法使用 Git 时，扫描标记为未完成。首次使用 `npx` 可能需要从 npm 下载软件包。
+
+[English](./README.md)
+
+## 检测范围
+
+| 检查项 | 级别 |
+|---|---|
+| 硬编码凭据、私钥及含密码的数据库连接串 | P0 |
+| 公开环境变量中的私密值 | P0 |
+| 客户端可访问的 Supabase 管理员密钥 | P0 |
+| Git 跟踪及历史 `.env` 文件中的凭据或疑似私密值 | P0 |
+| Supabase 表未启用行级安全（RLS） | P1 |
+| Firebase 无条件访问及固定日期测试规则 | 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、路由组和工作区应用。
+
+置信度分为确定（`certain`）和疑似（`likely`）。默认只展示确定结果；隐藏的疑似结果仍影响退出码。
+
+## 参数
+
+省略路径时扫描当前目录。
+
+| 参数 | 说明 |
+|---|---|
+| `-a`, `--all` | 展示疑似结果 |
+| `--json` | 输出 JSON |
+| `--fix-prompt` | 输出编程助手修复指令及独立的人工操作清单 |
+| `--report[=文件]` | 写入 HTML 报告，默认 `canship-report.html` |
+| `--sarif[=文件]` | 写入 SARIF 2.1.0 报告，默认 `canship.sarif` |
+| `--best-effort` | 无结果时，允许不完整扫描退出 `0` |
+| `--baseline[=文件]` | 应用基线，默认 `canship-baseline.json` |
+| `--baseline-write[=文件]` | 记录当前结果为基线后退出 |
+| `--only=规则` | 仅执行匹配规则，支持逗号分隔及重复参数 |
+| `--skip=规则` | 排除匹配规则，支持逗号分隔及重复参数 |
+| `--no-config` | 忽略项目配置 |
+| `-h`, `--help` | 显示帮助 |
+| `-v`, `--version` | 显示版本 |
+
+`--json` 与 `--fix-prompt` 互斥；HTML 和 SARIF 可与任一输出模式组合。报告正文为英文，各格式均用 `--all` 包含疑似结果。
+
+### 退出码
+
+| 退出码 | 含义 |
+|---|---|
+| `0` | 无结果且扫描完整，或由 `--best-effort` 接受不完整扫描 |
+| `1` | 存在 `certain` 的 P0/P1 结果 |
+| `2` | 存在其他结果，包括被隐藏的 `likely` |
+| `3` | 参数或工具错误，或未被接受的不完整扫描 |
+
+结果对应的退出码优先于不完整状态；`--best-effort` 不改变 `1` 或 `2`。JSON 用 `partial`、`errors`、`skipped` 保留完整性信息，SARIF 提供执行状态和诊断通知。
+
+## 配置与忽略
+
+扫描目录中的 `canship.config.json` 支持 `baseline`、`only`、`skip`、`all`：
+
+```json
+{
+  "skip": ["cors/wildcard-with-credentials"],
+  "all": false
+}
+```
+
+命令行参数优先；`only` 与 `skip` 互斥，接受完整规则 ID 或命名空间。无关规则不执行；`ruleSelection.removed` 仅统计已执行规则中被过滤的结果。扫描不可信项目时使用 `--no-config`；`bestEffort` 仅支持命令行设置。
+
+以独占注释行的 `canship-ignore-file` 排除整个文件，或用 `canship-ignore-next-line` 忽略下一行。后者可附加规则 ID：
+
+```ts
+// canship-ignore-next-line cors/wildcard-with-credentials
+const corsOptions = { origin: '*', credentials: true }
+```
+
+报告披露忽略、筛选和基线抑制信息。主动忽略不使扫描标记为未完成。
+
+## 基线
+
+记录已有结果：
+
+```powershell
+npx canship --baseline-write
+```
+
+仅报告新增结果：
+
+```powershell
+npx canship --baseline
+```
+
+裸参数使用扫描目录，显式路径相对工作目录。写入成功退出 `0`；扫描不完整或启用规则筛选时会提示。
+
+基线格式为第 2 版，不含源码摘录，但披露路径、规则、标题和问题类型，提交前需审阅。指纹不含行号，移动行号不会产生新结果，替换凭据会。缺失、损坏及第 1 版基线均退出 `3`。
+
+## 限制
+
+- 静态启发式分析可能误报或漏报，不验证运行时行为、限流、注入、依赖漏洞及业务授权。无发现不代表项目安全。
+- 脱敏仅覆盖已识别格式；未知秘密可能出现在证据行中，报告应作为内部材料。Google/Firebase/Maps 的 `AIza...` 值按公开标识符处理。
+- 单文件最多读取 2 MiB；单次累计读取最多 128 MiB、10,000 个文件；目录最多 16 层。跨规则每文件最多输出 100 条结果，优先保留高严重度、高置信度结果。
+- Git 历史每文件最多检查 100 个相关版本，单条 Git 命令超时为 30 秒。超限或超时均披露检查缺口。
+- 不跟随符号链接；嵌套仓库及子模块需分别扫描。扫描范围内的跳过项使扫描未完成，已排除的构建和依赖目录除外。
+
+## 开发
+
+检测规则需同时包含应检出和不应检出的用例，参见 [测试夹具](./test/fixtures/)。
+
+```powershell
+npm ci
+```
+
+```powershell
+npm run prepublishOnly
+```
+
+## 许可
+
+[MIT](./LICENSE)

package/README.md

@@ -1,111 +1,122 @@
 # canship
 
-canship is a read-only static scanner for JavaScript and TypeScript web projects. It detects exposed credentials, misuse of public environment variables, and access-control misconfigurations in Next.js, Vite, Nuxt, Create React App, Expo, Supabase, and Firebase projects.
+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.
 
-The scan does not execute project code, upload content, or initiate network requests. The npm package has no runtime dependencies. When scanning a Git repository, canship reads only the local working tree and local commit history.
-
-```bash
-npx canship
+```powershell
+npx canship .
 ```
 
-Node.js 18 or later is required. Git is optional; only commit-history checks require a local Git installation and a readable repository. If canship is not already in the npm cache, `npx` may download it from the npm registry before the scan starts; that download is performed by npm and is not part of the scan.
+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.
 
-[简体中文](./README.zh-CN.md)
+[简体中文](./README-zh-CN.md)
 
 ## Checks
 
-| Check | Risk | Severity |
-|---|---|---|
-| Hardcoded credentials | A scanned file contains a recognised OpenAI, Anthropic, AWS, Stripe, GitHub, npm, Slack, SendGrid, private-key, or database credential | P0 |
-| Private values in public environment variables | The value may be included in browser-delivered code | P0 |
-| Supabase `service_role` key reachable from client code | A `service_role` key can bypass Row Level Security (RLS) policies | P0 |
-| Git-tracked `.env` files | Recognised credentials remain in repository history; substantial unrecognised values may also produce a lower-confidence finding | P0 |
-| Supabase tables without RLS | A table exposed through the Supabase Data API lacks row-level access control | P1 |
-| Firebase rules allowing unconditional access | Unauthorised clients may be able to read or write data | P1 |
-| Next.js API routes accessing data without authentication | An unverified caller may access data or perform administrative operations | P0 / P1 |
-| CORS reflecting `Origin` while allowing credentials | Another site may access an endpoint with the user's credentials and read the response | P1 |
-
-Severity (P0, P1, P2) describes potential impact. Confidence (`certain`, `likely`) describes how strongly the code supports the finding. A `certain` P0/P1 finding blocks release and exits with status `1`; all other findings exit with status `2`.
-
-`Access-Control-Allow-Origin: *` combined with credentials is reported at P2 because browsers reject that configuration. A bare wildcard is not reported.
+| Check | Severity |
+|---|---|
+| Hardcoded credentials, private keys, and database URLs containing passwords | P0 |
+| Private values in public environment variables | P0 |
+| Client-accessible Supabase admin keys | P0 |
+| Credentials or suspected private values in Git-tracked and historical `.env` files | P0 |
+| Supabase tables without Row Level Security (RLS) | P1 |
+| Firebase unconditional access and date-based test rules | P1 |
+| Next.js API data operations without authentication | P0 / P1 |
+| Credentialed CORS with reflected or wildcard origins | P1 / P2 |
 
-For Git-tracked `.env` files, a recognised credential is reported at `certain` confidence. A substantial value that is not recognised but does not look public or placeholder-like is reported at `likely` confidence. Environment templates, public values, placeholders, and short settings do not trigger this Git rule solely because the file is tracked.
+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.
 
-## Usage
+Confidence is `certain` or `likely`. Only certain findings are shown by default; hidden likely findings still affect the exit code.
 
-```bash
-npx canship [path]
-```
+## Options
 
-The current directory is scanned when no path is provided.
+Omitting the path scans the current directory.
 
 | Option | Description |
 |---|---|
-| `-a`, `--all` | Show `likely` findings |
-| `--json` | Write machine-readable JSON |
-| `--fix-prompt` | Write remediation instructions for a coding assistant |
-| `--report[=file]` | Write a self-contained HTML report; defaults to `canship-report.html` |
-| `--best-effort` | Allow exit `0` when the scan is incomplete and has no findings; does not change the status of existing findings |
+| `-a`, `--all` | Include likely findings |
+| `--json` | Output JSON |
+| `--fix-prompt` | Output assistant 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 |
+| `--only=ids` | Run matching rules; comma-separated and repeatable |
+| `--skip=ids` | Exclude matching rules; comma-separated and repeatable |
+| `--no-config` | Ignore project configuration |
 | `-h`, `--help` | Show help |
-| `-v`, `--version` | Show the version |
+| `-v`, `--version` | Show version |
 
-`--json` and `--fix-prompt` are mutually exclusive. `--report` writes a separate file and may be combined with either mode.
+`--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.
 
-### Exit status
+### Exit codes
 
-| Status | Meaning |
+| Code | Meaning |
 |---|---|
-| `0` | No findings at any confidence and the scan completed; with `--best-effort`, it may also mean an incomplete scan was accepted |
-| `1` | At least one `certain` P0/P1 finding |
-| `2` | Findings exist, but none is a confirmed P0/P1 release blocker |
-| `3` | Invalid arguments, a tool error, or an incomplete scan without `--best-effort` |
+| `0` | No findings and a complete scan, or an incomplete scan accepted with `--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 |
 
-When findings and an incomplete scan coexist, status `1` or `2` takes precedence. The JSON fields `partial`, `errors`, and `skipped` still preserve the incomplete-scan state.
+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.
 
-The default view expands only `certain` findings. Hidden `likely` findings still produce status `2`; the terminal and HTML report display a warning, and JSON reports the count in `hiddenLikely`. Use `--all` to include their full details.
+## Configuration and suppressions
 
-### Excluding a file
+Place `canship.config.json` in the scanned directory. Supported keys: `baseline`, `only`, `skip`, `all`.
 
-Add `canship-ignore-file` on a line by itself to exclude the entire file. The marker may be wrapped only in `//`, `#`, `--`, `*`, `/* */`, or `<!-- -->` comment syntax. Intentionally excluded files are listed in the report and do not make the scan incomplete.
+```json
+{
+  "skip": ["cors/wildcard-with-credentials"],
+  "all": false
+}
+```
 
-### Remediation instructions
+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.
 
-`--fix-prompt` separates code changes that a coding assistant can perform from actions that require the project maintainer, such as rotating credentials, changing provider settings, or rewriting Git history.
+A standalone comment containing `canship-ignore-file` excludes a file. `canship-ignore-next-line` suppresses the next line and accepts an optional rule ID:
 
-## Rule activation
+```ts
+// canship-ignore-next-line cors/wildcard-with-credentials
+const corsOptions = { origin: '*', credentials: true }
+```
 
-| Rule | Activation conditions |
-|---|---|
-| Public environment variables | The name starts with `NEXT_PUBLIC_`, `VITE_`, `REACT_APP_`, `EXPO_PUBLIC_`, `NUXT_PUBLIC_`, `GATSBY_`, `VUE_APP_`, or `PUBLIC_` |
-| Git-tracked environment files | The target is inside a readable local Git repository whose `.git` metadata is inside the checkout or names it back; templates, public values, placeholders, and short settings are excluded, and at most the 100 most recent relevant revisions of each file are inspected |
-| Next.js API authentication | Only data-accessing handlers under `app/api/**` and `pages/api/**`; recognises enforcing authentication calls, identity conditions that control rejection, and middleware `matcher` coverage for the route |
-| Supabase RLS | The current project scope contains `supabase/`, an `@supabase/supabase-js` or `@supabase/ssr` import, or a `SUPABASE_URL`; table-related DDL is replayed across migrations within that project scope |
-| Other credential and configuration rules | Match known file formats and content patterns without requiring a specific front-end framework |
+Reports disclose exclusions, rule selection, and baseline suppression. Deliberate exclusions do not make the scan incomplete.
 
-## Known limitations
+## Baselines
 
-- canship uses static heuristics and does not verify runtime behaviour. Custom authentication wrappers, dynamic configuration, and unsupported syntax can cause false positives or false negatives.
-- Detection and redaction use the same credential patterns. A credential that canship cannot recognise cannot be guaranteed to be masked; if another rule quotes the same line, the original value may appear in the report. Treat reports as internal material.
-- Entropy-based detection is intentionally not used because random identifiers, hashes, and ordinary Base64 text cannot be classified reliably from entropy alone.
-- Files are limited to 2 MiB, traversal to 16 directory levels, and output to 100 findings per file. Git history checks inspect at most the 100 most recent relevant revisions of each file. Reaching a limit is recorded explicitly.
-- Symbolic links are not followed and make the scan incomplete.
-- Nested Git repositories and submodules are not expanded by the parent scan. They are listed as skipped and the parent scan is marked incomplete.
-- A `.git` file may point outside the checkout. canship follows it only when the target names this checkout back, which is what git records for a linked worktree and for a submodule. Anything else is read as a redirect to an unrelated repository: file scanning continues, history checks are marked incomplete.
-- Google, Firebase, and Maps `AIza...` keys are treated as public identifiers. Their application and API restrictions exist in Google Cloud and cannot be verified from local source, so the key value alone is not reported as a credential leak.
-- Rate limiting, injection, dependency vulnerabilities, and business authorisation beyond caller authentication are outside the scan scope.
+Record existing findings:
 
-A canship result describes only what the implemented rules observed in the files that were read. It is not proof that the project has no other security defects.
+```powershell
+npx canship --baseline-write
+```
+
+Report only new findings:
+
+```powershell
+npx canship --baseline
+```
 
-## Planned
+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.
 
-`--probe` is not implemented. The planned mode would, after explicit confirmation, issue read-only verification requests to service endpoints found in local project configuration. The current release does not initiate network requests.
+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`.
 
-## Contributing
+## Limitations
 
-Every new or changed detection rule should include at least two fixtures: one that must be reported and one that must not. See [`test/fixtures/`](./test/fixtures/).
+- 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.
 
-```bash
+## Development
+
+Detection rules require positive and negative cases; see [test fixtures](./test/fixtures/).
+
+```powershell
 npm ci
+```
+
+```powershell
 npm run prepublishOnly
 ```