vexpath 0.1.0__py3-none-any.whl

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.
vexpath/main.py ADDED
@@ -0,0 +1,120 @@
1
+ """CLI entry point.
2
+
3
+ Command groups are registered here and implemented under ``vexpath.commands``.
4
+ The exit-code contract in ``vexpath.exit_codes`` is the part CI depends on, and it
5
+ does not change between milestones.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from typing import Annotated
11
+
12
+ import typer
13
+
14
+ from vexpath import __version__ as cli_version
15
+ from vexpath.commands import advisory as advisory_commands
16
+ from vexpath.commands import attest as attest_commands
17
+ from vexpath.commands import auth as auth_commands
18
+ from vexpath.commands import policy as policy_commands
19
+ from vexpath.commands import reach as reach_command
20
+ from vexpath.commands import report as report_command
21
+ from vexpath.commands import sbom as sbom_commands
22
+ from vexpath.commands import scan as scan_command
23
+ from vexpath.commands import upload as upload_command
24
+ from vexpath.commands import vex as vex_commands
25
+ from vexpath.output import OutputFormat, emit, emit_json
26
+ from vexpath_core import RESULTS_SCHEMA
27
+ from vexpath_core import __version__ as core_version
28
+ from vexpath_core.enums import NATIVE_LOCKFILE_ECOSYSTEMS, REACHABILITY_ECOSYSTEMS
29
+ from vexpath_core.reach.cache import default_cache_directory
30
+ from vexpath_core.sbom.lockfiles import LOCKFILE_PRIORITY
31
+
32
+ app = typer.Typer(
33
+ name="vexpath",
34
+ help=(
35
+ "Find out which of your dependencies' known vulnerabilities are actually "
36
+ "reachable, and prove it with signed VEX."
37
+ ),
38
+ no_args_is_help=True,
39
+ add_completion=True,
40
+ rich_markup_mode="rich",
41
+ )
42
+
43
+ app.add_typer(sbom_commands.app, name="sbom")
44
+ app.add_typer(advisory_commands.app, name="advisory")
45
+ app.add_typer(vex_commands.app, name="vex")
46
+ app.add_typer(policy_commands.app, name="policy")
47
+ app.add_typer(attest_commands.app, name="attest")
48
+ # Login, whoami and logout sit at the top level rather than under a
49
+ # group: they are typed once by a person, not scripted.
50
+ app.command("login")(auth_commands.login)
51
+ app.command("whoami")(auth_commands.whoami)
52
+ app.command("logout")(auth_commands.logout)
53
+ app.command("scan")(scan_command.command)
54
+ app.command("reach")(reach_command.command)
55
+ app.command("report")(report_command.command)
56
+ app.command("upload")(upload_command.command)
57
+
58
+
59
+ @app.callback()
60
+ def cli() -> None:
61
+ """Root callback.
62
+
63
+ Present so that Typer keeps a command group rather than collapsing a
64
+ single-command application into a bare entry point.
65
+ """
66
+
67
+
68
+ @app.command()
69
+ def version(
70
+ output: Annotated[
71
+ OutputFormat,
72
+ typer.Option("--format", "-f", help="Output format."),
73
+ ] = OutputFormat.TABLE,
74
+ ) -> None:
75
+ """Print version and capability information.
76
+
77
+ Capabilities are printed next to the version because a verdict means
78
+ different things depending on what this build can analyse. Someone reading
79
+ a report needs to know that without consulting documentation.
80
+ """
81
+ payload = {
82
+ "cli": cli_version,
83
+ "core": core_version,
84
+ "results_schema": RESULTS_SCHEMA,
85
+ "reachability_ecosystems": sorted(REACHABILITY_ECOSYSTEMS),
86
+ "matching_ecosystems": "every ecosystem OSV publishes",
87
+ "native_lockfile_ecosystems": sorted(NATIVE_LOCKFILE_ECOSYSTEMS),
88
+ "lockfiles": list(LOCKFILE_PRIORITY),
89
+ "reachability_available": True,
90
+ # Where call graphs are cached. Reported here so a CI job can ask the
91
+ # tool rather than guess the platform convention: the difference
92
+ # between a warm scan and a cold one is minutes, and a cache keyed on
93
+ # the wrong directory silently never hits.
94
+ "cache_dir": str(default_cache_directory().parent),
95
+ }
96
+ if output is OutputFormat.JSON:
97
+ emit_json(payload)
98
+ return
99
+
100
+ lines = [
101
+ f"{'vexpath':<16}{payload['cli']}",
102
+ f"{'core':<16}{payload['core']}",
103
+ f"{'results':<16}{payload['results_schema']}",
104
+ "",
105
+ f"matching {payload['matching_ecosystems']}",
106
+ f"lockfiles {', '.join(LOCKFILE_PRIORITY)}",
107
+ f"reachability {', '.join(sorted(REACHABILITY_ECOSYSTEMS))}",
108
+ "",
109
+ f"graph cache {payload['cache_dir']}",
110
+ ]
111
+ emit("\n".join(lines) + "\n")
112
+
113
+
114
+ def run() -> None:
115
+ """Console-script entry point."""
116
+ app()
117
+
118
+
119
+ if __name__ == "__main__":
120
+ run()
vexpath/output.py ADDED
@@ -0,0 +1,96 @@
1
+ """Output handling shared by every command.
2
+
3
+ Two rules hold throughout:
4
+
5
+ Machine output goes to standard output and nothing else does. ``vexpath scan
6
+ --format json > results.json`` has to produce a file that parses, so progress,
7
+ warnings and errors all go to standard error.
8
+
9
+ Failures name the fix. A tool that runs in CI is read by someone who did not
10
+ choose to run it and does not know its internals, so every error says what to
11
+ do next.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import json
17
+ from enum import StrEnum
18
+ from typing import Any, NoReturn
19
+
20
+ import typer
21
+ from rich.console import Console
22
+
23
+ from vexpath.exit_codes import ExitCode
24
+
25
+ #: Machine-readable output only.
26
+ stdout = Console(soft_wrap=True)
27
+ #: Everything a human reads while the command runs.
28
+ stderr = Console(stderr=True, soft_wrap=True)
29
+
30
+
31
+ class OutputFormat(StrEnum):
32
+ """How to render results."""
33
+
34
+ TABLE = "table"
35
+ JSON = "json"
36
+ MARKDOWN = "markdown"
37
+ SARIF = "sarif"
38
+
39
+ @property
40
+ def is_machine_readable(self) -> bool:
41
+ return self in {OutputFormat.JSON, OutputFormat.SARIF}
42
+
43
+
44
+ def emit(text: str) -> None:
45
+ """Write rendered output to standard output, unstyled.
46
+
47
+ Markup interpretation is off: advisory summaries and component names come
48
+ from outside this process, and a square bracket in one of them must not be
49
+ read as a style tag.
50
+ """
51
+ stdout.print(text, markup=False, highlight=False, end="")
52
+
53
+
54
+ def emit_json(payload: Any) -> None:
55
+ """Write a JSON document to standard output."""
56
+ stdout.print(json.dumps(payload, indent=2, default=str), markup=False, highlight=False)
57
+
58
+
59
+ def note(message: str) -> None:
60
+ """Report progress to standard error."""
61
+ stderr.print(f"[dim]{message}[/dim]")
62
+
63
+
64
+ def warn(message: str) -> None:
65
+ """Report something the user should know but that is not fatal."""
66
+ stderr.print(f"[yellow]warning[/yellow] {message}")
67
+
68
+
69
+ def fail(message: str, *, code: ExitCode = ExitCode.ANALYSIS_ERROR) -> NoReturn:
70
+ """Report a failure and exit.
71
+
72
+ The default is an analysis error rather than a policy failure, because the
73
+ two must stay distinguishable: a build that breaks because the scanner
74
+ could not run has to look different from one that breaks because the code
75
+ is vulnerable.
76
+ """
77
+ stderr.print(f"[red]error[/red] {message}")
78
+ raise typer.Exit(code=int(code))
79
+
80
+
81
+ def fail_config(message: str) -> NoReturn:
82
+ """Report a configuration problem and exit."""
83
+ fail(message, code=ExitCode.CONFIG_ERROR)
84
+
85
+
86
+ __all__ = [
87
+ "OutputFormat",
88
+ "emit",
89
+ "emit_json",
90
+ "fail",
91
+ "fail_config",
92
+ "note",
93
+ "stderr",
94
+ "stdout",
95
+ "warn",
96
+ ]
vexpath/py.typed ADDED
File without changes
vexpath/sources.py ADDED
@@ -0,0 +1,88 @@
1
+ """Where the command-line tool gets its advisories.
2
+
3
+ Every command that reads advisories faces the same choice, with the same
4
+ consequence: a local snapshot makes the result reproducible, a live query does
5
+ not. Keeping the choice and the warning in one place means no command can
6
+ quietly omit the warning, and the environment variable is spelled once.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import os
12
+ from pathlib import Path
13
+
14
+ from vexpath.output import fail, note, warn
15
+ from vexpath_core.advisory import OsvApiSource, SnapshotSource
16
+ from vexpath_core.protocols import AdvisorySource
17
+ from vexpath_core.snapshot import SnapshotIntegrityError
18
+
19
+ #: Environment variable naming a local advisory snapshot. Set it and commands
20
+ #: become reproducible and offline by default.
21
+ SNAPSHOT_ENV = "VEXPATH_ADVISORY_SNAPSHOT_DIR"
22
+ #: Override for the OSV endpoint, so tests can point at something local.
23
+ OSV_BASE_ENV = "VEXPATH_OSV_API_BASE"
24
+
25
+
26
+ def snapshot_directory(explicit: Path | None = None) -> Path | None:
27
+ """Resolve the snapshot to read, from the flag or the environment."""
28
+ if explicit is not None:
29
+ return explicit
30
+ raw = os.environ.get(SNAPSHOT_ENV, "").strip()
31
+ if not raw:
32
+ return None
33
+ candidate = Path(raw)
34
+ if not candidate.is_dir():
35
+ warn(f"${SNAPSHOT_ENV} points at {candidate}, which is not a directory; ignoring it.")
36
+ return None
37
+ return candidate
38
+
39
+
40
+ def advisory_source(snapshot: Path | None, *, result_noun: str = "scan") -> AdvisorySource:
41
+ """Open an advisory source, preferring a reproducible snapshot.
42
+
43
+ Args:
44
+ snapshot: Snapshot directory from a command-line flag, if given.
45
+ result_noun: What the caller is producing, for the warning text. A
46
+ warning that names the thing about to become unreproducible is one
47
+ people act on.
48
+
49
+ Exits the process with a configuration error if a snapshot was named but
50
+ cannot be trusted. A corrupted corpus changes verdicts, so continuing with
51
+ it would be worse than stopping.
52
+ """
53
+ directory = snapshot_directory(snapshot)
54
+ if directory is not None:
55
+ try:
56
+ source = SnapshotSource(directory)
57
+ except FileNotFoundError as exc:
58
+ fail(str(exc))
59
+ except SnapshotIntegrityError as exc:
60
+ fail(f"advisory snapshot is not trustworthy: {exc}")
61
+ note(f"using advisory snapshot {source.snapshot_id} from {directory}")
62
+ return source
63
+
64
+ warn(
65
+ f"No advisory snapshot was given, so advisories will be read live from "
66
+ f"OSV and this {result_noun} will not be reproducible. Run "
67
+ f"'vexpath advisory sync' and set ${SNAPSHOT_ENV} to fix that."
68
+ )
69
+ return OsvApiSource(base_url=os.environ.get(OSV_BASE_ENV, "https://api.osv.dev"))
70
+
71
+
72
+ def close_source(source: object) -> None:
73
+ """Release a source's resources, if it holds any.
74
+
75
+ A snapshot source holds none; a live one holds an HTTP connection pool.
76
+ """
77
+ close = getattr(source, "close", None)
78
+ if callable(close):
79
+ close()
80
+
81
+
82
+ __all__ = [
83
+ "OSV_BASE_ENV",
84
+ "SNAPSHOT_ENV",
85
+ "advisory_source",
86
+ "close_source",
87
+ "snapshot_directory",
88
+ ]
@@ -0,0 +1,160 @@
1
+ Metadata-Version: 2.5
2
+ Name: vexpath
3
+ Version: 0.1.0
4
+ Summary: Command-line tool: generate SBOMs, match advisories, analyse reachability and emit signed VEX.
5
+ Project-URL: Homepage, https://github.com/Unknown122-coder/vexpath
6
+ Project-URL: Documentation, https://github.com/Unknown122-coder/vexpath/tree/main/docs
7
+ Project-URL: Repository, https://github.com/Unknown122-coder/vexpath
8
+ Project-URL: Issues, https://github.com/Unknown122-coder/vexpath/issues
9
+ Project-URL: Changelog, https://github.com/Unknown122-coder/vexpath/releases
10
+ Author: Akmal Khan
11
+ License-Expression: Apache-2.0
12
+ License-File: LICENSE
13
+ Keywords: cyclonedx,openvex,reachability,sbom,sca,security,spdx,supply-chain,vex,vulnerability
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Environment :: Console
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Intended Audience :: System Administrators
18
+ Classifier: License :: OSI Approved :: Apache Software License
19
+ Classifier: Operating System :: OS Independent
20
+ Classifier: Programming Language :: Python :: 3
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: Security
24
+ Classifier: Topic :: Software Development :: Quality Assurance
25
+ Classifier: Topic :: System :: Software Distribution
26
+ Classifier: Typing :: Typed
27
+ Requires-Python: >=3.12
28
+ Requires-Dist: rich>=13.9
29
+ Requires-Dist: typer>=0.15
30
+ Requires-Dist: vexpath-core==0.1.0
31
+ Description-Content-Type: text/markdown
32
+
33
+ # vexpath
34
+
35
+ **Most of your vulnerability findings cannot run.** vexpath works out which
36
+ ones can, and shows you the call path that proves it.
37
+
38
+ ```bash
39
+ uv tool install vexpath # or: pipx install vexpath
40
+ vexpath scan .
41
+ ```
42
+
43
+ A scanner tells you that `jinja2` has a critical advisory. vexpath reads the
44
+ commit that fixed it, extracts the functions it changed, builds a call graph
45
+ from your code through your dependencies, and tells you whether anything you
46
+ run can reach them. On five real repositories it cleared 68 of 146 findings as
47
+ unreachable, with the evidence for each.
48
+
49
+ ```
50
+ SEVERITY VERDICT ADVISORY COMPONENT REACHABILITY
51
+ --------------------------------------------------------------------------------
52
+ HIGH affected CVE-2026-1234 jinja2 3.1.0 reachable_confirmed
53
+ MEDIUM not_affected CVE-2026-5678 urllib3 2.2.1 unreachable
54
+
55
+ 38 findings | 10 reachable | 28 not affected | 0 under investigation
56
+ ```
57
+
58
+ ## What makes a finding clearable
59
+
60
+ A finding is cleared only when the vulnerable code **provably** cannot run.
61
+ That requires the dependency's own source, so:
62
+
63
+ ```bash
64
+ pip install -e . # or uv sync, or poetry install
65
+ vexpath scan .
66
+ ```
67
+
68
+ With nothing installed, vexpath still matches advisories but clears nothing —
69
+ an absence of paths through code it never read proves nothing, and it says so
70
+ rather than implying a clean bill of health. `--download-missing` fetches each
71
+ dependency's source from the package index instead (nothing is executed,
72
+ ever).
73
+
74
+ ## The gate
75
+
76
+ ```bash
77
+ vexpath scan . --policy balanced
78
+ ```
79
+
80
+ Exits 1 when a critical or high finding's vulnerable code is provably
81
+ reachable, or when anything in your tree is in CISA's Known Exploited
82
+ Vulnerabilities catalogue. Five presets, or write your own in CEL:
83
+
84
+ ```bash
85
+ vexpath policy list
86
+ vexpath scan . --policy 'findings.exists(f, f.kev && f.verdict != "not_affected")'
87
+ ```
88
+
89
+ ## Exit codes
90
+
91
+ The contract with CI, and fixed:
92
+
93
+ | Code | Meaning |
94
+ |---|---|
95
+ | 0 | Analysis completed and the policy passed |
96
+ | 1 | Analysis completed and the policy **failed** — your dependencies need attention |
97
+ | 2 | Analysis could not complete: a broken lockfile, an unreachable index |
98
+ | 3 | Configuration error: a policy that does not compile, a bad flag |
99
+
100
+ 1 and 2 are separate on purpose. A build failing because the code is
101
+ vulnerable must never look like a build failing because the tool broke.
102
+
103
+ ## What else it does
104
+
105
+ | Command | What for |
106
+ |---|---|
107
+ | `vexpath scan` | The whole pipeline: SBOM → match → reachability → VEX → gate |
108
+ | `vexpath reach --advisory CVE-…` | Why one verdict is what it is: symbols searched for, which entry points reach them, by what path, and the graph it rests on |
109
+ | `vexpath report results.json --format sarif` | Re-render a scan. Nothing is re-analysed, so the SARIF matches the table |
110
+ | `vexpath sbom generate` | CycloneDX 1.6 or SPDX 2.3 from seven lockfile formats |
111
+ | `vexpath vex export` | OpenVEX 0.2.0 or CycloneDX VEX, with the evidence attached |
112
+ | `vexpath attest sign` | A signed in-toto statement in a DSSE envelope, keyless or with a key |
113
+ | `vexpath advisory sync` | Download a local advisory snapshot for offline and air-gapped use |
114
+ | `vexpath policy test` | Try a gate against a scan that already ran |
115
+
116
+ ## Offline and reproducible
117
+
118
+ ```bash
119
+ vexpath advisory sync --ecosystem PyPI --dir ./advisories
120
+ vexpath scan . --snapshot ./advisories
121
+ ```
122
+
123
+ A scan against a pinned snapshot can be re-derived. One against the live API
124
+ cannot, and every report says which it was — a clearance nobody can reproduce
125
+ is a claim, not a finding.
126
+
127
+ ## It never runs your dependencies
128
+
129
+ Source is parsed with `ast`, never imported. `setup.py` is read, never
130
+ executed. Archives are unpacked, never installed. A tool that executed what it
131
+ analysed would be a worse supply-chain risk than the one it was looking for.
132
+
133
+ ## What it covers
134
+
135
+ Advisory matching works for every ecosystem OSV publishes. **Reachability is
136
+ Python only** — it is a real static analysis, not a heuristic, and one done
137
+ properly for one language is worth more than four done badly. Lockfiles read:
138
+ `uv.lock`, `poetry.lock`, `pdm.lock`, `Pipfile.lock`, `package-lock.json`,
139
+ `pnpm-lock.yaml`, `requirements.txt` (pinned).
140
+
141
+ `vexpath version` prints exactly what the build you have can do, because a
142
+ cleared finding means nothing unless you know whether reachability ran.
143
+
144
+ ## In CI
145
+
146
+ ```yaml
147
+ - uses: Unknown122-coder/vexpath@v1
148
+ with:
149
+ policy: balanced
150
+ ```
151
+
152
+ The Action caches call graphs, writes SARIF for code scanning, and can comment
153
+ on the pull request. A cold scan takes minutes; a warm one takes seconds.
154
+
155
+ ## Standards
156
+
157
+ purl, OSV, CycloneDX 1.4–1.6, SPDX 2.2–2.3, OpenVEX 0.2.0, in-toto Statement
158
+ v1, DSSE, Sigstore, SARIF 2.1.0, CVSS 3.x, PEP 440, semver, CEL.
159
+
160
+ Apache 2.0.
@@ -0,0 +1,23 @@
1
+ vexpath/__init__.py,sha256=9UdsTdkfGG85KW7cYT9n8ssTPmuF56UagsP2kfktRic,367
2
+ vexpath/credentials.py,sha256=EkMfINj6GBEKHwrDFXnKRmeUtjdJFH1i4ro56lhEqZM,7025
3
+ vexpath/exit_codes.py,sha256=yXzpV0k6S-wWud25Vb9fq2IrOid4vTN84SuBxM2ZElo,877
4
+ vexpath/main.py,sha256=rZRz8tq3mtDqjeP0wVyNceZGwQpY-YWPtobyl4KAsmg,4238
5
+ vexpath/output.py,sha256=25sBVpp7XzATSeWFqhJhIl3VGeFEDq55YfVcwiVVCJ4,2634
6
+ vexpath/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
7
+ vexpath/sources.py,sha256=R1LbuynVhdp0LSyZJO82-Cuu_CQ-quBFI8ZNLu7LYqY,3164
8
+ vexpath/commands/__init__.py,sha256=2AvVdvd5UuwMyqX42InQKDECZJqebYLFTY8i-6XhN-k,97
9
+ vexpath/commands/advisory.py,sha256=i9g-WO0Y2q4QrAda_yd8ir6qwTfBJTjKLpPzArFr_2I,11362
10
+ vexpath/commands/attest.py,sha256=nUnPEi4T6IIf8nlHNMGLaNwhHAks9N9oMWpw1W6KiMQ,11989
11
+ vexpath/commands/auth.py,sha256=MP71lzwmhZmPzuWqwZgLI_imf57bzTryu1DZJ-m0NA4,8185
12
+ vexpath/commands/policy.py,sha256=1bfYVzFl8SlH9EidI0sYrahm500wCLDqD5G_yL4cZ0w,6413
13
+ vexpath/commands/reach.py,sha256=P0xnfBc6uNDwZeMCLUID5Y_yGNqbkCDUDxnEJdWS2m4,8014
14
+ vexpath/commands/report.py,sha256=SLP5pcmY4qqNrXe41hVvax9bcJgk1dnQrVLcFQsfPss,7058
15
+ vexpath/commands/sbom.py,sha256=AU0BdNH7WJBzdWN7XpavZBGR2RYCvXKQ0YfBBCXhWUw,5318
16
+ vexpath/commands/scan.py,sha256=sg66q_Nn_ssyPLnXchXGS7brbz7VzFdrf8aI3Dt3etM,10716
17
+ vexpath/commands/upload.py,sha256=sPg06oOkNy50D_PCjogXsuHaVY9BMd-lv-xh_vdBzz8,3536
18
+ vexpath/commands/vex.py,sha256=KECDVsq9rpMhj8Hn40a1_-GFwYHPqse7r-10YnmAjHw,8533
19
+ vexpath-0.1.0.dist-info/METADATA,sha256=-2ENm6rYdaK3GrjvAwoCWbm7MMEslDphBocMpQlCwS8,6285
20
+ vexpath-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
21
+ vexpath-0.1.0.dist-info/entry_points.txt,sha256=sewPiDFshBnTQm9jt3fBPiTyWAZSOhYt1AOuZr05qfg,45
22
+ vexpath-0.1.0.dist-info/licenses/LICENSE,sha256=Se1xttJWiYYXeBLRjuUy6JeLKn6LKGk68SxdRbiI37w,11340
23
+ vexpath-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ vexpath = vexpath.main:app