vetguard 0.0.0 → 0.2.0

package/README.md

@@ -5,10 +5,10 @@ AI-assisted development created: hallucinated (slopsquatted) dependencies,
 typosquats, and freshly registered malicious packages. No account, no server,
 no telemetry.
 
-> Early development. `scan` and `check` work today with two detectors live
-> (`nonexistent-package`, `young-package`); more detectors, lockfile
-> resolution, and a GitHub Action are landing next. Roadmap:
-> [docs/PLAN.md](docs/PLAN.md).
+> `vetguard@0.2.0` is on npm, published with provenance. Six detectors,
+> full-tree `package-lock` scanning, diff mode, a config file and baseline for
+> brownfield adoption, and a GitHub Action with text/JSON/SARIF/markdown output.
+> Roadmap to v1.0: [docs/ROADMAP.md](docs/ROADMAP.md).
 
 ## Why
 
@@ -20,29 +20,44 @@ CVE-first tools cannot see it. vetguard targets that gap.
 
 ## Install
 
-Not yet published to npm. For now, run from source (see Development). Once
-released:
+Published on npm. Run it without installing:
 
 ```
-npx vetguard scan
+npx vetguard scan          # scan the current project
+npx vetguard check <pkg>   # vet a package before installing
 ```
 
+Or add it to a project with `npm install --save-dev vetguard`. Requires Node.js
+20 or newer.
+
 ## Usage
 
 ```
 vetguard scan [dir]     Scan a project's dependencies (defaults to cwd)
 vetguard check <pkg>    Vet a single package before installing
                         (e.g. vetguard check some-package, foo@1.2.3)
+vetguard diff --base <lockfile> [--head <lockfile>]
+                        Scan only the dependencies a change introduces
+                        (head defaults to ./package-lock.json)
+vetguard baseline [dir] Record current findings so later scans fail only on new
+                        ones (adopt on an existing project, ratchet down later)
 vetguard --help         Show help
 vetguard --version      Show version
 
   --offline             Do not contact the registry
   --json                Print the report as JSON (for CI and tooling)
   --sarif               Print SARIF 2.1.0 for GitHub code scanning
+  --markdown            Print compact markdown for a PR comment or summary
+  --quiet               Print only findings and the verdict
+  --no-color            Disable ANSI colors (also respects NO_COLOR)
   --fail-on <severity>  Exit non-zero only at or above this severity
                         (critical|high|medium|low|info); default: any finding
 ```
 
+Text output is colored by severity only when writing to a terminal; piped or
+redirected output stays plain, and `--no-color` or the `NO_COLOR` environment
+variable turns color off.
+
 `scan` reads the resolved dependency tree from `package-lock.json` (v2 or v3),
 so it covers transitive dependencies and exact installed versions. Without a
 supported lockfile it falls back to the manifest's declared dependencies and
@@ -53,6 +68,47 @@ Exit codes: `0` clean or could-not-verify, `1` findings, `2` usage or read
 error. `check` makes vetguard usable as a pre-install gate, including for
 coding agents that add dependencies.
 
+## Configuration
+
+An optional `vetguard.config.json` in the scanned project sets defaults and
+suppresses findings. Command-line flags override it.
+
+```json
+{
+  "failOn": "high",
+  "offline": false,
+  "ignore": [
+    {
+      "rule": "young-package",
+      "package": "our-internal-lib",
+      "reason": "first-party package published last week; reviewed"
+    }
+  ]
+}
+```
+
+Every `ignore` entry requires a `reason`, an ignore without one is a
+configuration error, not a silent skip. A suppressed finding is still shown in
+the report (marked suppressed, with its reason) but does not affect the verdict
+or exit code. The point is an audit trail: you can always see what was waved
+through and why.
+
+### Adopt on an existing project (baseline)
+
+A repository that has not been scanned before will usually have some
+pre-existing findings. Rather than fix them all before you can turn vetguard on,
+record a baseline and ratchet down over time:
+
+```
+vetguard baseline        # writes .vetguard-baseline.json (commit it)
+```
+
+Later scans report the baselined findings as suppressed and pass; only findings
+**not** in the baseline fail the build. Commit the file so the whole team shares
+the same starting line, then shrink it as you clean things up. A finding's
+identity in the baseline includes its exact version, so a dependency bump is
+re-evaluated rather than grandfathered forever.
+
 ## Use on pull requests
 
 vetguard runs in GitHub Actions with no server and no cost: the scan happens on
@@ -67,25 +123,57 @@ on:
   pull_request:
 permissions:
   contents: read
