Key takeaways:
- Heisenberg is an open source tool that automatically scans pull requests (PRs) to flag risky or newly published dependencies before they merge.
- It enables Software Bills of Materials (SBOMs) to be used as actionable defense, detecting supply chain threats early without slowing development.
- Developers can run it as a Command Line Interface (CLI) or GitHub Action (GHA) to instantly identify risky packages and strengthen their workflows.
Over the years, software supply chain security went from “occasional incident” to a recurring headline. Recently, attackers phished well known maintainers and pushed malicious releases of debug and chalk packages, briefly poisoning projects with billions of weekly downloads. Soon after, a fresh wave tied to the S1ngularity/Nx actors spread the first-of-its-kind npm worm, Shai Hulud, that self-propagated via new releases and credential theft.
Cute names aside, a ‘named’ attack campaign typically marks large-scale or high-impact incidents. If parts of that sound familiar, it’s because we just lived through the Nx compromise in late August, where attackers abused GitHub Actions to publish trojanized packages for several hours. It’s starting to feel like Groundhog Day for the ecosystem.
There’s no silver bullet, but there are practical ways to detect and block risky changes before they land into your main branch. For us, the breakthrough came when we stopped treating Software Bill of Materials (SBOMs) as static paperwork and started using them as actionable living data.
Before we talk about how we use SBOMs, let’s take a step back to the moment a dependency enters the codebase. What actually happens at the gate (if there is one)?
A new tool to maintaining security and velocity
Most organizations run on other people’s code, which is the tradeoff of modern software development: velocity in exchange for dependence. The challenge isn’t whether to use third-party packages, but rather how to approve them quickly without slowing development or introducing future risks.
Imagine a team proposing the usage of a new library. Product wants to move fast. Security wants assurance. Too often, the process swings between two extremes: a slow, manual review that bottlenecks progress, or a quick approval (or no review at all) if no Common Vulnerabilities and Exposures (CVEs) appear in the security composition (SCA) scan. The first delays releases without clear results; the second ignores real-world risks like rushed new versions, abandoned projects, unverified maintainers, and compromised packages.
The reality is messier when the change is not a new dependency at all but a version bump. Running the same heavyweight process or skipping it entirely is a cost no team can afford. As a result, most organizations quietly approve these updates and hope they won’t cause trouble later.
We, at AppOmni, wanted a gate that didn’t feel like one: an automated, lightweight check that focuses on what changed in the pull request (PR).
If a dependency is new, unhealthy, flagged by an advisory, or lacks verifiable history, it should surface in the conversation where developers are already working: in the PR. And when the ecosystem is hit by a new campaign and everyone asks “are we affected?”, we want answers from our SBOMs within minutes, not after days of manual digging and hunting.
Heisenberg fills that gap.
From inventory to instrument panel: Turning SBOMs into a security control
It’s hard to get excited about SBOMs. They’ve been around for a while, but their importance came into focus after Executive Order 14028 required software vendors to provide SBOMs with any software sold to the US government.
On paper, SBOMs sounded like a silver bullet to improve software supply chain security: a standardized way to see every package and version your software depends on. In practice, static SBOMs often feel like a security theater. As Nietzsche quipped about the abyss: stare into an SBOM long enough, and it seems to stare back. They often become endless paperwork for compliance teams or a visibility tool that’s useful but not actionable for security engineers. We could see what was in the box, but not whether it was healthy, secure, or even legitimate.
That changed when we realized an SBOM is a time-series of dependency states we can query forward and backward. Looking forward, you can gate new or updated packages in pull requests as they enter your supply chain based on risk signals. Looking backward, we can ask “where do we already carry this thing?” when an advisory dropped.
Once we started treating SBOMs this way, they went from paperwork to the instrument panel.
The one who knocks: Meet Heisenberg, designed to protect your codebase
The solution needed to be precise, automated, and ruthless about catching bad ingredients. We called it Heisenberg, named after the alias of Walter White (a supply chain expert) in Breaking Bad. Heisenberg is a small toolkit and GitHub Action that turns dependency changes into decisions automatically in PRs, and on demand when an incident happens.
At a glance, Heisenberg does two things well: forward detection at PR time (gating new/updated packages by age, health, and security advisories) and backward search when news breaks (answering “are we already running this?” across SBOMs in seconds).
Let’s take a deeper look at the toolkit. Heisenberg ships with four Command Line Interface (CLI) modes.
- sbom: This simply generates the per-repo SBOMs. It creates a stripped-down version of SBOM (per repo or multiple repos) that becomes our query surface. It’s intentionally boring because boring is easy to parse, diff, and automate. This is mostly a background mode that is used by other modes, but it can also be handy during investigations.
- check: This is the individual package deep dive. Backed by the deps.dev API, check pulls in project metadata (scorecard/maintenance, stars/forks, dependents, advisories), detects fresh publishes (<24h), and prints cross-reference links (deps.dev, Snyk Advisor, Socket). Additionally, It flags deprecated/inactive packages. If deps.dev lacks data, it falls back to the GitHub API and the npm/PyPI registries. Under the hood, we also compute a Custom Health Score that softens extremes by blending popularity, maintenance, dependents, and vuln signals, putting the most weight into security of the project. Finally, for npm packages, it can detect if there are postinstall scripts, which could be an indication of potential malware.
- bulk: This fans out checks across all our SBOMs. The bulk runner parallelizes calls to check over every SBOM row and writes a consolidated report with fields like health score, security advisories, deprecated, and others. Think of it as our portfolio scan that creates visibility into our overall software supply chain health.
- analyze: Helps us find package(s) across our SBOM(s) fast. Think of it as our “are we affected?” button. Feed it a comma-separated list or a text file of package names, and it returns the full SBOM row(s) where they appear.
The bump in the road: Catching risky dependencies before they merge
Every supply chain incident starts the same: a small change lands quietly in a dependency manifest. Hence, we need a way to proactively detect this change. That’s where Heisenberg GitHub Action (GHA) comes in.
When a pull request modifies a lockfile, the action pulls the base branch’s manifest, computes a diff, and hands only the new or changed packages to Heisenberg CLI. Each candidate gets a quick review: We fetch health and maintenance signals from deps.dev, check for known advisories, detect fresh publishes (under 24 hours old), and on npm we also detect the presence of lifecycle scripts like postinstall. The workflow puts together a short Markdown report and posts it to the PR, including: package@version, the signals we detected, and cross-references (deps.dev / Snyk Advisor / Socket) so reviewers can go deeper with just a few clicks and no extra research.
This approach directly addresses the kinds of attacks we’ve seen in the wild. In debug/chalk style compromises, malicious versions appeared suddenly in popular packages. Those fresh, untested releases are exactly what our GHA flags. If a PR tries to pull one in (manually or via renovate-bot), the action will flag the fresh publish and the lack of healthy signals, fail the job, and add a security review label before the version reaches the main branch.
In a Shai Hulud style worm, attackers abused automation and install-time behavior to spread. We deliberately surface packages that define postinstall scripts and alert on those so humans can review intent. That’s a speed bump for potential worms/malware and a spotlight for anything that shouldn’t be there.
The result isn’t another ticket queue but a lightweight, deterministic gate that scales with your velocity. Developers still move quickly, but risky changes don’t slip in unnoticed.
There’s always debate about timing: Should you wait a day, a week, or never update at all? The real answer depends on your risk tolerance and release cadence. With proactive detection in place, you set your pace instead of being forced into one. Need fast turnarounds? Keep the quarantine short and trust the signals. Running critical infrastructure? Extend the window and tighten the rules on health and provenance. Heisenberg lets you configure it to fit your needs.
“Say My Name”: How Heisenberg works
The point of all this is to stop bad packages before they merge and to find them fast when the news breaks. Here’s what that looks like on an ordinary day, and on a bad one.
Preventive: The PR that tries to sneak in a risky dependency
Let’s say a developer is moving fast, or maybe renovate-bot just pushed an automated update. They trigger a PR, trying to pull in a dependency. Heisenberg doesn’t stop velocity; it makes it deterministic. When the lockfile changes, the action immediately hands the new and changed packages off to the CLI. If that dependency fails policy, is brand new (published <24 hours ago), or the health signals are missing, the PR instantly fails.
The result looks like this:
Behind the scenes, the action is running the following command:
python heisenberg_health_check.py -mgmt npm -pkg puppeteer -v 22.10.0If the version is brand new (published within the last 24 hours), or the health score is unknown/below threshold, or there are security advisories, the job fails and adds a security review label. That keeps the “Squash and Merge” button from becoming a “Scramble and Regret” button.
(For context: the September 8 compromise of debug and chalk came from a phished maintainer account and pushed malicious releases to billions-of-downloads packages.This is also the kind of “brand-new but dangerous” change this gate is meant to catch.)
Investigative: The morning after a headline
Now, let’s look at a bad day. A named campaign drops like Shai Hulud, the self-replicating npm worm. The reports are flying, and you need to know now whether any of those affected packages are running in your environment. You don’t have a week.
The power of the instrument panel kicks in here.
If the news broke about one single bad package, you could search your GitHub organization and find it eventually. But in a major incident like Shai Hulud, you’re dealing with a list of ten, fifty, or even hundreds of compromised packages. Searching for that across dozens of repositories is a mess.
You take the list of compromised packages and feed it into the analyze mode. Since you already generated SBOMs for every repo (heisenberg sbom –all -o all_repos_sboms.csv), Heisenberg interrogates that entire dataset in parallel.
heisenberg analyze -sbom all_repos_sbom.csv -file affected_pkgs.txt
It answers in seconds if there is a match in any of the repos. In less than a minute, you have your answer. It’s the difference between mass panic and having an immediate, precise list of every repo that needs remediation. That quick analyze run gives you the peace of mind, or the precise hit list, you need to move from “What do we do?” to “Fix these five repos.”
We’ve taken the guesswork out of the formula. Now you can control the ingredients (something Heisenberg would say).
Supply chain resilience with Heisenberg
The point of Heisenberg is simple: stop bad packages before they merge, and find them fast when the news breaks.
We’re adopting this tool at AppOmni to prevent risk, and we’d love for you to try it out. The code lives at https://github.com/AppOmni-Labs/heisenberg-ssc-health-check, and an installable GHA lives at https://github.com/AppOmni-Labs/heisenberg-ssc-gha.
Dependency attacks aren’t slowing down. With tools like Heisenberg, we’re not the danger; we’re the ones detecting it. Try it out for yourself and help secure your supply chain. We welcome your feedback.
Together, we can strengthen the open source supply chain.
Heisenberg is available today under an open source license. Developers can download the repo and add Heisenberg to their workflow. Security teams can integrate the GitHub Action to protect their codebase against risky packages. Contributors can help expand Heisenberg by adding new ecosystem support or integrations.