cleartoship 0.7.0 → 0.9.0

package/ATTRIBUTION.md

@@ -0,0 +1,115 @@
+# Attribution
+
+ClearToShip vendors and adapts work from other projects. This file records what,
+from where, and under which licence.
+
+## Vendored code
+
+### GuardVibe — `src/vendor/guardvibe/`
+
+- Source: https://github.com/goklab/guardvibe
+- Copyright 2026 GokLab
+- Licence: Apache License 2.0 — full text in `LICENSES/guardvibe-Apache-2.0.txt`,
+  upstream NOTICE in `LICENSES/guardvibe-NOTICE.txt`
+
+468 security rules are vendored verbatim under `src/vendor/guardvibe/rules/`.
+Each file carries a provenance header. Rule content is **unmodified**; the only
+changes are the added headers and an aggregating `index.ts` written by this
+project.
+
+Modifications, as required by Apache-2.0 §4(b), are made at runtime in
+`src/scanners/community.ts` rather than in the vendored files:
+
+- **27 rules are superseded** by ClearToShip's own AST and schema checks, which
+  reason over a whole function body or a replayed migration rather than a fixed
+  character window. Running both would double-report the same defect and import
+  the less precise location. Each is listed with the rule that replaces it.
+- **5 rules are withheld** as measurably noisy in this tool's context — for
+  example `VG543`, which matches `; DROP|DELETE|INSERT …` anywhere in a `.sql`
+  file and therefore fires on the normal shape of every migration. Each is
+  listed with its reason.
+- Findings in test, fixture and documentation paths are reported at `low`.
+
+Every vendored finding carries `meta.source: "guardvibe"` and its attribution
+string, so provenance survives into JSON and SARIF output.
+
+### gitleaks — `src/vendor/gitleaks/rules.ts`
+
+- Source: https://github.com/gitleaks/gitleaks (`config/gitleaks.toml`)
+- Copyright (c) 2019 Zachary Rice
+- Licence: MIT — full text in `LICENSES/gitleaks-MIT.txt`
+
+221 of 222 credential detection rules are converted from the upstream TOML into
+a generated TypeScript module by `scripts/vendor-gitleaks.mjs`. Rule ids,
+descriptions, entropy thresholds and keyword prefilters are carried over
+unchanged.
+
+Modifications:
+
+- **Regex dialect.** Upstream patterns are Go RE2. A leading `(?i)` becomes the
+  JavaScript `i` flag and `(?P<n>)` becomes `(?<n>)`. 37 rules use *scoped*
+  inline flags — `(?i:…)`, `(?-i:…)` — which JavaScript has no equivalent for;
+  rather than drop them, the flag is hoisted to the whole pattern. The cost is
+  precision, not safety: a prefix upstream matched case-sensitively now matches
+  either way, and every match still has to clear the entropy threshold. One rule
+  could not be converted and is omitted.
+- **2 rules are withheld** as noisy, each with its reason in
+  `src/scanners/secrets.ts`: `generic-api-key` (gitleaks' own catch-all — 97 of 118 hits across the
+  reference corpus were false, including ordinary arrays of method names) and
+  `sourcegraph-access-token` (matches any 40-character hex string, so every
+  SHA-pinned GitHub Action reads as a leaked token).
+- Per-rule allowlists are not carried over; ClearToShip applies its own
+  placeholder, entropy, hex-digest and fixture-path filters instead.
+
+Findings carry `meta.source: "gitleaks"` and the attribution string.
+
+## Services queried
+
+### OSV.dev
+
+Known-vulnerability data comes from https://osv.dev via its public HTTP API —
+the same database behind Google's `osv-scanner` (Apache-2.0). Nothing is
+vendored and no licence attaches; ClearToShip queries the API at scan time.
+
+This is why the vendored CVE-version rules stand down whenever OSV answers: a
+rule that hard-codes "next before 14.1.1" is stale the week after it is written,
+while OSV is current. Offline (`--offline`), the vendored rules are the fallback.
+
+## Ideas adopted, code not copied
+
+These informed the rule set. No code, regex or rule text was taken.
+
+| Project | Licence | What it informed |
+| --- | --- | --- |
+| [supabase/splinter](https://github.com/supabase/splinter) | none stated | The vulnerability classes behind CTS010–019 and CTS050–052. Splinter queries a live database; ClearToShip reimplements these statically against migration files. |
+| [slopcheck](https://github.com/mattschaller/slopcheck) | MIT | Distinguishing HTTP 451 (pulled for malware) from 404 (never existed) from unpublished-with-installs (open to takeover) — CTS026/CTS027 — and reading install commands out of prose and agent instruction files. |
+
+## Licence status of every candidate considered
+
+Verified against the GitHub API and the repositories' own LICENSE files, because
+second-hand licence claims about these projects are frequently wrong.
+
+| Project | Actual licence | Usable in a commercial SaaS? |
+| --- | --- | --- |
+| gitleaks | MIT | **Yes** — vendored above |
+| google/osv-scanner | Apache-2.0 | Yes (we use the OSV API rather than the binary) |
+| aquasecurity/trivy | Apache-2.0 | Yes |
+| dependency-check/DependencyCheck | Apache-2.0 | Yes |
+| projectdiscovery/nuclei + templates | MIT | Yes (DAST — needs a running app, out of scope here) |
+| zaproxy/zaproxy | Apache-2.0 | Yes (DAST) |
+| OWASP/Nettacker | Apache-2.0 | Yes (recon) |
+| goklab/guardvibe | Apache-2.0 | **Yes** — vendored above |
+| octokit, probot, babel, zod, shadcn/ui | MIT / ISC | Yes |
+| semgrep/semgrep | **LGPL-2.1**, not Apache | Only as a subprocess. LGPL is copyleft; invoking the CLI is fine, linking it into the product is not. Its *rules* are separately under the Semgrep Rules License. |
+| trufflesecurity/trufflehog | **AGPL-3.0** | No, unless ClearToShip itself ships under AGPL. gitleaks is the permissive equivalent and is what we used. |
+| elicosilva/RouteWarden | AGPL-3.0 | Same. |
+| wapiti | GPL-2.0 | Subprocess only. |
+| sqlmap, nikto | GPL-2.0 | Subprocess only. |
+| **Bearer/bearer** | **Elastic License 2.0** | **No.** ELv2 specifically prohibits providing the software to third parties as a hosted or managed service — which is precisely what a ClearToShip SaaS would be. It is not an open-source licence. |
+| supabase/splinter | **none** | No licence file means no licence granted. Ideas only. |
+| bscript/supabase-exposure-check | none | Same. |
+
+Taking a part rather than the whole does not change any of this: copyright and
+the AGPL both apply to substantial portions, not only to entire programs. What
+is genuinely free to take is the *idea* — the class of vulnerability, the fact
+that a check is worth making. Expression (regexes, queries, rule prose) is not.

package/LICENSES/gitleaks-MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Zachary Rice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSES/guardvibe-Apache-2.0.txt

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 GokLab
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSES/guardvibe-NOTICE.txt

@@ -0,0 +1,4 @@
+GuardVibe
+Copyright 2026 GokLab
+
+Licensed under the Apache License, Version 2.0.

package/README.md

@@ -79,7 +79,15 @@ reaches a manifest.
 | **CTS033** | critical | `'use client'` component reaching for a server-only secret |
 | **GL-\*** | high/critical | 219 further credential providers, vendored from [gitleaks](https://github.com/gitleaks/gitleaks) (MIT), gated on Shannon entropy |
 
-**Community ruleset** — 436 additional rules vendored from
+**Logging, error-handling & deserialization** — the detectable slices of A08/A09/A10
+
+| Rule | Severity | What it catches |
+| --- | --- | --- |
+| **CTS070** | high/medium | Secret, token or PII (or a whole request body) written to a log (A09) |
+| **CTS071** | high/medium | A security check that **fails open** — `catch { return true }` — or swallows its error (A10) |
+| **CTS072** | high | Insecure deserialization of untrusted data — `unserialize`, `pickle.loads`, unsafe `yaml.load` (A08) |
+
+**Community ruleset** — 435 additional rules vendored from
 [GuardVibe](https://github.com/goklab/guardvibe) (Apache-2.0)
 
 Reported under their upstream `VG###` ids. These cover ground the AST scanners
@@ -89,12 +97,50 @@ Dockerfiles, Terraform, GitHub Actions pinning, prompt injection and MCP tool
 runtimes, React Native, Go and shell.
 
 27 upstream rules are **superseded** where ClearToShip's own AST check is more
-precise, and 5 are **withheld** as measurably noisy — both lists carry a reason
-per rule in `src/scanners/community.ts`. Run `--no-community` to use only
-ClearToShip's rules. See [ATTRIBUTION.md](ATTRIBUTION.md).
+precise, 6 are **withheld** as measurably noisy, and 3 name-heuristic rules are
+**manifest-only** — they never run over a `package-lock.json`, where they matched
+ordinary transitive packages (`fast-glob`, `core-js`) and named nothing anyone
+could act on. Each list carries a reason per rule in
+`src/scanners/community.ts`. Run `--no-community` to use only ClearToShip's
+rules. See [ATTRIBUTION.md](ATTRIBUTION.md).
 
 Findings map to **OWASP Top 10:2025** and CWE.
 
+## OWASP Top 10:2025 coverage — honest version
+
+ClearToShip is not an even, "100% coverage" scanner and does not claim to be —
+it is strongest exactly where AI-generated code fails. Coverage by category:
+
+| Category | Coverage | What we detect |
+| --- | --- | --- |
+| **A01** Broken Access Control | 🟢 Strong | Missing Server Action / route auth, RLS holes, IDOR, definer bypasses |
+| **A03** Supply Chain Failures | 🟢 Strong | Hallucinated / slopsquat / typosquat packages, live CVEs (OSV), install hooks |
+| **A07** Authentication Failures | 🟢 Strong | `getSession` misuse, weak sessions, JWT (mostly vendored) |
+| **A02** Security Misconfiguration | 🟢 Strong | Docker, Terraform, headers, CORS — via the vendored pack |
+| **A05** Injection | 🟢 Strong | SQLi, XSS, command injection |
+| **A04** Cryptographic Failures | 🟡 Moderate | Hardcoded keys (234 credential patterns), weak hashing |
+| **A09** Logging & Alerting Failures | 🟡 Targeted | **Secrets / PII written to logs** (CTS070) — the statically knowable slice |
+| **A10** Mishandling Exceptions | 🟡 Targeted | **Fail-open / swallowed error on a security check** (CTS071) |
+| **A08** Data & Integrity Failures | 🟡 Targeted | Unverified webhooks (CTS042), **insecure deserialization** (CTS072) |
+| **A06** Insecure Design | 🔴 Not statically detectable | Missing threat modeling is an architecture concern — no static scanner covers it, and we don't pretend to |
+
+Two honest points a reviewer would raise, answered up front:
+
+- **A06 and A09 are hard for _any_ static tool.** A06 (Insecure Design) is about
+  missing threat modeling — you cannot grep for "the developer didn't consider an
+  abuse case." A09 (Logging failures) is largely a runtime/ops concern. Semgrep,
+  Snyk and CodeQL have the same limits. ClearToShip covers the *detectable slices*
+  (secrets in logs, fail-open error handling) and is honest that the rest needs a
+  human threat model and runtime observability, not a scanner.
+- **Coverage is uneven on purpose.** The thesis is "the gaps LLM-generated code
+  leaves," which cluster in A01/A03/A07/A04 — so that is where the rules cluster.
+
+Running with `--no-community` (first-party rules only) covers **8 of 10**
+categories directly (A01, A03, A04, A05, A07, A08, A09, A10); the community pack
+adds A02 and broadens A05/A07.
+
+
+
 ## Usage
 
 ```bash
@@ -123,7 +169,33 @@ room to be written out.
 
 ## Continuous integration
 
-### GitHub Action (recommended)
+### The CLI (works anywhere, today)
+
+One line in any workflow, on any CI. It needs nothing from GitHub beyond npm:
+
+```yaml
+      - run: npx cleartoship --fail-on=critical
+```
+
+To feed findings into GitHub's Security tab:
+
+```yaml
+      - run: npx cleartoship --sarif -o results.sarif --fail-on=none
+      - uses: github/codeql-action/upload-sarif@v3
+        with: { sarif_file: results.sarif }
+```
+
+A copyable workflow is in [`examples/security-cli.yml`](examples/security-cli.yml).
+
+### GitHub Action
+
+> **Not usable from other repositories yet.** The action lives in *this*
+> repository, which is currently private, so `uses: murtazaozdemir/cleartoship@…`
+> resolves for nobody but its owner — GitHub answers `Unable to resolve action`
+> — and it cannot be listed on the Marketplace. Nothing about it is broken; it
+> simply needs the repository to be public, and it works the day that happens.
+> Until then, use the CLI recipe above. The npm package itself is public and
+> unaffected.
 
 Posts a summary comment on every pull request, blocks the merge on critical
 findings, and optionally uploads to the Security tab. Copy
@@ -140,7 +212,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: murtazaozdemir/cleartoship@v0.7.0
+      - uses: murtazaozdemir/cleartoship@v0.9.0
         with:
           fail-on: critical
           comment: true
@@ -154,29 +226,22 @@ jobs:
 | `sarif` | `false` | Upload results to GitHub code scanning |
 | `offline` | `false` | Skip registry and OSV lookups |
 | `working-directory` | `.` | Directory to scan from |
+| `version` | *(matches the action ref)* | npm version of the scanner to run; `latest` to always track the newest, `local` to build from the checkout |
 
-Outputs `verdict` (`clear`/`conditional`/`hold`), `critical`, `high` and `total`
-for use in later steps. The comment is *sticky* — re-runs edit the same comment
-instead of piling up. Until the npm package is published, the action builds
-itself from its own checkout, so `uses: …@ref` works immediately.
-
-### Plain CLI
-
-```yaml
-      - run: npx cleartoship --fail-on=critical
-```
+Outputs `verdict` (`clear`/`conditional`/`hold`), the per-severity counts
+`critical`, `high`, `medium`, `low`, plus `total` and `blocking` (findings at or
+above `fail-on`) for use in later steps. The comment is *sticky* — re-runs edit
+the same comment instead of piling up.
 
-To feed findings into GitHub's Security tab without the Action:
-
-```yaml
-      - run: npx cleartoship --sarif -o results.sarif --fail-on=none
-      - uses: github/codeql-action/upload-sarif@v3
-        with: { sarif_file: results.sarif }
-```
+By default the action runs the scanner version its own ref declares, so
+`@v0.9.0` runs `cleartoship@0.9.0` and pinning the ref pins the behaviour. If
+that version is not on the registry, it builds from its own checkout instead, so
+`uses: …@ref` works against an unpublished commit.
 
-## How it works## How it works
+## How it works
 
-Four scanners, all static — nothing is uploaded and no database is contacted.
+Six scanners, all static: your source is read and parsed, never executed, never
+uploaded, and no database is connected to.
 
 1. **Server Actions & Route Handlers** — parses TS/TSX with Babel, finds every exported
    function reachable over HTTP (`'use server'` modules, inline directives, `app/**/route.ts`
@@ -211,6 +276,41 @@ Four scanners, all static — nothing is uploaded and no database is contacted.
   commented-out line are reported at `low`, never as blocking criticals.
 - **Precision over recall on the noisy rules.** Typosquat matching skips exact matches and
   names shorter than five characters, where one-edit neighbours are meaningless.
+- **Auth is followed into the helper it lives in.** Almost no real app repeats the
+  session check inside every action — it resolves in `lib/auth.ts`, or in a
+  framework helper such as Shopify's `handleSessionToken`, and each action calls
+  that. ClearToShip resolves first-party imports (relative paths and `@/`-style
+  aliases) and credits a call whose helper authenticates, directly or through
+  another helper. Third-party packages are never followed, so a call into
+  `node_modules` still proves nothing on its own.
+- **A machine endpoint authenticates differently.** Comparing an `Authorization`
+  header against a server-side secret is the auth check for a cron or
+  webhook route, and a verified provider signature *is* the caller's identity —
+  neither is reported as missing authorization.
+
+## Trust
+
+A security tool earns its place by being auditable, so the guarantees are stated
+plainly and each one is checkable in a few seconds. `SECURITY.md` has the full
+version, including how to report a vulnerability.
+
+- **Read-only on your code.** The only files ClearToShip writes are the report
+  you ask for with `--output` and its 24-hour registry cache under
+  `~/.cache/cleartoship`. Nothing under the scan root is ever modified.
+- **Your code is never executed.** No `child_process`, no `eval`, no dynamic
+  import of a scanned file. Everything is text, an AST and regexes — which is
+  also why it is safe to point at a repository you have not read yet.
+- **No source leaves the machine.** Online, three hosts are contacted and they
+  receive package **names and versions** only: `registry.npmjs.org` /
+  `api.npmjs.org`, `pypi.org`, `api.osv.dev`. No file contents, no paths, no
+  project name. `--offline` disables all three and makes a run a pure local
+  computation.
+- **No database connection.** The RLS checks read your migration files. There is
+  no database driver in the dependency tree.
+- **Five runtime dependencies.** Three Babel packages, `commander`,
+  `picocolors`. The GuardVibe and gitleaks rulesets are vendored into
+  `src/vendor/`, not installed, so they are visible in every diff and pinned by
+  construction.
 
 ## Programmatic use
 

package/SECURITY.md

@@ -0,0 +1,70 @@
+# Security
+
+ClearToShip is a security tool, so it asks for the same scrutiny it applies. This
+document states exactly what it does on your machine, what leaves it, and how to
+check both for yourself rather than take it on faith.
+
+## Reporting a vulnerability
+
+Report privately through the repository's **Security → Report a vulnerability**
+tab (GitHub private vulnerability reporting). Please include the version
+(`cleartoship --version`), the smallest input that reproduces the problem, and
+what you expected instead. Non-sensitive bugs — a false positive, a crash on a
+weird file — belong in a normal issue.
+
+Fixes ship in a patch release. The `latest` published version is the only
+supported one; older versions are not backported.
+
+## What it does to your project
+
+| Guarantee | Why it holds |
+| --- | --- |
+| **Never writes to the scanned project** | The only writes in the codebase are the report file you ask for with `--output <path>` and the registry cache. Verify: `grep -rn "writeFileSync\|mkdirSync\|rmSync\|unlink" src/ --exclude-dir=vendor` — five lines, of which two are imports and three are those call sites. Neither path is derived from the scan root. |
+| **Never executes your code** | The scanner has no `child_process`, `exec`, `spawn`, `eval`, `new Function`, or dynamic `import()` of scanned files. Your code is read as text, parsed by Babel into an AST, and matched against regexes. Verify: `grep -rn "child_process\|execSync\|spawn\|eval(\|new Function" src/ --exclude-dir=vendor` — one hit, and it is a *pattern string* in the rule that detects those calls in **your** install hooks. (Drop `--exclude-dir=vendor` and the extra hits are rule text in the vendored ruleset, matched against your code, never run.) |
+| **Never connects to your database** | The Row Level Security scanner replays your `.sql` migration files to model the resulting schema. There is no database driver in the dependency tree and no connection string is ever read. |
+| **Reads only what it scans** | Files are gathered by walking the scan root, skipping `node_modules`, build output and virtualenvs. Nothing outside the root is read except the cache directory. |
+
+## What leaves your machine
+
+Three hosts, and only when a scan runs online:
+
+| Host | Sent | Purpose |
+| --- | --- | --- |
+| `registry.npmjs.org`, `api.npmjs.org` | package **name** (in the URL), nothing else | does this package exist, when was it published, how many weekly downloads, is it deprecated |
+| `pypi.org` | package **name** | the same, for `requirements.txt` |
+| `api.osv.dev` | package **name** + resolved **version** | known-vulnerability lookup |
+
+No file contents, no paths, no repository name, no identifier of you or your
+project is ever transmitted. Responses are cached for 24 hours under
+`~/.cache/cleartoship` (override with `CLEARTOSHIP_CACHE`).
+
+**`--offline` stops even that.** Every network path is behind the same flag: the
+dependency scanner returns early, and the registry client refuses to fetch. An
+offline run is a pure local computation, and it is the right default in CI on a
+private codebase.
+
+## Dependency surface
+
+Five runtime dependencies, all first-party Babel or long-established
+single-purpose packages:
+
+- `@babel/parser`, `@babel/traverse`, `@babel/types` — the TS/TSX parser and AST walker
+- `commander` — argument parsing
+- `picocolors` — terminal colour, zero dependencies
+
+Two rulesets are **vendored** into `src/vendor/` rather than installed, so they
+are visible in the diff and cannot change under you between releases:
+[GuardVibe](https://github.com/goklab/guardvibe) (Apache-2.0) and
+[gitleaks](https://github.com/gitleaks/gitleaks) (MIT). See `ATTRIBUTION.md`.
+
+## What this tool is not
+
+- **Not a proof of security.** It finds specific, well-defined classes of
+  mistake. A clean run means those classes are absent, not that the app is safe.
+  The OWASP coverage matrix in `README.md` is deliberately honest about the
+  categories no static scanner can reach.
+- **Not a sandbox.** It reads whatever you point it at. Pointing it at a
+  repository you do not trust is as safe as opening that repository in an
+  editor — no more, and no less.
+- **Not a secret scanner of record.** Secrets already committed to git history
+  are out of scope; ClearToShip reads the working tree, not past commits.