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.
Files changed (66) hide show
  1. zerobom-0.1.0/.gitignore +33 -0
  2. zerobom-0.1.0/CHANGELOG.md +29 -0
  3. zerobom-0.1.0/LICENSE +200 -0
  4. zerobom-0.1.0/PKG-INFO +223 -0
  5. zerobom-0.1.0/README.md +176 -0
  6. zerobom-0.1.0/SECURITY.md +32 -0
  7. zerobom-0.1.0/pyproject.toml +173 -0
  8. zerobom-0.1.0/sources.yaml +61 -0
  9. zerobom-0.1.0/src/zerobom/__init__.py +71 -0
  10. zerobom-0.1.0/src/zerobom/_version.py +14 -0
  11. zerobom-0.1.0/src/zerobom/backends/__init__.py +58 -0
  12. zerobom-0.1.0/src/zerobom/backends/_http.py +496 -0
  13. zerobom-0.1.0/src/zerobom/backends/base.py +92 -0
  14. zerobom-0.1.0/src/zerobom/backends/conformance.py +249 -0
  15. zerobom-0.1.0/src/zerobom/backends/dependency_track.py +507 -0
  16. zerobom-0.1.0/src/zerobom/backends/k8s_sbom.py +931 -0
  17. zerobom-0.1.0/src/zerobom/backends/local_sbom.py +299 -0
  18. zerobom-0.1.0/src/zerobom/backends/oci_sbom.py +1227 -0
  19. zerobom-0.1.0/src/zerobom/backends/registry.py +283 -0
  20. zerobom-0.1.0/src/zerobom/backends/sbom_parser.py +527 -0
  21. zerobom-0.1.0/src/zerobom/cli.py +1338 -0
  22. zerobom-0.1.0/src/zerobom/data/__init__.py +1 -0
  23. zerobom-0.1.0/src/zerobom/data/demo_article.json +8 -0
  24. zerobom-0.1.0/src/zerobom/data/demo_extracted.json +48 -0
  25. zerobom-0.1.0/src/zerobom/data/demo_sbom.cdx.json +31 -0
  26. zerobom-0.1.0/src/zerobom/extract/__init__.py +23 -0
  27. zerobom-0.1.0/src/zerobom/extract/base.py +49 -0
  28. zerobom-0.1.0/src/zerobom/extract/openai_compat.py +483 -0
  29. zerobom-0.1.0/src/zerobom/extract/prompts.py +198 -0
  30. zerobom-0.1.0/src/zerobom/ingest/__init__.py +59 -0
  31. zerobom-0.1.0/src/zerobom/ingest/fetcher.py +510 -0
  32. zerobom-0.1.0/src/zerobom/ingest/prefilter.py +207 -0
  33. zerobom-0.1.0/src/zerobom/ingest/rss.py +793 -0
  34. zerobom-0.1.0/src/zerobom/ingest/state.py +173 -0
  35. zerobom-0.1.0/src/zerobom/models.py +1018 -0
  36. zerobom-0.1.0/src/zerobom/outputs/__init__.py +67 -0
  37. zerobom-0.1.0/src/zerobom/outputs/github_issue.py +725 -0
  38. zerobom-0.1.0/src/zerobom/outputs/json_out.py +83 -0
  39. zerobom-0.1.0/src/zerobom/outputs/sarif.py +260 -0
  40. zerobom-0.1.0/src/zerobom/outputs/slack.py +487 -0
  41. zerobom-0.1.0/src/zerobom/outputs/terminal.py +161 -0
  42. zerobom-0.1.0/src/zerobom/outputs/webhook.py +558 -0
  43. zerobom-0.1.0/src/zerobom/pipeline.py +396 -0
  44. zerobom-0.1.0/src/zerobom/py.typed +0 -0
  45. zerobom-0.1.0/src/zerobom/triage/__init__.py +43 -0
  46. zerobom-0.1.0/src/zerobom/triage/actions.py +272 -0
  47. zerobom-0.1.0/src/zerobom/triage/server.py +543 -0
  48. zerobom-0.1.0/src/zerobom/triage/store.py +443 -0
  49. zerobom-0.1.0/src/zerobom/verify/__init__.py +95 -0
  50. zerobom-0.1.0/src/zerobom/verify/grounding.py +636 -0
  51. zerobom-0.1.0/src/zerobom/verify/osv_compiler.py +1567 -0
  52. zerobom-0.1.0/src/zerobom/verify/purl.py +1012 -0
  53. zerobom-0.1.0/src/zerobom/verify/scorer.py +281 -0
  54. zerobom-0.1.0/tests/__init__.py +0 -0
  55. zerobom-0.1.0/tests/test_alerting_and_triage.py +1435 -0
  56. zerobom-0.1.0/tests/test_backend_conformance.py +464 -0
  57. zerobom-0.1.0/tests/test_benchmarks.py +390 -0
  58. zerobom-0.1.0/tests/test_cli_and_outputs.py +1086 -0
  59. zerobom-0.1.0/tests/test_cloud_plugins.py +954 -0
  60. zerobom-0.1.0/tests/test_enterprise_backends.py +1507 -0
  61. zerobom-0.1.0/tests/test_extract.py +478 -0
  62. zerobom-0.1.0/tests/test_github_ci.py +797 -0
  63. zerobom-0.1.0/tests/test_ingest.py +703 -0
  64. zerobom-0.1.0/tests/test_local_sbom.py +1038 -0
  65. zerobom-0.1.0/tests/test_release_and_docs.py +240 -0
  66. zerobom-0.1.0/tests/test_verify.py +1957 -0
@@ -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
+ [![CI](https://img.shields.io/github/actions/workflow/status/zerobom-dev/zerobom/zerobom-ci.yml?branch=main&label=CI)](https://github.com/zerobom-dev/zerobom/actions/workflows/zerobom-ci.yml)
53
+ [![Docs](https://img.shields.io/github/actions/workflow/status/zerobom-dev/zerobom/docs.yml?branch=main&label=docs)](https://zerobom.dev/)
54
+ [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
55
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
56
+ [![Standards: OSV 1.6.7 & SARIF 2.1.0](https://img.shields.io/badge/standards-OSV%201.6.7%20%7C%20SARIF%202.1.0-brightgreen.svg)](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
+ ![zerobom offline demo](docs/assets/demo-preview.svg)
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)