-  security-events: write
+  security-events: write # upload SARIF
+  pull-requests: write # only if comment: true
 jobs:
   vetguard:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: tallyguard/vetguard@v1
+      - uses: tallyguard/vetguard@v0.2.0
         with:
           fail-on: high # fail the check only on high/critical findings
+          comment: true # post/update a single sticky PR comment (optional)
       - if: always()
         uses: github/codeql-action/upload-sarif@v3
         with:
           sarif_file: vetguard.sarif
 ```
 
-> The reusable action above resolves once vetguard is published to npm. This
-> repository already scans its own pull requests from source via
+`comment: true` posts one sticky comment and updates it in place on later
+pushes, so it never stacks. It needs `pull-requests: write`; leave it off (the
+default) to rely on the SARIF annotations and job summary alone. On pull requests
+from forks the token is read-only, so the comment is skipped without failing.
+
+> Pin the action to an exact release (`@v0.2.0`) while vetguard is pre-1.0, since
+> 0.x minor versions may change behaviour; a moving `@v1` tag will follow the
+> 1.0 release. This repository also scans its own pull requests from source via
 > [.github/workflows/pr-scan.yml](.github/workflows/pr-scan.yml).
 
+### Scan only what a pull request changes
+
+`diff` mode evaluates just the dependencies a change introduces (new to the head
+lockfile, or a new version), which is the highest-signal moment and keeps the
+report focused. Fetch the base branch's lockfile and diff against the working
+tree:
+
+```yaml
+name: Dependency diff
+on:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  vetguard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # so the base branch's lockfile is available
+      - run: git show "origin/${{ github.base_ref }}:package-lock.json" > /tmp/base-lock.json
+      - run: npx vetguard@0.2.0 diff --base /tmp/base-lock.json --fail-on high
+```
+
 ## What it checks
 
 Every finding carries a rule id, severity, and concrete evidence, so a verdict
@@ -121,17 +209,42 @@ scanner can prove a package is free of backdoors, a novel or heavily obfuscated
 one can evade heuristics, so vetguard raises evidenced signals and reports "no
 findings", never "safe".
 
-## Principles
+## Is vetguard itself safe?
+
+A fair question to ask of any security tool, a scanner is exactly what a
+supply-chain attacker would want to disguise malware as. Every claim below is
+verifiable, not asserted:
 
+- **Provenance-signed releases.** Every version is published from CI with npm
+  provenance: cryptographic proof the published bytes were built from this
+  public repository's tagged source, not tampered with in between. Verify with
+  `npm audit signatures` after install, or the verified badge on the
+  [npm page](https://www.npmjs.com/package/vetguard).
+- **Zero runtime dependencies.** vetguard installs nothing but itself, so there
+  is no transitive package that could be compromised, and every line that runs
+  is code you can read. Verify: `npm view vetguard dependencies` (empty).
+- **No install scripts.** `npm install vetguard` executes no code, there are no
+  `preinstall` / `install` / `postinstall` hooks. Verify: read its
+  `package.json`.
 - **Never executes the code it scans.** It reads manifests, lockfiles, and
-  package metadata as data.
-- **Honest verdicts.** When something cannot be verified (offline, private
-  registry, unsupported lockfile), vetguard reports "could not verify", never
+  package metadata as data; it never `require`s, imports, or evals a scanned
+  package.
+- **No telemetry, no phone-home.** The only network calls are the registry
+  lookups a scan needs, and `--offline` disables even those. Verify: run any
+  command with `--offline` and watch it work with no network.
+- **Honest verdicts.** When something cannot be verified (offline, off-registry
+  source, unsupported lockfile), vetguard reports "could not verify", never
   "safe".
-- **Near-zero runtime dependencies.** A supply-chain scanner should not ship a
-  large dependency tree of its own.
-- **No telemetry.** The only network calls are the registry lookups a scan
-  needs, and `--offline` disables even those.
+- **Small, auditable, open source.** The published tarball is a handful of files
+  (the bundled CLI, type declarations, `LICENSE`, `README`, `package.json`),
+  built from the source in this repository under Apache-2.0.
+- **It scans itself.** On every test run and in CI, vetguard scans its own
+  dependencies offline: an introduced name that resembles a popular package (a
+  typosquat or slopsquat) is caught with no network and fails the build. The
+  pull-request workflow
+  ([.github/workflows/pr-scan.yml](.github/workflows/pr-scan.yml)) also runs a
+  full live scan for the signals that need the registry. Its own supply chain is
+  held to the same bar it applies to yours.
 
 ## Development