@scanverra/cli 0.2.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.md +97 -0
- package/dist/cli.js +498 -0
- package/package.json +38 -0
package/README.md
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# @scanverra/cli
|
|
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.
|
|
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.
|
|
8
|
+
|
|
9
|
+
## Quick start
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npx @scanverra/cli login # paste an API key from Dashboard > API keys
|
|
13
|
+
npx @scanverra/cli scan .
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Or install globally: `npm i -g @scanverra/cli`, then use `scanverra scan .`.
|
|
17
|
+
|
|
18
|
+
## Commands
|
|
19
|
+
|
|
20
|
+
| Command | What it does |
|
|
21
|
+
| --- | --- |
|
|
22
|
+
| `scanverra login` | Verify and save your API key (`~/.config/scanverra/config.json`, mode 0600) |
|
|
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 |
|
|
26
|
+
|
|
27
|
+
## Scan options
|
|
28
|
+
|
|
29
|
+
| Option | Description |
|
|
30
|
+
| --- | --- |
|
|
31
|
+
| `--json` / `--sarif` | Machine-readable output (SARIF 2.1.0 works with GitHub code scanning and Sonar import) |
|
|
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 |
|
|
34
|
+
| `--fail-on-gate` | Also exit 1 when the Scanverra quality gate fails |
|
|
35
|
+
| `--severity <sev>` | Only print findings at or above this severity |
|
|
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 |
|
|
42
|
+
|
|
43
|
+
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
|
+
|
|
47
|
+
Exit codes: `0` ok, `1` threshold failed, `2` usage or runtime error.
|
|
48
|
+
|
|
49
|
+
## GitHub Actions
|
|
50
|
+
|
|
51
|
+
```yaml
|
|
52
|
+
- uses: actions/checkout@v4
|
|
53
|
+
- uses: actions/setup-node@v4
|
|
54
|
+
with: { node-version: 20 }
|
|
55
|
+
- run: npx @scanverra/cli scan . --fail-on high
|
|
56
|
+
env:
|
|
57
|
+
SCANVERRA_API_KEY: ${{ secrets.SCANVERRA_API_KEY }}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
To surface findings in the GitHub Security tab, add `--sarif --output scanverra.sarif` and upload it with `github/codeql-action/upload-sarif`.
|
|
61
|
+
|
|
62
|
+
## Rules and updates
|
|
63
|
+
|
|
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.
|
|
65
|
+
|
|
66
|
+
## CI: cache the rules
|
|
67
|
+
|
|
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:
|
|
69
|
+
|
|
70
|
+
```yaml
|
|
71
|
+
# GitHub Actions
|
|
72
|
+
- uses: actions/cache@v4
|
|
73
|
+
with:
|
|
74
|
+
path: ~/.cache/scanverra
|
|
75
|
+
key: scanverra-rules-${{ github.run_id }}
|
|
76
|
+
restore-keys: scanverra-rules-
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
```yaml
|
|
80
|
+
# GitLab CI
|
|
81
|
+
cache:
|
|
82
|
+
key: scanverra-rules
|
|
83
|
+
paths: [.cache/scanverra]
|
|
84
|
+
variables:
|
|
85
|
+
SCANVERRA_CACHE_DIR: $CI_PROJECT_DIR/.cache/scanverra
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Development (inside the Scanverra monorepo)
|
|
89
|
+
|
|
90
|
+
```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
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
The server needs `CLI_BUNDLE_SIGNING_KEY` (base64 PEM Ed25519 private key). Its public half is `src/publickey.ts`.
|