Skip to content

About

GitHub Action: find dependencies affected by security advisories in limbo, published but not yet in the databases scanners read

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Latest commit

 

History

52 Commits

Folders and files

Repository files navigation

Limbowatch

Release Self-test GitHub Marketplace License

Find dependencies affected by security advisories in limbo: published by their maintainers on GitHub, but not yet reviewed into the GitHub Advisory Database or OSV, so Dependabot, npm audit, OSV-Scanner and most other scanners can't see them yet. In October 2026, about 1 in 6 advisories behind 15 popular projects was in limbo, and the median wait for review was 23 days (report).

The action reads your lockfiles, checks every package against the live limbo feed, annotates each finding on its lockfile line, writes a job summary and reports, and can fail the build.

Alpha. Release 0.1.0a22. Options and formats may change before 0.1.0.

Usage

on: [push, pull_request]
permissions:
  contents: read
jobs:
  limbowatch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: limbowatch/limbowatch-action@v0.1.0a22
        with:
          fail-on: high

With GitHub code scanning (public repos, or private ones with GitHub Code Security):

permissions:
  contents: read
  security-events: write   # for the SARIF upload
  actions: read            # the upload action needs it in private repos
steps:
  - uses: actions/checkout@v4
  - uses: limbowatch/limbowatch-action@v0.1.0a22
    with:
      fail-on: high
      sarif: limbowatch.sarif
  - if: always()
    uses: github/codeql-action/upload-sarif@v4
    with: { sarif_file: limbowatch.sarif, category: limbowatch }

Keep the reports, or act on the result in later steps:

  - uses: limbowatch/limbowatch-action@v0.1.0a22
    id: limbo
    with: { fail-on: none }
  - if: steps.limbo.outputs.findings != '0'
    uses: actions/upload-artifact@v4
    with: { name: limbowatch-report, path: limbowatch-report/ }

Keep one issue per finding up to date in a private repo (opened, commented on as the advisory moves, closed when you upgrade), with the job's own token. Issues are written on a push to the default branch, a schedule or a manual run (never from a pull request), never in a public repo, and at most 50 new ones a run. The concurrency group keeps two runs from overlapping: GitHub lists a new issue a few seconds late.

on: { push: { branches: [main] }, schedule: [{ cron: "17 6 * * *" }] }
permissions: { contents: read, issues: write }
concurrency: limbowatch
jobs:
  limbowatch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: limbowatch/limbowatch-action@v0.1.0a22
        with: { fail-on: none, issues: github }

Gitea and Forgejo Actions: uses: https://github.com/limbowatch/limbowatch-action@v0.1.0a22. With issues: gitea and a LIMBOWATCH_ISSUES_TOKEN secret, it opens and updates one issue per finding on a push to the default branch, a schedule or a manual run (never in a public repo). The token is never sent over plain http:// to another machine: if your Gitea or Forgejo is served only over http (GITHUB_SERVER_URL is http://… and not localhost), the step stops and says so; set LIMBOWATCH_ALLOW_INSECURE_HTTP: "1" in the step's env to send it anyway, readable to anyone on that network.

How it runs

On a Linux runner with Docker, it runs the Limbowatch image, pinned by digest and attested by the Limbowatch repository. On macOS or Windows, or when the job runs in a container, it installs Limbowatch with pip from the same release (Python 3.12 or later, e.g. actions/setup-python), every dependency checked against the hashes in requirements.txt, and OSV-Scanner checked against its SHA-256 sums. install: auto | image | python picks one explicitly.

Exit codes: 0 passed, 1 a finding meets fail-on, 2 the scan couldn't run. allow-failure: true passes the step with a warning when findings meet fail-on; a scan that couldn't run still fails.

Security and data

The action runs in your job; it doesn't upload files or source code.

  • Reads your lockfiles and SBOMs (OSV-Scanner, offline) and, for C/C++, the build files that declare upstream sources.
  • Sends package names and versions to public services (deps.dev, Maven Central, GitHub, CVE Services, OSV) to find out whether a dependency is affected. limbo.watch learns nothing: the feed is downloaded whole. With extra-args: --no-upstream --no-resolve-maven, the scan contacts limbo.watch and nothing else, at the cost of the checks those lookups make.
  • Needs no secrets and only permissions: contents: read. It gets a token only when issues is set.
  • Verify it: pin uses: to a commit SHA; the default image is pinned by digest and attested (gh attestation verify oci://ghcr.io/limbowatch/limbowatch:<tag> --owner limbowatch).
  • Isolated: the image sees the checkout read-only and never the runner's temp directory, where GITHUB_ENV and GITHUB_PATH live. It runs with a read-only root filesystem, no capabilities and no new privileges, and workflow commands are off while it prints. It writes only to directories of its own, and the action copies regular files out of them: never a symlink or a dotfile, never over a file git tracks. So even a compromised image can't change what the job's later steps run. The one place in the checkout it can write is the reports directory: files that extra-args writes (--state, --audit-log, more -o) go there, directly in it, if it holds no files from the repository. It sees nothing outside the checkout, so an --sbom file must be inside it.
  • Record it: extra-args: --audit-log limbowatch-report/network.jsonl writes every URL the scan calls and every request body (method, status, time; never a secret) to a file uploaded with the reports; --show-network prints them in the log. Every request is https only, redirects included.
  • Lock it down: check out only the dependency files (sparse checkout), or pass your own SBOM with extra-args: --sbom <file>; run it in a job of its own; allow only the hosts you chose with an egress filter. Strictest, without this action: the sealed workflow hands only the dependency files to a job with no permissions and runs the image there with no network (what it costs).

Every host, what it receives and the option that turns it off: Security and data.

Inputs

Input Default What it does
path . Project directory to scan.
fail-on low Fail for findings at or above this severity: critical, high, medium, low, none.
fail-on-unknown true Also fail for findings with no severity.
allow-failure false Pass the step with a warning when findings meet fail-on.
sarif Write SARIF to this file, for GitHub code scanning.
annotations true Annotate each finding on its lockfile line in the pull request.
reports limbowatch-report Directory for report.json, report.md, report.html, report.sarif, report.csv and cyclonedx.json; empty for none.
issues github (needs permissions: issues: write) or gitea (Gitea or Forgejo): open and update issues in this repo on a push to the default branch, a schedule or a manual run. Never in a public repo unless extra-args has --issues-public.
issues-token Token that can write issues here (pass a secret); for github, the job's token by default. A personal token's user needs write access: GitHub drops a new issue's labels otherwise, so nothing is opened and the step says why.
extra-args More limbowatch scan options.
install auto image, python or auto.
image the release's image The Limbowatch image, pinned by digest.
osv-scanner-version 2.7.1 OSV-Scanner release for install: python.
limbowatch-source GitHub archives Where <ref>.tar.gz source archives are served, for install: python.
limbowatch-ref v0.1.0a22 Limbowatch release tag to install with install: python.

Outputs

Output Meaning
findings Findings that aren't accepted (ignored).
failing Findings at or above fail-on.
failed "true" if the scan failed the fail-on gate.
report Path of the JSON report (schema_version 1), when reports is set.

More

Advisory data from published GitHub repository security advisories and the GitHub Advisory Database (CC BY 4.0). Code: Apache-2.0.

About

GitHub Action: find dependencies affected by security advisories in limbo, published but not yet in the databases scanners read

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages