@cupel-sh/cli 0.10.0 → 0.12.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 +54 -16
- package/bundle/cli.js +154 -53
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -10,17 +10,20 @@ npx @cupel-sh/cli scan .
|
|
|
10
10
|
|
|
11
11
|
## Verdicts
|
|
12
12
|
|
|
13
|
-
cupel answers with one of
|
|
13
|
+
cupel answers with one of three verdicts: **reachable**, **potentially
|
|
14
|
+
reachable** and **not reachable**. Each is reported in its own tiers:
|
|
14
15
|
|
|
15
|
-
| Verdict
|
|
16
|
-
| ------------------------------------- |
|
|
17
|
-
| `
|
|
18
|
-
| `not-
|
|
19
|
-
|
|
|
20
|
-
| `
|
|
16
|
+
| Verdict | Tier | Meaning |
|
|
17
|
+
| --------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
18
|
+
| reachable | `reachable-low` / `-medium` / `-high` | a call path exists; confidence rises with the evidence |
|
|
19
|
+
| potentially reachable | `potentially-reachable-not-ruled-out` | a path could not be ruled out: a dynamic call, a dynamic load, or a dependency cupel cannot see into |
|
|
20
|
+
| potentially reachable | `potentially-reachable-not-analysed` | cupel did not analyse this finding, and says why |
|
|
21
|
+
| not reachable | `not-reachable` | no call path from your code reaches the vulnerable symbol |
|
|
22
|
+
| not reachable | `not-affected` | the advisory does not apply to this version |
|
|
21
23
|
|
|
22
|
-
|
|
23
|
-
better. Every
|
|
24
|
+
Potentially reachable is never folded into the other verdicts to make a number
|
|
25
|
+
look better. Every potentially reachable finding carries a named reason and an
|
|
26
|
+
owner.
|
|
24
27
|
|
|
25
28
|
**An empty result is not a clean bill of health.** It is the set of advisories
|
|
26
29
|
cupel could enumerate for the packages it could see.
|
|
@@ -29,18 +32,53 @@ cupel could enumerate for the packages it could see.
|
|
|
29
32
|
|
|
30
33
|
```
|
|
31
34
|
cupel scan <dir> [--shard <npm.sqlite>] [--sarif <file>]
|
|
32
|
-
[--fail-on-reachable] [--fail-on-
|
|
35
|
+
[--fail-on-reachable] [--fail-on-potentially-reachable]
|
|
36
|
+
[--exclude <pattern>]
|
|
33
37
|
```
|
|
34
38
|
|
|
35
|
-
| Flag
|
|
36
|
-
|
|
|
37
|
-
| `--shard`
|
|
38
|
-
| `--sarif`
|
|
39
|
-
| `--fail-on-reachable`
|
|
40
|
-
| `--fail-on-
|
|
39
|
+
| Flag | Effect |
|
|
40
|
+
| --------------------------------- | -------------------------------------------------------- |
|
|
41
|
+
| `--shard` | path to the npm symbol shard (or set `CUPEL_SHARD_NPM`) |
|
|
42
|
+
| `--sarif` | also write a SARIF 2.1.0 report |
|
|
43
|
+
| `--fail-on-reachable` | exit 2 when any reachable finding is present |
|
|
44
|
+
| `--fail-on-potentially-reachable` | exit 2 when any potentially reachable finding is present |
|
|
45
|
+
| `--exclude <pattern>` | leave matching files out of the file count (repeatable) |
|
|
46
|
+
|
|
47
|
+
`--fail-on-unknown`, the old name of `--fail-on-potentially-reachable`, still
|
|
48
|
+
works and prints a warning. It will be removed in the next major version.
|
|
41
49
|
|
|
42
50
|
Requires Node 22 or newer.
|
|
43
51
|
|
|
52
|
+
## Coverage
|
|
53
|
+
|
|
54
|
+
Every scan counts the source files in the repository by language and says how
|
|
55
|
+
many it scanned, how many an entrypoint reaches, and what happened to each of
|
|
56
|
+
the rest:
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
📂 Source files: 142 · 97.6% scanned · 64 reached from an entrypoint
|
|
60
|
+
JavaScript and TypeScript: 128 files · 100% scanned · 64 reached · 12 excluded
|
|
61
|
+
Python: 14 files · 78.5% scanned · 0 reached · 3 failed
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
A file that could not be scanned is listed with its reason: not UTF-8, over the
|
|
65
|
+
size cap, a syntax error, a symlink loop, and so on. The SARIF report carries
|
|
66
|
+
every one of them.
|
|
67
|
+
|
|
68
|
+
The count follows `.gitignore`, `.git/info/exclude` and git's global excludes
|
|
69
|
+
file, with or without git installed. A file git tracks is counted even when an
|
|
70
|
+
ignore pattern matches it. Dependency and build directories (`node_modules`,
|
|
71
|
+
`dist`, `.venv`, …) are left out. To leave out more, list patterns in a
|
|
72
|
+
`.cupelignore` file (gitignore syntax) or pass `--exclude`. Other tools' ignore
|
|
73
|
+
files, such as `.eslintignore` or `.dockerignore`, are not read.
|
|
74
|
+
|
|
75
|
+
`.vue`, `.svelte` and `.astro` files are read: their scripts, an Astro page's
|
|
76
|
+
frontmatter and client scripts, and their templates. A call a template makes is
|
|
77
|
+
found like any other. A component cupel cannot read in full (a component with no
|
|
78
|
+
import, a custom directive, a template in another language) is named in the
|
|
79
|
+
report, and nothing is ruled out through it.
|
|
80
|
+
Go and Rust files are counted as not scanned until cupel reads them.
|
|
81
|
+
|
|
44
82
|
## Signing in
|
|
45
83
|
|
|
46
84
|
A scan needs an advisory database. **On GitHub Actions there is nothing to set
|