oss-intake 0.2.1__tar.gz

oss_intake-0.2.1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

oss_intake-0.2.1/PKG-INFO

@@ -0,0 +1,326 @@
+Metadata-Version: 2.4
+Name: oss-intake
+Version: 0.2.1
+Summary: Assess third-party open source software before adoption: known vulnerabilities, release lag and project health.
+Author: Ned Tavakol
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/ntavakol/OSS-Intake
+Project-URL: Source, https://github.com/ntavakol/OSS-Intake
+Project-URL: Issues, https://github.com/ntavakol/OSS-Intake/issues
+Project-URL: Changelog, https://github.com/ntavakol/OSS-Intake/blob/main/CHANGELOG.md
+Keywords: security,sbom,vulnerability,trivy,grype,osv,supply-chain
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# oss-intake
+
+[![ci](https://github.com/ntavakol/OSS-Intake/actions/workflows/ci.yml/badge.svg)](https://github.com/ntavakol/OSS-Intake/actions/workflows/ci.yml)
+[![codeql](https://github.com/ntavakol/OSS-Intake/actions/workflows/codeql.yml/badge.svg)](https://github.com/ntavakol/OSS-Intake/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/ntavakol/OSS-Intake/badge)](https://scorecard.dev/viewer/?uri=github.com/ntavakol/OSS-Intake)
+
+Assess third-party open source software before you adopt it. `oss-intake` answers two questions for a
+security or architecture review:
+
+1. **Is it vulnerable?** Known vulnerabilities in a container image and the dependencies bundled inside it.
+2. **Does the project patch?** Whether fixes that exist upstream are being shipped, how long they have been
+   available, and how active the project is.
+
+The second question is what a scanner alone does not answer. `oss-intake` measures **release lag**: findings
+where the fixed version of a dependency was already published before the project's release, so the project
+could have shipped it and did not. It then adds project health signals (release cadence, OpenSSF Scorecard,
+CISA KEV membership).
+
+## What it does
+
+- Runs [Trivy](https://github.com/aquasecurity/trivy) and, if installed, [Grype](https://github.com/anchore/grype)
+  against an image, and queries [OSV.dev](https://osv.dev) for the language packages Trivy found.
+- Merges the results into one row per vulnerability, package and version, recording which sources saw it.
+- Looks up when each fixed dependency version was published ([deps.dev](https://deps.dev)) and compares that
+  with the project's GitHub release date.
+- Reports release cadence from the GitHub API and the OpenSSF Scorecard score where one exists.
+- Audits the project's own GitHub Actions workflows: unpinned actions, known-bad action versions (such as the
+  compromised `trivy-action` tags), missing or write-all token permissions, and `pull_request_target` triggers.
+- Optionally suggests a likelihood value for a 5x5 risk matrix from configurable rules, clearly labelled
+  as a heuristic.
+- Writes `findings.csv`, `summary.md`, `assessment.json` and a self-contained `report.html`, plus the raw
+  scanner output under `raw/` as evidence.
+- Applies integrity checks to the scanners it runs: version pinning, a known-bad version list, SHA-256
+  verification and optional Sigstore (cosign) verification.
+
+## What it does not do
+
+- **It does not prove exploitability.** Scanners match component versions against advisory databases. A
+  finding means a version is listed as affected, not that the vulnerable code is reachable or exposed in your
+  deployment. The CSV has empty `triage_*` columns for recording reachability decisions.
+- It does not install, download, bundle or redistribute scanners. You install them; it verifies them.
+- It does not assess licences, secrets or misconfiguration, and it does not detect new malware. Packages already
+  listed in the OpenSSF malicious packages database (OSV `MAL-` entries) are flagged as malicious.
+- It does not give a risk rating. The likelihood suggestion is a starting point for an assessor.
+- It does not fix anything or open issues upstream.
+
+## Install
+
+Python 3.10 or later on Windows, macOS or Linux. No administrator rights are needed.
+
+```bash
+pipx install oss-intake
+```
+
+Releases are published to PyPI from GitHub Actions through trusted publishing, so PyPI shows each file's
+provenance (which workflow in this repository built it). Each GitHub release also carries a Sigstore signature
+bundle (`.sigstore.json`) for every file, verifiable with [sigstore-python](https://github.com/sigstore/sigstore-python).
+
+Windows PowerShell without pipx:
+
+```powershell
+py -m pip install --user pipx
+py -m pipx ensurepath
+# open a new terminal, then
+pipx install oss-intake
+```
+
+If `oss-intake` is "not recognized" after `pip install --user`, the per-user Scripts folder is not on PATH.
+Either add it, or run the tool through Python, which works everywhere:
+
+```powershell
+py -m oss_intake --help
+```
+
+### Install the scanners yourself, pinned and verified
+
+Install a specific version of each scanner from its official GitHub release, never "latest", and verify the
+download before you extract it. `oss-intake verify` does the hash comparison correctly on any platform
+(checksum files are served as `application/octet-stream`; they are parsed as bytes, with BOM and CRLF handled):
+
+```bash
+oss-intake verify --file trivy_0.76.1_windows-64bit.zip --checksums trivy_0.76.1_checksums.txt
+```
+
+Then record the SHA-256 of the extracted executable and pass it on every run (`oss-intake doctor` prints it):
+
+```bash
+oss-intake doctor
+```
+
+Trivy versions 0.69.4, 0.69.5 and 0.69.6 were malicious (CVE-2026-33634, March 2026). `oss-intake` refuses to
+run any version on its [known-bad list](src/oss_intake/data/known_bad.json).
+
+## Usage
+
+```bash
+oss-intake --image owner/app:1.2.3 --repo owner/app --out ./reports \
+  --image-src remote --trivy-version 0.76.1 --trivy-sha256 <sha256-of-trivy-executable> --likelihood
+```
+
+PowerShell (backtick continues a line):
+
+```powershell
+$env:GITHUB_TOKEN = "<optional token, raises the GitHub API rate limit>"
+oss-intake --image owner/app:1.2.3 --repo owner/app --out .\reports `
+  --image-src remote --trivy-version 0.76.1 --trivy-sha256 <sha256> --likelihood
+```
+
+Without a container image, assess a file or folder directly with `--path`:
+
+```bash
+oss-intake --path ./vendor-app-2.4.1.jar --repo owner/app --out ./reports   # JAR, WAR, EAR or binary
+oss-intake --path ./requirements.txt --repo owner/app --release-tag v1.4.0 --out ./reports
+oss-intake --path ./renv.lock --repo owner/app --release-tag v1.4.0 --out ./reports
+```
+
+A JAR, WAR, EAR or binary is scanned as built artifacts (Trivy `rootfs`, Grype `dir:`), and a version in its
+file name is tried as the release tag. Lockfiles the scanners understand (Python, npm, Maven, Go, Rust, PHP,
+Ruby, .NET) are scanned with Trivy `fs`. An R `renv.lock` is read by oss-intake and checked against OSV's CRAN
+advisories, since neither scanner reads it; packages from Bioconductor, GitHub or local sources are listed as
+not checked. A folder is scanned as built artifacts; for a source checkout, pass its lockfile. Release lag needs
+the project's release: `--repo` with `--release-tag`, or `--release-date`.
+
+All inputs are validated before any scanner runs. The image must carry an explicit tag or digest.
+
+| Option | Purpose |
+|---|---|
+| `--image` | Image with explicit tag or digest |
+| `--path` | A JAR, WAR, binary, folder, lockfile or `renv.lock` instead of an image |
+| `--reachability`, `--govulncheck-path` | Check Go binaries with govulncheck (see Go reachability) |
+| `--repo` | GitHub `owner/name` (a full GitHub URL is accepted) |
+| `--image-src remote` | Pull from the registry without Docker installed (Trivy `--image-src remote`, Grype `registry:`) |
+| `--platform` | Image platform for both scanners (default `linux/amd64`, so Apple Silicon scans the same variant as a server); `''` uses scanner defaults |
+| `--scanners` | `auto` (default: Trivy and OSV, plus Grype if found) or a list such as `trivy,grype,osv` |
+| `--trivy-version`, `--grype-version` | Required scanner version; the run fails on mismatch |
+| `--trivy-sha256`, `--grype-sha256` | Expected SHA-256 of the executable |
+| `--trivy-cosign-bundle`, `--grype-cosign-bundle` | Verify a Sigstore bundle with cosign (cosign must be on PATH) |
+| `--trivy-arg`, `--grype-arg` | Pass extra arguments, e.g. `--trivy-arg=--db-repository=ghcr.io/aquasecurity/trivy-db:2` |
+| `--from-trivy-json`, `--from-grype-json` | Use an existing JSON report instead of running the scanner |
+| `--release-tag`, `--release-date` | Set the release the image corresponds to, when tags do not match |
+| `--grace-days` | A fix must predate the release by this many days to count as missed (default 14) |
+| `--unshipped-days` | Days a fix must be public, with no newer release, to count as unshipped (default 90) |
+| `--as-of` | Fix the assessment date for reproducible reports |
+| `--min-severity` | Drop findings below a severity |
+| `--formats` | Any of `csv,md,json,html` (default all) |
+| `--offline` | No network enrichment (OSV, deps.dev, GitHub, Scorecard, KEV, EPSS, exploit sources) |
+| `--no-epss`, `--no-kev`, `--no-scorecard`, `--no-fix-dates`, `--no-exploits` | Skip one enrichment source |
+| `--likelihood`, `--likelihood-config FILE` | Add the 5x5 likelihood heuristic, with optional custom rules |
+| `--fail-on-likelihood N` | Exit code 3 when the suggestion is N or higher, for pipelines |
+| `--sbom` | Also write a CycloneDX SBOM to `raw/` |
+
+Other commands: `oss-intake doctor` (scanner paths, versions, hashes, known-bad status) and
+`oss-intake verify` (check a download against a checksums file, a hash or a cosign bundle).
+
+Exit codes: `0` success, `1` error (including any integrity failure), `2` invalid input, `3` likelihood
+threshold reached.
+
+`GITHUB_TOKEN` is optional. It is only sent to `api.github.com`, and it is never logged or written to reports.
+
+## How release lag is measured
+
+For each finding with a fix, `oss-intake` picks the nearest fixed version above the installed one (so a fix on
+an older branch is not counted for a newer one) and looks up when that version was published.
+
+| Metric | Meaning |
+|---|---|
+| Fix exists upstream | A fixed version of the dependency is known |
+| **Fix existed before release** | The fixed version was published at least `--grace-days` (14) days before the project's release: the project could reasonably have shipped it |
+| Fix within grace period | Published in the 14 days before release; shown but not counted as missed |
+| **Unshipped** | Forward-looking: the fix has been public for `--unshipped-days` (90) or more and the scanned release is still the project's latest |
+| Likely already fixed | Installed version equals a listed fix apart from a build label such as `.jre11`; flagged and excluded from lag |
+| Fix published after release | The fix arrived later; this is normal lag for the next release |
+| Days a fix has been available | Assessment date minus the fixed version's publish date |
+| CVE published before release | Secondary signal. A CVE can be public before any fix exists, so this overstates lag on its own |
+
+Fix dates come from deps.dev for language packages, from Packagist for PHP Composer packages, falling back to the GitHub release date for Go modules
+hosted on GitHub that deps.dev does not index. For Debian packages they come from the Debian security advisory
+that shipped the fix (DSA or DLA, by the scanner's advisory ID or the exact fixed version), dated from the Debian
+security tracker's advisory lists, with OSV as a fallback. Fixes that shipped without an advisory are dated from the
+Debian point release (13.6 and so on) that included the fixed version, from the suite's ChangeLog; fixes still in
+proposed-updates stay unknown, with a note. For Ubuntu packages they come from the Ubuntu
+Security Notice (USN) that fixed the CVE in that release and source package at that version, found through OSV;
+failing that, from Launchpad's publishing history: when that exact version was first published to the release in
+the Release, Security or Updates pocket.
+For RHEL and UBI packages they come from the Red Hat advisory (RHSA) that Trivy reports, dated from Red Hat's
+CSAF document. For Alpine packages they come from the aports commit history on the image's release branch: a commit naming the
+CVE, or the fixed version for a new upstream release (set `GITHUB_TOKEN`, one request per package).
+For the Go standard library they come from the Go release history (go.dev/doc/devel/release).
+Packages with no dated source yet, currently Amazon Linux and runtimes detected only from a binary, are counted as
+"fix date unknown" rather than guessed. The `fix_date_source` column in findings.csv shows where each date came from.
+
+## Example output
+
+Taken from the synthetic test fixtures (`tests/fixtures`, fictional project `example/webapp`) so it shows
+the format, not a judgement of any real project:
+
+```text
+findings=7 critical=2 high=4 with_fix=6 fix_before_release=3 fix_date_unknown=1 likelihood=5(Almost certain)
+```
+
+| ID | Severity | Package | Installed | Fix | Fix before release | Days fix available |
+|---|---|---|---|---|---|---|
+| CVE-2099-0001 | CRITICAL | org.springframework:spring-web | 6.1.10 | 6.1.12 | yes | 290 |
+| CVE-2099-0006 | CRITICAL | com.fasterxml.jackson.core:jackson-databind | 2.17.0 | 2.17.3 | no | 113 |
+| CVE-2099-0003 | HIGH | io.netty:netty-codec-http | 4.1.100.Final | 4.1.108.Final | yes | 244 |
+| CVE-2099-0004 | HIGH | org.springframework:spring-web | 6.1.10 | none | no fix | n/a |
+| CVE-2099-1000 | MEDIUM | libc6 | 2.39-0ubuntu8.4 | 2.39-0ubuntu8.5 | unknown | n/a |
+
+The summary also covers scope (scanner versions, database dates, hash verification), project health,
+agreement between sources and any warnings. See [docs/validation.md](docs/validation.md) for checking the
+tool against a real public image.
+
+## Exploit availability and advisory conditions
+
+Each finding gets the strongest public exploit evidence found: known exploited (CISA KEV), weaponised (a
+Metasploit module or Nuclei template), public (Exploit-DB), proof of concept (GitHub repositories only, which
+are noisy and sometimes malicious), or none indexed. "None indexed" means none was found in those sources, not
+that none exists; when a source cannot be reached the finding is "not checked" instead. The `conditions`
+column quotes the advisory's own statement of when the finding applies (for example "only if the application
+uses XsltView"), word for word, so the assessor can check it against the deployment.
+
+## Go reachability (optional)
+
+With `--reachability`, Go binaries in the scan are checked with Go's official
+[govulncheck](https://go.dev/doc/security/vuln/) in binary mode, which reports whether a vulnerable function is
+actually linked into the binary. Install it yourself (`go install golang.org/x/vuln/cmd/govulncheck@v1.1.4`);
+oss-intake never downloads it. For an image, the binaries are copied out with Docker (`docker create` and
+`docker cp`) or `crane export`. A finding whose vulnerable functions are absent from every binary it was seen
+in is marked "not reachable" and set aside in triage, with the govulncheck ID as the reason; one whose function
+is present is marked "reachable". Counts and likelihood do not change: the vulnerable version is still shipped.
+This covers Go only; for other languages the advisory conditions are the assessor's guide.
+
+## Suggested triage
+
+Each finding is placed in one group, with its reason, as a reading order for the engineer: **Act now** (a known
+malicious package, CISA KEV, or a Metasploit or Nuclei exploit), **Review** (an Exploit-DB exploit, EPSS 0.1 or more, or a critical whose
+advisory states no conditions), **Check conditions** (the advisory says when it applies; confirm against the
+deployment), **Routine** (none of these) and **Set aside** (only with evidence: a kernel header package, the
+installed version already matches a fix, or govulncheck shows the vulnerable function is not in the binary). No group says a finding carries no risk.
+
+## Likelihood heuristic
+
+Off by default. With `--likelihood`, the first matching rule wins:
+
+| Level | Default rule |
+|---|---|
+| 5 Almost certain | A CISA KEV vulnerability has a fix the project has not shipped |
+| 4 Likely | A finding with an upstream fix has a ready-to-use exploit (Metasploit module or Nuclei template) |
+| 4 Likely | A finding with an upstream fix has an EPSS score of 0.5 or more |
+| 4 Likely | A critical fix existed before release, and the project has not released for 180 days, is archived or scores under 4 on Scorecard |
+| 4 Likely | A critical fix is unshipped and the project has not released for 180 days |
+| 3 Possible | A finding with an upstream fix has an EPSS score of 0.1 or more |
+| 3 Possible | A finding with an upstream fix has a published exploit (Exploit-DB) |
+| 3 Possible | A critical fix, or 5 or more high fixes, existed before release |
+| 3 Possible | A critical fix, or 10 or more high fixes, are unshipped |
+| 2 Unlikely | Any high or critical finding has an upstream fix |
+| 1 Rare | None of the above |
+
+Unknown signals (no Scorecard score, say) never trigger a rule. To use your own rules, copy
+`DEFAULT_CONFIG` from [likelihood.py](src/oss_intake/likelihood.py) into a JSON file and pass
+`--likelihood-config`. The available metrics are `critical_fix_at_release`, `high_fix_at_release`,
+`critical_with_fix`, `high_with_fix`, `critical_fix_unshipped`, `high_fix_unshipped`, `kev_with_fix`, `max_epss_with_fix`, `max_days_fix_available`, `days_since_latest_release`,
+`archived`, `scorecard_score` and `fix_date_unknown`.
+
+## Limitations
+
+- Results depend on the scanners' vulnerability databases and drift as those databases update. The report
+  records scanner and database versions so a result can be reproduced or explained.
+- Trivy and Grype detect packages independently, so their disagreement is informative. OSV is queried with
+  Trivy's package list, so it is an independent database check, not an independent detector.
+- Severity is the highest any source reported, which is conservative. Per-source severities are in the CSV.
+- Kernel CVEs reported against kernel header packages (`linux-libc-dev` and similar) are excluded from lag and
+  likelihood, because a container uses the host's kernel. They stay in findings.csv with a note; assess the host
+  kernel separately. Use `--include-kernel-headers` to count them.
+- Version comparison is ecosystem-agnostic and approximate. It only affects which fix date is used. Build
+  labels (`.jre11`, `-jre`, `-android`) are ignored when comparing.
+- Scanners can read a JAR's version without its build label and report an already-fixed build as vulnerable
+  (seen with `mssql-jdbc 12.10.2.jre11`). These rows are kept, marked in the `note` column and excluded from lag.
+  OSV inherits the same mistake because it is queried with the scanner's version.
+- The OpenSSF Scorecard API only covers repositories in its scheduled dataset. "Not scored" is not a
+  negative signal.
+- Release matching expects GitHub releases whose tags resemble the image tag (`1.2.3`, `v1.2.3`,
+  `name-1.2.3`, `release-1.2.3`), and also tries the tag without a variant suffix (`2.528-jdk21` matches
+  `jenkins-2.528`). If nothing matches, lag metrics are not computed rather than measured against the
+  wrong release. Use `--release-tag` or `--release-date` in that case. Failing both, the image's build date is
+  used and labelled "image build date": lag then means "fixes that existed when the image was built"
+  (disable with `--no-image-date`).
+- Fix dates are unavailable for Amazon Linux and for runtimes found only in binaries. When more than half of the fixes lack
+  a date, the likelihood suggestion is marked low confidence: read it as "not enough evidence", not "low risk".
+- Only GitHub-hosted projects get health signals in this version.
+- Trivy does not catalogue installed R (CRAN) packages, so R libraries inside an image are not assessed.
+- Runtimes detected from binaries (`binary` in the coverage table) have no package registry to date fixes
+  from, so they always show as "fix date unknown".
+
+Planned work is in [BACKLOG.md](BACKLOG.md).
+
+## Licence
+
+Apache License 2.0. See [LICENSE](LICENSE).