zerobom 0.1.0__tar.gz
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.
- zerobom-0.1.0/.gitignore +33 -0
- zerobom-0.1.0/CHANGELOG.md +29 -0
- zerobom-0.1.0/LICENSE +200 -0
- zerobom-0.1.0/PKG-INFO +223 -0
- zerobom-0.1.0/README.md +176 -0
- zerobom-0.1.0/SECURITY.md +32 -0
- zerobom-0.1.0/pyproject.toml +173 -0
- zerobom-0.1.0/sources.yaml +61 -0
- zerobom-0.1.0/src/zerobom/__init__.py +71 -0
- zerobom-0.1.0/src/zerobom/_version.py +14 -0
- zerobom-0.1.0/src/zerobom/backends/__init__.py +58 -0
- zerobom-0.1.0/src/zerobom/backends/_http.py +496 -0
- zerobom-0.1.0/src/zerobom/backends/base.py +92 -0
- zerobom-0.1.0/src/zerobom/backends/conformance.py +249 -0
- zerobom-0.1.0/src/zerobom/backends/dependency_track.py +507 -0
- zerobom-0.1.0/src/zerobom/backends/k8s_sbom.py +931 -0
- zerobom-0.1.0/src/zerobom/backends/local_sbom.py +299 -0
- zerobom-0.1.0/src/zerobom/backends/oci_sbom.py +1227 -0
- zerobom-0.1.0/src/zerobom/backends/registry.py +283 -0
- zerobom-0.1.0/src/zerobom/backends/sbom_parser.py +527 -0
- zerobom-0.1.0/src/zerobom/cli.py +1338 -0
- zerobom-0.1.0/src/zerobom/data/__init__.py +1 -0
- zerobom-0.1.0/src/zerobom/data/demo_article.json +8 -0
- zerobom-0.1.0/src/zerobom/data/demo_extracted.json +48 -0
- zerobom-0.1.0/src/zerobom/data/demo_sbom.cdx.json +31 -0
- zerobom-0.1.0/src/zerobom/extract/__init__.py +23 -0
- zerobom-0.1.0/src/zerobom/extract/base.py +49 -0
- zerobom-0.1.0/src/zerobom/extract/openai_compat.py +483 -0
- zerobom-0.1.0/src/zerobom/extract/prompts.py +198 -0
- zerobom-0.1.0/src/zerobom/ingest/__init__.py +59 -0
- zerobom-0.1.0/src/zerobom/ingest/fetcher.py +510 -0
- zerobom-0.1.0/src/zerobom/ingest/prefilter.py +207 -0
- zerobom-0.1.0/src/zerobom/ingest/rss.py +793 -0
- zerobom-0.1.0/src/zerobom/ingest/state.py +173 -0
- zerobom-0.1.0/src/zerobom/models.py +1018 -0
- zerobom-0.1.0/src/zerobom/outputs/__init__.py +67 -0
- zerobom-0.1.0/src/zerobom/outputs/github_issue.py +725 -0
- zerobom-0.1.0/src/zerobom/outputs/json_out.py +83 -0
- zerobom-0.1.0/src/zerobom/outputs/sarif.py +260 -0
- zerobom-0.1.0/src/zerobom/outputs/slack.py +487 -0
- zerobom-0.1.0/src/zerobom/outputs/terminal.py +161 -0
- zerobom-0.1.0/src/zerobom/outputs/webhook.py +558 -0
- zerobom-0.1.0/src/zerobom/pipeline.py +396 -0
- zerobom-0.1.0/src/zerobom/py.typed +0 -0
- zerobom-0.1.0/src/zerobom/triage/__init__.py +43 -0
- zerobom-0.1.0/src/zerobom/triage/actions.py +272 -0
- zerobom-0.1.0/src/zerobom/triage/server.py +543 -0
- zerobom-0.1.0/src/zerobom/triage/store.py +443 -0
- zerobom-0.1.0/src/zerobom/verify/__init__.py +95 -0
- zerobom-0.1.0/src/zerobom/verify/grounding.py +636 -0
- zerobom-0.1.0/src/zerobom/verify/osv_compiler.py +1567 -0
- zerobom-0.1.0/src/zerobom/verify/purl.py +1012 -0
- zerobom-0.1.0/src/zerobom/verify/scorer.py +281 -0
- zerobom-0.1.0/tests/__init__.py +0 -0
- zerobom-0.1.0/tests/test_alerting_and_triage.py +1435 -0
- zerobom-0.1.0/tests/test_backend_conformance.py +464 -0
- zerobom-0.1.0/tests/test_benchmarks.py +390 -0
- zerobom-0.1.0/tests/test_cli_and_outputs.py +1086 -0
- zerobom-0.1.0/tests/test_cloud_plugins.py +954 -0
- zerobom-0.1.0/tests/test_enterprise_backends.py +1507 -0
- zerobom-0.1.0/tests/test_extract.py +478 -0
- zerobom-0.1.0/tests/test_github_ci.py +797 -0
- zerobom-0.1.0/tests/test_ingest.py +703 -0
- zerobom-0.1.0/tests/test_local_sbom.py +1038 -0
- zerobom-0.1.0/tests/test_release_and_docs.py +240 -0
- zerobom-0.1.0/tests/test_verify.py +1957 -0
zerobom-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Virtual environments
|
|
2
|
+
.venv/
|
|
3
|
+
.venv-*/
|
|
4
|
+
venv/
|
|
5
|
+
|
|
6
|
+
# Python / build artifacts
|
|
7
|
+
__pycache__/
|
|
8
|
+
*.py[cod]
|
|
9
|
+
*$py.class
|
|
10
|
+
*.egg-info/
|
|
11
|
+
dist/
|
|
12
|
+
build/
|
|
13
|
+
site/
|
|
14
|
+
htmlcov/
|
|
15
|
+
.coverage
|
|
16
|
+
.coverage.*
|
|
17
|
+
|
|
18
|
+
# Caches, local state, and generated reports
|
|
19
|
+
.cache/
|
|
20
|
+
.mypy_cache/
|
|
21
|
+
.pytest_cache/
|
|
22
|
+
.ruff_cache/
|
|
23
|
+
.zerobom/
|
|
24
|
+
.zerobom-reports/
|
|
25
|
+
*.sqlite
|
|
26
|
+
*.sqlite3
|
|
27
|
+
*.sqlite-wal
|
|
28
|
+
*.sqlite-shm
|
|
29
|
+
|
|
30
|
+
# Local secrets & environment overrides
|
|
31
|
+
.env
|
|
32
|
+
.env.*
|
|
33
|
+
!.env.example
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `zerobom` are documented in this file following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/).
|
|
4
|
+
|
|
5
|
+
## [0.1.0] - 2026-11-21
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
- **Deterministic Verification Engine (`zerobom.verify`):**
|
|
9
|
+
- Deterministic quote grounding (exact/normalized substring match with left/right token boundary guards and colon-list negation filtering).
|
|
10
|
+
- ASCII PackageURL canonicalization, unnamespaced & `generic`-namespace blocklist, Solr-safe Maven/PyPI/npm/Go `HttpRegistryChecker` with TTL SQLite caching and `follow_redirects=False`.
|
|
11
|
+
- Two-axis credibility scorer (`AUTO >= 0.75`, `TRIAGE 0.50-0.74`, `DROP < 0.50`), isolating `TRIAGE`/unbounded/registry-error claims from `AUTO` alerts.
|
|
12
|
+
- OSV 1.6.7-compatible compiler using the non-official local namespace `PRECVE-YYYY-XXXXXXXX` (with `Generic` and `CloudLinux` documented as `zerobom` extensions) and deterministic `univers` version evaluation.
|
|
13
|
+
- **Ingestion & Narrow LLM Layer (`zerobom.ingest`, `zerobom.extract`):**
|
|
14
|
+
- SSRF-hardened `SafeHttpFetcher` (DNS validation per hop, `<= 3` redirects, bounded streaming bytes, `Content-Type` allowlist).
|
|
15
|
+
- RSS, Atom, XML sitemap, and HTML index pollers + SQLite ETag/SHA-256 deduplication store.
|
|
16
|
+
- Pre-LLM keyword/regex prefilter preserving pre-CVE alias disclosures (`known_aliases`).
|
|
17
|
+
- Isolated `Extractor` protocol and `OpenAICompatExtractor` (`httpx`, Ollama/OpenAI/Gemini compat/OpenRouter/vLLM, prompt `v1.4`).
|
|
18
|
+
- **Pluggable Inventory Backends (`zerobom.backends`, `plugins/`):**
|
|
19
|
+
- Cloud-agnostic `InventoryBackend` protocol, `zerobom.backends` entry-point registry, hardened CycloneDX (1.4–1.6) & SPDX (2.2–2.3) parser (`InMemoryComponentIndex`), and conformance suite (`assert_backend_conformance`).
|
|
20
|
+
- Built-in enterprise backends: `local_sbom`, `dependency_track`, `oci_sbom` (with in-toto DSSE unwrapping & realm pinning), `k8s_sbom` (Trivy Operator CRDs).
|
|
21
|
+
- Standalone workspace cloud plugins (`zerobom-aws`, `zerobom-gcp`, `zerobom-azure`) covering Security Hub v2, S3 SBOMs, GCP Artifact Analysis, GCS SBOMs, Azure Resource Graph, and Azure Blob SBOMs.
|
|
22
|
+
- **CLI, Alerting, Human Triage & CI (`zerobom.cli`, `zerobom.outputs`, `zerobom.triage`, `action.yml`):**
|
|
23
|
+
- Offline `zerobom demo`, pure deterministic `zerobom scan`, `zerobom check`, `zerobom watch`, `zerobom backends`, and `--version`.
|
|
24
|
+
- Rich terminal renderer, JSON report, and SARIF 2.1.0 GitHub Code Scanning exporter.
|
|
25
|
+
- HMAC-SHA256 webhooks, Slack Block Kit alerts, persistent SQLite triage queue (`zerobom triage list|show|approve|reject`), signed Slack callback server & Socket Mode worker (`zerobom triage-worker`), and idempotent `GitHubIssueSyncer`.
|
|
26
|
+
- Reusable composite GitHub Action (`action.yml`) with SQLite state caching, SARIF upload, and script-injection hardening.
|
|
27
|
+
- **Benchmarks & Documentation:**
|
|
28
|
+
- Two-tier public benchmark (`benchmarks/run_evals.py`) covering `16` deterministic adversarial offline cases (`100.00%` routing, `0/16` escape) and `46` synthetic pre-CVE + marketing trap dev cases (`97.83%` routing, `100.00%` precision on `gpt-4o-mini` `v1.4`).
|
|
29
|
+
- Zensical + `mkdocstrings-python` documentation site, contributor templates, and OIDC PyPI Trusted Publishing release workflow.
|
zerobom-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, in at least one of the following
|
|
110
|
+
places: within a NOTICE text file distributed as part of the
|
|
111
|
+
Derivative Works; within the Source form or documentation,
|
|
112
|
+
if provided along with the Derivative Works; or, within a
|
|
113
|
+
display generated by the Derivative Works, if and wherever such
|
|
114
|
+
third-party notices appear. The contents of the NOTICE file
|
|
115
|
+
are for informational purposes only and do not modify the
|
|
116
|
+
License. You may add Your own attribution notices within
|
|
117
|
+
Derivative Works that You distribute, alongside or as an
|
|
118
|
+
addendum to the NOTICE text file from the Work, provided
|
|
119
|
+
that such additional attribution notices cannot be construed
|
|
120
|
+
as modifying the License.
|
|
121
|
+
|
|
122
|
+
You may add Your own copyright notice to Your modifications and
|
|
123
|
+
may provide additional or different license terms and conditions
|
|
124
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
125
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
126
|
+
reproduction, or distribution of the Work otherwise complies with
|
|
127
|
+
the conditions stated in this License.
|
|
128
|
+
|
|
129
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
130
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
131
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
132
|
+
this License, without any additional terms or conditions.
|
|
133
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
134
|
+
the terms of any separate license agreement you may have executed
|
|
135
|
+
with Licensor regarding such Contributions.
|
|
136
|
+
|
|
137
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
138
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
139
|
+
except as required for reasonable and customary use in describing the
|
|
140
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
141
|
+
|
|
142
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
143
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
144
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
145
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
146
|
+
implied, including, without limitation, any warranties or conditions
|
|
147
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
148
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
149
|
+
appropriateness of using or redistributing the Work and assume any
|
|
150
|
+
risks associated with Your exercise of permissions under this License.
|
|
151
|
+
|
|
152
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
153
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
154
|
+
unless required by applicable law (such as deliberate gross
|
|
155
|
+
negligence) or agreed to in writing, shall any Contributor be liable
|
|
156
|
+
to You for damages, including any direct, indirect, special,
|
|
157
|
+
incidental, or consequential damages of any kind arising as a result of
|
|
158
|
+
this License or out of the use or inability to use the Work (including
|
|
159
|
+
but not limited to damages for loss of goodwill, work stoppage,
|
|
160
|
+
computer failure or malfunction, or any and all other commercial
|
|
161
|
+
damages or losses), even if such Contributor has been advised of the
|
|
162
|
+
possibility of such damages.
|
|
163
|
+
|
|
164
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
165
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
166
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
167
|
+
or other liability obligations and/or rights consistent with this
|
|
168
|
+
License. However, in accepting such obligations, You may act only
|
|
169
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
170
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
171
|
+
defend, and hold each Contributor harmless for any liability
|
|
172
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
173
|
+
of your accepting any such warranty or additional liability.
|
|
174
|
+
|
|
175
|
+
END OF TERMS AND CONDITIONS
|
|
176
|
+
|
|
177
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
178
|
+
|
|
179
|
+
To apply the Apache License to your work, attach the following
|
|
180
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
181
|
+
replaced with your own identifying information. (Don't include
|
|
182
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
183
|
+
comment syntax for the file format. We also recommend that a
|
|
184
|
+
file or class name and description of purpose be included on the
|
|
185
|
+
same "printed page" as the copyright notice for easier
|
|
186
|
+
identification within third-party archives.
|
|
187
|
+
|
|
188
|
+
Copyright 2026 zerobom Contributors
|
|
189
|
+
|
|
190
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
191
|
+
you may not use this file except in compliance with the License.
|
|
192
|
+
You may obtain a copy of the License at
|
|
193
|
+
|
|
194
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
195
|
+
|
|
196
|
+
Unless required by applicable law or agreed to in writing, software
|
|
197
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
198
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
199
|
+
See the License for the specific language governing permissions and
|
|
200
|
+
limitations under the License.
|
zerobom-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: zerobom
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Deterministic pre-CVE security advisory verification and OSV compilation engine.
|
|
5
|
+
Project-URL: Homepage, https://zerobom.dev/
|
|
6
|
+
Project-URL: Documentation, https://zerobom.dev/
|
|
7
|
+
Project-URL: Repository, https://github.com/zerobom-dev/zerobom
|
|
8
|
+
Project-URL: Issues, https://github.com/zerobom-dev/zerobom/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/zerobom-dev/zerobom/blob/main/CHANGELOG.md
|
|
10
|
+
Author: zerobom Contributors
|
|
11
|
+
License-Expression: Apache-2.0
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: appsec,cyclonedx,osv,pre-cve,sarif,sbom,security,spdx,supply-chain,vulnerability
|
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
|
15
|
+
Classifier: Environment :: Console
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: Intended Audience :: Information Technology
|
|
18
|
+
Classifier: Intended Audience :: System Administrators
|
|
19
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
20
|
+
Classifier: Operating System :: OS Independent
|
|
21
|
+
Classifier: Programming Language :: Python :: 3
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
25
|
+
Classifier: Topic :: Security
|
|
26
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
27
|
+
Classifier: Typing :: Typed
|
|
28
|
+
Requires-Python: >=3.11
|
|
29
|
+
Requires-Dist: feedparser>=6.0
|
|
30
|
+
Requires-Dist: httpx>=0.27
|
|
31
|
+
Requires-Dist: packageurl-python>=0.16
|
|
32
|
+
Requires-Dist: pydantic<3,>=2.9
|
|
33
|
+
Requires-Dist: pyyaml>=6.0
|
|
34
|
+
Requires-Dist: rich>=13.9
|
|
35
|
+
Requires-Dist: trafilatura>=1.12
|
|
36
|
+
Requires-Dist: typer>=0.12
|
|
37
|
+
Requires-Dist: univers>=30.11.0
|
|
38
|
+
Provides-Extra: aws
|
|
39
|
+
Requires-Dist: zerobom-aws<0.2.0,>=0.1.0; extra == 'aws'
|
|
40
|
+
Provides-Extra: azure
|
|
41
|
+
Requires-Dist: zerobom-azure<0.2.0,>=0.1.0; extra == 'azure'
|
|
42
|
+
Provides-Extra: gcp
|
|
43
|
+
Requires-Dist: zerobom-gcp<0.2.0,>=0.1.0; extra == 'gcp'
|
|
44
|
+
Provides-Extra: slack
|
|
45
|
+
Requires-Dist: slack-sdk>=3.33; extra == 'slack'
|
|
46
|
+
Description-Content-Type: text/markdown
|
|
47
|
+
|
|
48
|
+
# zerobom
|
|
49
|
+
|
|
50
|
+
> **Hunt CVE-less and pre-CVE vulnerabilities published in security blogs against your software inventories before NVD or OSV publishes an entry.**
|
|
51
|
+
|
|
52
|
+
[](https://github.com/zerobom-dev/zerobom/actions/workflows/zerobom-ci.yml)
|
|
53
|
+
[](https://zerobom.dev/)
|
|
54
|
+
[](LICENSE)
|
|
55
|
+
[](https://www.python.org/downloads/)
|
|
56
|
+
[](docs/architecture.md)
|
|
57
|
+
|
|
58
|
+
`zerobom` bridges the window between **security blog disclosure** (Google Project Zero, Wiz Research, Trail of Bits, Datadog Security Labs, vendor blogs) and **official CVE/NVD indexing**—isolating the LLM strictly to raw text extraction while keeping quote grounding, package resolution, and version-range matching 100% deterministic.
|
|
59
|
+
|
|
60
|
+
The LLM is a narrow, replaceable **~15% extraction layer**. Every extracted claim is grounded verbatim in source text, validated against canonical Package URLs and optional package registries, compiled into **OSV 1.6.7-compatible JSON**, and matched deterministically against your CycloneDX, SPDX, container, Kubernetes, or cloud software inventories using [`univers`](https://github.com/aboutcode-org/univers) ecosystem version math.
|
|
61
|
+
|
|
62
|
+

|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## 60-Second Quickstart (Zero API Keys Required)
|
|
67
|
+
|
|
68
|
+
Run the wheel-bundled offline demonstration using [`uv`](https://docs.astral.sh/uv/):
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
uvx zerobom demo
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
What happens inside `zerobom demo`:
|
|
75
|
+
|
|
76
|
+
1. Loads a bundled sample advisory naming `requests (<2.31.0)`, `openssl` on Debian 11 (`<1.1.1n-0+deb11u5`), and a noisy `utils` claim.
|
|
77
|
+
2. **Grounds quotes verbatim** and blocks the generic unnamespaced `utils` package claim.
|
|
78
|
+
3. Compiles **OSV `PRECVE-2026-7DA3A045`** (non-official local deterministic ID prefix) and matches the bundled CycloneDX SBOM via both canonical PURL (`pkg:pypi/requests@2.30.0`) and Debian binary `?upstream=openssl` metadata (`libssl1.1@1.1.1n-0+deb11u4` on `Debian:11`).
|
|
79
|
+
|
|
80
|
+
### Common Workflows
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
# Pure deterministic zero-LLM scan against OSV JSON + CycloneDX/SPDX SBOM
|
|
84
|
+
zerobom scan --osv advisories/ --sbom sbom.cdx.json --format sarif > zerobom.sarif
|
|
85
|
+
|
|
86
|
+
# Check a single security blog advisory URL against your inventory (defaults to local Ollama or ZEROBOM_LLM_*)
|
|
87
|
+
zerobom check --url https://research.example.org/post --tier tier_1 --sbom sbom.cdx.json
|
|
88
|
+
|
|
89
|
+
# Poll curated RSS/Atom/sitemap/HTML feeds with SQLite ETag deduplication
|
|
90
|
+
zerobom watch --feeds sources.yaml --sbom ./sboms/ --state-db .zerobom/state.sqlite --format sarif > results.sarif
|
|
91
|
+
|
|
92
|
+
# List discovered inventory backend plugins
|
|
93
|
+
zerobom backends
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
> Configure any OpenAI-compatible LLM endpoint (Ollama, OpenAI, Gemini OpenAI compat, OpenRouter, vLLM) via `ZEROBOM_LLM_BASE_URL`, `ZEROBOM_LLM_MODEL`, and `ZEROBOM_LLM_API_KEY`. Hosted endpoints receive only fetched public blog titles/URLs/text (up to `24` KB); SBOM inventories never leave your host. See [Getting Started](docs/getting-started.md).
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## Why Not Another LLM Security Wrapper?
|
|
101
|
+
|
|
102
|
+
```mermaid
|
|
103
|
+
flowchart LR
|
|
104
|
+
A["RSS / Atom / URL\n(SSRF-checked fetcher\n& SQLite ETag dedup)"] --> B["Deterministic Prefilter\n(drops marketing, hiring,\nevent noise pre-LLM)"]
|
|
105
|
+
B --> C["Narrow LLM Extractor (~15%)\n(strict JSON schema,\nnever compares versions)"]
|
|
106
|
+
C --> D["Verbatim Quote Grounding\n+ ASCII PURL & Registry Gate\n(blocks generic/404 names)"]
|
|
107
|
+
D --> E{"Two-Axis Credibility Gate\ntier_weight * specificity"}
|
|
108
|
+
E -- ">= 0.75 (AUTO)" --> F["OSV Compiler + univers\n(AUTO claims only)"]
|
|
109
|
+
E -- "0.50-0.74 (TRIAGE)" --> T["SQLite Triage Queue\n+ Slack/CLI Review"]
|
|
110
|
+
E -- "< 0.50 (DROP)" --> X["Drop Silently"]
|
|
111
|
+
F --> G["Pluggable Inventory Backends\n(CycloneDX, SPDX, DT, OCI,\nK8s, AWS / GCP / Azure)"]
|
|
112
|
+
G --> H["Outputs & Alerting\n(SARIF 2.1.0, GitHub Issues,\nWebhook, Slack + Approve Worker)"]
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
- **LLMs never compare versions.** All version ranges (`SemVer`, `PEP 440`, `Maven`, `Go`, `Debian dpkg`, `RPM`, `Alpine`, `Cargo`, `RubyGems`, `NuGet`, `Composer`) execute inside `univers` + OSV `"0"` sentinel range logic. Standard package ecosystems validate against OSV 1.6.7 using the non-official local prefix `PRECVE-YYYY-XXXXXXXX`; `Generic` runtimes and vendor streams such as `CloudLinux` are `zerobom` ecosystem extensions.
|
|
116
|
+
- **Verbatim quote grounding.** Every claim must include an exact/normalized `evidence_quote` verified in the fetched article body alongside left/right boundary-checked package and version tokens.
|
|
117
|
+
- **No hallucinated packages.** Fuzzy names resolve to canonical ASCII Package URLs (`pkg:pypi/requests`), generic names (`core`, `utils`, `app`) without explicit package namespaces fail closed, and `--verify-registry` confirms existence against PyPI/npm/Maven/Go without following redirects (capping upstream registry lookup errors at `TRIAGE`).
|
|
118
|
+
- **Two-axis credibility routing:** `composite_score = source_tier_weight * extraction_specificity`:
|
|
119
|
+
- `>= 0.75` (`AUTO`): Queries SBOM inventory automatically and alerts only when vulnerable hits > 0 (weak quotes, unbounded zero-days, and registry errors are capped `<= 0.70`).
|
|
120
|
+
- `0.50 – 0.74` (`TRIAGE`): Holds in SQLite triage queue / Slack review until human approval.
|
|
121
|
+
- `< 0.50` (`DROP`): Suppresses silently.
|
|
122
|
+
|
|
123
|
+
### How `zerobom` Fits Alongside Existing Scanners
|
|
124
|
+
|
|
125
|
+
`zerobom` is an **upstream pre-CVE discovery and OSV compilation feeder**, not a replacement for authoritative CVE scanners:
|
|
126
|
+
|
|
127
|
+
| Tooling Category | Strength | `T+0` Pre-CVE Blog Window | Relationship with `zerobom` |
|
|
128
|
+
| --- | --- | --- | --- |
|
|
129
|
+
| **OSV-Scanner / Grype / Trivy** | Fast, authoritative matching against published CVE/GHSA/OSV DBs | Blind until NVD/OSV indexes an advisory | `zerobom` compiles verified blog advisories into OSV JSON for `zerobom scan` or OSV pipelines |
|
|
130
|
+
| **OWASP Dependency-Track** | Continuous SBOM lifecycle platform & policy management | Relies on upstream NVD/OSS Index/OSV feeds | Queried directly via built-in `--backend dependency_track` |
|
|
131
|
+
| **Dependabot / Renovate** | Automated dependency bump PRs once GitHub Advisory DB updates | No alerts prior to GHSA/CVE publication | `zerobom` alerts SecOps earlier with verbatim blog quotes + fix commits |
|
|
132
|
+
| **OpenVEX / CSAF** | Exploitability status & vendor advisory exchange formats | Authoring/exchange standard, not blog discovery | Downstream companion (OpenVEX export planned in `v0.2.0`) |
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## Benchmark Results
|
|
137
|
+
|
|
138
|
+
Full methodology, 95% confidence bounds, known blind spots, and per-case breakdowns live in [`benchmarks/REPORT.md`](benchmarks/REPORT.md) (archived `v0.1.0` live run: [`benchmarks/results/live-eval-summary.json`](benchmarks/results/live-eval-summary.json) and [`benchmarks/results/live-eval-report.md`](benchmarks/results/live-eval-report.md)).
|
|
139
|
+
|
|
140
|
+
| Metric | Tier 1: Offline Deterministic (`16` cases) | Tier 2: Synthetic Dev Suite `gpt-4o-mini` / `v1.4` (`46` cases) |
|
|
141
|
+
| --- | ---: | ---: |
|
|
142
|
+
| **Routing Accuracy** | **100.00%** (`16/16`) | **97.83%** (`45/46`; CI `[88.66%, 99.62%]`) |
|
|
143
|
+
| **Package Precision** | **100.00%** (`12/12`, `0` FP) | **100.00%** (`37/37`, `0` FP; CI `[90.59%, 100%]`) |
|
|
144
|
+
| **Package Recall** | **100.00%** (`12/12`, `0` FN) | **97.37%** (`37/38`; CI `[86.51%, 99.53%]`) |
|
|
145
|
+
| **Package F1** | **100.00%** | **98.67%** |
|
|
146
|
+
| **Version Probe Accuracy** | **100.00%** (`18/18`) | **96.47%** (`82/85`; `82/82` on compiled OSVs) |
|
|
147
|
+
| **Quote Grounding Rate** | **84.21%** (`16/19`, adversarial drops) | **97.56%** (`40/41`) |
|
|
148
|
+
| **Hallucination Escape Rate** | **0.00%** (`0/16`; 95% CI upper `19.36%`) | **0.00%** (`0/46`; 95% CI upper `7.71%`) |
|
|
149
|
+
| **Marketing Trap FP Rate** | **0.00%** (`1/1` marketing trap; `5/5` drops) | **0.00%** (`0/10` leaked; CI `[0%, 27.75%]`) |
|
|
150
|
+
|
|
151
|
+
> **Scope note:** Tier 2 evaluates `36` concise synthetic historical advisory summaries (`332–584` chars each) + `10` traps across prompt iterations `v1.1`–`v1.4` on `gpt-4o-mini`. Full multi-KB HTML extraction via `trafilatura`, non-English blogs, and semantic negation handling remain active evaluation targets for a held-out corpus in `v0.2.0`.
|
|
152
|
+
|
|
153
|
+
Reproduce offline CI evals anytime:
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
uv run python benchmarks/run_evals.py --mode offline
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## Pluggable Inventory Backends (`zerobom.backends`)
|
|
162
|
+
|
|
163
|
+
Core `zerobom` has **zero cloud vendor dependencies**. Enterprise & cloud integrations load lazily via standard Python `zerobom.backends` entry points (`zerobom[aws|gcp|azure]` companion cloud packages publish alongside `v0.1.0` via `plugins-v*` tags):
|
|
164
|
+
|
|
165
|
+
| Backend Name | Package / Extra | Inventory Source |
|
|
166
|
+
| --- | --- | --- |
|
|
167
|
+
| `local_sbom` | built-in core | Local CycloneDX (1.4–1.6) & SPDX (2.2–2.3) JSON files/directories |
|
|
168
|
+
| `dependency_track` | built-in core | OWASP Dependency-Track `/api/v1/component/identity` API |
|
|
169
|
+
| `oci_sbom` | built-in core | OCI registry attached CycloneDX/SPDX SBOMs & in-toto/DSSE attestations |
|
|
170
|
+
| `k8s_sbom` | built-in core | Trivy Operator `sbomreports` / `clustersbomreports` CRDs |
|
|
171
|
+
| `aws_security_hub` | `zerobom[aws]` | AWS Security Hub `GetSoftwareV2` / `GetSoftwareResourcesV2` |
|
|
172
|
+
| `s3_sbom` | `zerobom[aws]` | Amazon S3 SBOM prefixes |
|
|
173
|
+
| `gcp_artifact_analysis` | `zerobom[gcp]` (+ `[adc]`) | GCP Container/Artifact Analysis package occurrences |
|
|
174
|
+
| `gcs_sbom` | `zerobom[gcp]` (+ `[adc]`) | Google Cloud Storage SBOM prefixes |
|
|
175
|
+
| `azure_resource_graph` | `zerobom[azure]` (+ `[identity]`) | Azure Resource Graph `microsoft.security/softwareinventories` |
|
|
176
|
+
| `azure_blob_sbom` | `zerobom[azure]` (+ `[identity]`) | Azure Blob Storage SBOM prefixes |
|
|
177
|
+
|
|
178
|
+
Want to add a custom inventory backend? Follow [Authoring `zerobom.backends` Inventory Plugins](docs/PLUGIN_AUTHORING.md).
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## Drop-In GitHub Action & SecOps Alerting
|
|
183
|
+
|
|
184
|
+
Use [`action.yml`](action.yml) in scheduled CI security scans to upload SARIF to GitHub Code Scanning or sync idempotent GitHub Issues:
|
|
185
|
+
|
|
186
|
+
```yaml
|
|
187
|
+
name: Pre-CVE SBOM Watch
|
|
188
|
+
on:
|
|
189
|
+
schedule:
|
|
190
|
+
- cron: "0 */6 * * *"
|
|
191
|
+
workflow_dispatch:
|
|
192
|
+
|
|
193
|
+
permissions:
|
|
194
|
+
contents: read
|
|
195
|
+
security-events: write
|
|
196
|
+
issues: write
|
|
197
|
+
|
|
198
|
+
jobs:
|
|
199
|
+
zerobom-watch:
|
|
200
|
+
runs-on: ubuntu-latest
|
|
201
|
+
steps:
|
|
202
|
+
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
|
|
203
|
+
- uses: zerobom-dev/zerobom@v0.1.0
|
|
204
|
+
with:
|
|
205
|
+
mode: watch
|
|
206
|
+
sbom: sbom.cdx.json
|
|
207
|
+
upload-sarif: "true"
|
|
208
|
+
create-github-issues: "true"
|
|
209
|
+
llm-base-url: ${{ secrets.ZEROBOM_LLM_BASE_URL }}
|
|
210
|
+
llm-model: ${{ secrets.ZEROBOM_LLM_MODEL }}
|
|
211
|
+
llm-api-key: ${{ secrets.ZEROBOM_LLM_API_KEY }}
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
- **Human-in-the-loop Slack / Webhook Triage:** Run `zerobom triage-worker` (signed HTTP `X-Slack-Signature` callback server or optional Socket Mode with `zerobom[slack]`) alongside `zerobom triage list|show|approve|reject`. See [Alerting & Triage](docs/alerting-and-triage.md).
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## Documentation & Community
|
|
219
|
+
|
|
220
|
+
- **Documentation:** [Getting Started](docs/getting-started.md) · [Architecture & Security](docs/architecture.md) · [Backends](docs/backends.md) · [Alerting & Triage](docs/alerting-and-triage.md) · [GitHub Action](docs/github-action.md) · [Benchmarks](docs/benchmarks.md) · [Plugin Authoring](docs/PLUGIN_AUTHORING.md)
|
|
221
|
+
- **Contribute in 1 Minute:** Add a security blog to [`sources.yaml`](sources.yaml), submit a benchmark fixture, or contribute a backend plugin—see [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
|
222
|
+
- **Security Policy:** See [`SECURITY.md`](SECURITY.md) for responsible disclosure and security boundaries.
|
|
223
|
+
- **License:** [Apache-2.0](LICENSE)
|