@scanverra/cli 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.
Files changed (3) hide show
  1. package/README.md +111 -27
  2. package/dist/cli.js +74 -73
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # @scanverra/cli
2
2
 
3
- Scan a codebase for hardcoded secrets, SAST vulnerabilities, dependency CVEs, IaC misconfigurations and code quality issues. Results are sent to your [Scanverra](https://scanverra.com) dashboard.
3
+ Scan a codebase for hardcoded secrets, SAST vulnerabilities, dependency CVEs, IaC misconfigurations and code quality issues, then see the results in your [Scanverra](https://scanverra.com) dashboard.
4
4
 
5
- **Your source code never leaves your machine.** The scan runs locally; only the findings are uploaded.
6
-
7
- The package contains no scanner rules. On first use it downloads them from Scanverra, verifies their Ed25519 signature, caches them, and refuses to run anything that is not signed by Scanverra. A **Pro, Team or Enterprise plan** and an API key are required.
5
+ - **Your source code stays on your machine.** The scan runs locally. See [What is uploaded](#what-is-uploaded).
6
+ - **Requires** Node.js 18 or newer, a Scanverra API key, and a **Pro, Team or Enterprise** plan.
7
+ - The package contains no scanner rules. It downloads them from Scanverra, verifies their Ed25519 signature, caches them, and refuses to run anything that is not signed by Scanverra.
8
8
 
9
9
  ## Quick start
10
10
 
@@ -13,38 +13,100 @@ npx @scanverra/cli login # paste an API key from Dashboard > API keys
13
13
  npx @scanverra/cli scan .
14
14
  ```
15
15
 
16
- Or install globally: `npm i -g @scanverra/cli`, then use `scanverra scan .`.
16
+ Or install globally: `npm i -g @scanverra/cli`, then run `scanverra scan .`.
17
17
 
18
18
  ## Commands
19
19
 
20
20
  | Command | What it does |
21
21
  | --- | --- |
22
- | `scanverra login` | Verify and save your API key (`~/.config/scanverra/config.json`, mode 0600) |
22
+ | `scanverra login` | Verify and save your API key (stored with mode 0600, see [Files and folders](#files-and-folders)) |
23
23
  | `scanverra logout` | Remove the saved key |
24
- | `scanverra whoami` | Show the account and plan behind the key |
25
- | `scanverra scan [path]` | Scan a folder (default `.`), print results, upload to Scanverra |
24
+ | `scanverra whoami` | Show the account and plan behind the key, and where the key came from |
25
+ | `scanverra scan [path]` | Scan a folder (default `.`), print the results, upload them to Scanverra |
26
26
 
27
27
  ## Scan options
28
28
 
29
29
  | Option | Description |
30
30
  | --- | --- |
31
- | `--json` / `--sarif` | Machine-readable output (SARIF 2.1.0 works with GitHub code scanning and Sonar import) |
31
+ | `--json` / `--sarif` | Machine-readable output on stdout (SARIF 2.1.0 works with GitHub code scanning and Sonar import) |
32
32
  | `--output <file>` | Write the report to a file instead of stdout |
33
- | `--fail-on <sev>` | Exit 1 at or above `critical`, `high` (default), `medium`, `low`; `none` never fails |
33
+ | `--fail-on <sev>` | Exit 1 if a finding at or above `critical`, `high` (default), `medium` or `low` exists; `none` never fails |
34
34
  | `--fail-on-gate` | Also exit 1 when the Scanverra quality gate fails |
35
35
  | `--severity <sev>` | Only print findings at or above this severity |
36
36
  | `--category <list>` | Only include `security`, `dependency`, `iac`, `quality` (comma separated); score and gate are recomputed |
37
- | `--exclude <glob>` | Skip matching paths (repeatable). `.scanverraignore` (one glob per line) is also read |
38
- | `--no-upload` | Scan only, do not send results |
39
- | `--offline` | Use the cached rules with no network calls (cache is valid for 14 days) |
40
- | `--project <owner/repo>`, `--branch`, `--commit` | Override auto-detected values |
41
- | `--api-key`, `--api-url` | Override credentials / server |
37
+ | `--all` | List every finding. By default critical and high are listed and the rest are grouped by rule |
38
+ | `--exclude <glob>` | Skip matching paths (repeatable) |
39
+ | `--no-upload` | Scan only, do not send results to Scanverra |
40
+ | `--include-code` | Also upload the matched source line of each finding (off by default) |
41
+ | `--offline` | Use the cached rules with no network calls. Implies `--no-upload` |
42
+ | `--project <owner/repo>`, `--branch <name>`, `--commit <sha>` | Override the auto-detected values |
43
+ | `--api-key <key>`, `--api-url <url>` | Override credentials / server |
44
+ | `--no-color` | Disable colours (also off when piped or when `NO_COLOR` is set) |
45
+ | `-v`, `--version`, `-h`, `--help` | Version and help |
46
+
47
+ Both `--flag value` and `--flag=value` work. Examples:
48
+
49
+ ```bash
50
+ scanverra scan . --category security,dependency # ignore quality opinions
51
+ scanverra scan . --fail-on critical # gate CI on criticals only
52
+ scanverra scan ./services/api --exclude "**/*.test.ts" # one folder, skip tests
53
+ scanverra scan . --sarif --output scanverra.sarif # for code scanning
54
+ ```
55
+
56
+ ## What is uploaded
57
+
58
+ **Uploaded:** file paths, line numbers, rule IDs, titles, descriptions, fix suggestions, severities, dependency names and versions, counts, and the project name, branch, commit and PR number.
59
+
60
+ **Not uploaded:** file contents, and the matched source line of each finding (pass `--include-code` if you want those shown in the dashboard). Secret findings never carry the secret itself, and because matched lines are not uploaded by default, a credential on a matched line stays local too.
61
+
62
+ Scanverra then adds an AI-written summary and fixes computed from those findings.
63
+
64
+ ## How files are chosen
65
+
66
+ - Inside a git repository the CLI uses `git ls-files` (tracked plus untracked, minus ignored), so **`.gitignore` is respected**. Outside git it walks the folder and skips `node_modules`, `.next`, `.git`, `dist`, `build`, `coverage`, `vendor`, `.venv` and `__pycache__`, and does not follow symlinks.
67
+ - Scanned file types: `ts tsx js jsx mjs cjs py go rb java php cs css scss json yml yaml lock txt toml tf`, plus `Dockerfile`, `.env*`, `go.mod` and `requirements.txt`. Files over 1 MB are skipped.
68
+ - `.scanverraignore` in the folder you scan (one glob per line, `#` for comments) and `--exclude` add more exclusions.
69
+ - In a monorepo the manifest closest to the scanned root is used for the dependency check.
70
+ - Suppress a single finding by putting a `scanverra-ignore` or `nosec` comment on the line above it.
71
+
72
+ ## Project detection
73
+
74
+ The project name, branch, commit and PR number come from the environment, in this order: `--project`/`--branch`/`--commit`, GitHub Actions or GitLab CI variables, then git (`origin` remote and current HEAD). Without a git remote the project is named `local/<folder name>`.
75
+
76
+ ## Score and quality gate
77
+
78
+ The score starts at 100 and loses points per finding by severity, with a cap per category (security, dependencies, IaC, quality). The quality gate **fails** if there is any critical finding or the score is below 60. Use `--category` to focus on what matters to you.
79
+
80
+ ## Exit codes
81
+
82
+ | Code | Meaning |
83
+ | --- | --- |
84
+ | `0` | Success, and no finding reached the `--fail-on` threshold |
85
+ | `1` | A finding reached the `--fail-on` threshold, or `--fail-on-gate` is set and the gate failed |
86
+ | `2` | Usage error, no rules available, or the server rejected your key or plan (401/402) |
87
+
88
+ A failed upload (network error, server error) prints a warning but does not change the exit code, so a Scanverra outage does not break your pipeline.
89
+
90
+ ## Environment variables
91
+
92
+ | Variable | Purpose |
93
+ | --- | --- |
94
+ | `SCANVERRA_API_KEY` | API key (used when `--api-key` is not given and before the saved login) |
95
+ | `SCANVERRA_URL` | Server URL, default `https://www.scanverra.com` |
96
+ | `SCANVERRA_CACHE_DIR` | Where the rules cache is kept |
97
+ | `SCANVERRA_CONFIG_DIR` | Where the saved login is kept |
98
+ | `NO_COLOR` | Disable colours |
42
99
 
43
100
  Key lookup order: `--api-key`, then `SCANVERRA_API_KEY`, then the saved login.
44
- Project, branch, commit and PR number are detected from git and from GitHub Actions / GitLab CI variables.
45
- Files are taken from `git ls-files`, so `.gitignore` is respected. Suppress a finding on the next line with a `scanverra-ignore` or `nosec` comment.
46
101
 
47
- Exit codes: `0` ok, `1` threshold failed, `2` usage or runtime error.
102
+ ## Files and folders
103
+
104
+ | What | macOS / Linux | Windows |
105
+ | --- | --- | --- |
106
+ | Saved login | `~/.config/scanverra/config.json` | `%APPDATA%\scanverra\config.json` |
107
+ | Rules cache | `~/.cache/scanverra/engine.json` | `%LOCALAPPDATA%\scanverra\cache\engine.json` |
108
+
109
+ `XDG_CONFIG_HOME` and `XDG_CACHE_HOME` are honoured. To reset everything: `scanverra logout` and delete the cache folder.
48
110
 
49
111
  ## GitHub Actions
50
112
 
@@ -57,15 +119,23 @@ Exit codes: `0` ok, `1` threshold failed, `2` usage or runtime error.
57
119
  SCANVERRA_API_KEY: ${{ secrets.SCANVERRA_API_KEY }}
58
120
  ```
59
121
 
60
- To surface findings in the GitHub Security tab, add `--sarif --output scanverra.sarif` and upload it with `github/codeql-action/upload-sarif`.
122
+ To show findings in the GitHub Security tab:
123
+
124
+ ```yaml
125
+ - run: npx @scanverra/cli scan . --sarif --output scanverra.sarif --fail-on none
126
+ env:
127
+ SCANVERRA_API_KEY: ${{ secrets.SCANVERRA_API_KEY }}
128
+ - uses: github/codeql-action/upload-sarif@v3
129
+ with: { sarif_file: scanverra.sarif }
130
+ ```
61
131
 
62
132
  ## Rules and updates
63
133
 
64
- Rules are refreshed automatically: cached for 24 hours, then revalidated (a 304 means nothing to download). If the server is unreachable the cached rules are used for up to 14 days. A revoked key or a lapsed plan stops the CLI immediately after the next check.
134
+ Rules are cached for 24 hours, then revalidated (an unchanged bundle is not downloaded again). If the server is unreachable the cached rules are used for up to 14 days. A revoked key or a lapsed plan stops the CLI at the next check.
65
135
 
66
136
  ## CI: cache the rules
67
137
 
68
- CI runners start empty, so without a cache every run downloads the rules again (and each API key is limited to a number of full downloads per day). Cache the folder:
138
+ CI runners start empty, so without a cache every run downloads the rules again, and each API key is limited to a number of full downloads per day. Cache the folder:
69
139
 
70
140
  ```yaml
71
141
  # GitHub Actions
@@ -85,13 +155,27 @@ variables:
85
155
  SCANVERRA_CACHE_DIR: $CI_PROJECT_DIR/.cache/scanverra
86
156
  ```
87
157
 
88
- ## Development (inside the Scanverra monorepo)
158
+ ## Troubleshooting
159
+
160
+ | Message | What to do |
161
+ | --- | --- |
162
+ | `Not logged in ... an API key is required` | Run `scanverra login`, or set `SCANVERRA_API_KEY` |
163
+ | `API key was rejected` (401) | The key is wrong or was revoked. Create a new one under Dashboard > API keys |
164
+ | `The Scanverra CLI requires a Pro, Team or Enterprise plan` (402) | Upgrade your plan. The message includes the pricing link |
165
+ | `Daily limit for downloading the scanner rules reached` (429) | Cache the rules folder in CI (see above). Cached rules keep working meanwhile |
166
+ | `Rules bundle is temporarily unavailable` (503) | A Scanverra-side problem. Retry shortly; cached rules are used automatically if you have them |
167
+ | `Rules bundle signature is invalid. Refusing to run it.` | Something between you and Scanverra altered the download (proxy or TLS inspection), or the cache is corrupt. Delete the cache folder and retry, and contact support if it persists |
168
+ | `No cached rules found` with `--offline` | Run one scan online first |
169
+ | `No scannable files found` | Check the path and your `.gitignore` / `.scanverraignore` |
170
+ | `Unexpected response from ...` | `SCANVERRA_URL` / `--api-url` points somewhere that is not Scanverra |
171
+
172
+ ## Uninstall
89
173
 
90
174
  ```bash
91
- npm run cli:engine # rebuild the signed rules bundle after changing lib/repo-scanner
92
- npm run cli:engine:check # CI: fails if the committed bundle is stale
93
- npm run cli:build # bundle the CLI to packages/cli/dist
94
- cd packages/cli && npm publish
175
+ npm rm -g @scanverra/cli
176
+ scanverra logout # run this first if you want the saved key removed
95
177
  ```
96
178
 
97
- The server needs `CLI_BUNDLE_SIGNING_KEY` (base64 PEM Ed25519 private key). Its public half is `src/publickey.ts`.
179
+ ## Support
180
+
181
+ Questions or problems: [scanverra.com](https://scanverra.com).