Heisenberg Dependency Health Check is a GitHub Action that inspects only the new or modified dependencies introduced in a pull request. It analyses lockfiles or manifest changes, gathers health and risk signals from deps.dev and other heuristics, and posts a detailed dependency health report directly on the pull request. It highlights suspicious, low-quality, or unusually fresh packages before they reach your main branch.
Overview
Modern supply-chain attacks increasingly rely on introducing malicious or low-trust dependencies through everyday development workflows. Traditional scanners often run periodically and focus on known vulnerabilities, which miss early indicators of risk. Heisenberg takes a different approach: it hooks directly into the pull request, detects which packages were added or updated, and reviews them in isolation. Running at merge time, it gives reviewers actionable risk signals exactly when decisions are made.
The tool is ecosystem-agnostic and supports Python, JavaScript, and Go dependency formats. It can detect unusual publish timings, maintenance red flags, popularity issues, suspicious scripts, and other patterns associated with supply-chain compromise. If configured, it can also label or block pull requests that exceed risk thresholds.
Features
- Delta-based scanning: evaluates only new or changed dependencies rather than rescanning the entire dependency graph.
- Multi-ecosystem support: works with
poetry.lock,requirements.txt,uv.lock,package-lock.json,yarn.lockandgo.mod. - Risk and health signals: pulls advisories, maintenance metrics, popularity data, dependents, and incredibly fresh publishes that may indicate rushed or suspicious releases.
- npm script checks: highlights post-install script behaviours that attackers frequently abuse.
- Pull request reporting: posts a structured dependency health comment with links to package intelligence sources.
- Policy controls: can add a security review label or fail the job if risky packages are introduced.
Installation
The following workflow is taken directly from the Heisenberg documentation and should be placed inside .github/workflows/ in your repository. It monitors standard dependency files and runs the action whenever one of them changes.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
name: Heisenberg Health Check on: pull_request: paths: - "**/poetry.lock" - "**/uv.lock" - "**/package-lock.json" - "**/yarn.lock" - "**/requirements.txt" - "**/go.mod" permissions: contents: read pull-requests: write issues: write jobs: deps-health: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Detect changed manifest id: detect run: | git fetch origin ${{ github.base_ref }} --depth=1 LOCK_PATH=$(git diff --name-only origin/${{ github.base_ref }} | \ grep -E 'poetry.lock$|uv.lock$|package-lock.json$|yarn.lock$|requirements.txt$|go.mod$' | head -n1 || true) echo "lock_path=$LOCK_PATH" >> $GITHUB_OUTPUT - name: Heisenberg Dependency Health Check uses: AppOmni-Labs/heisenberg-ssc-gha@v1 with: package_file: ${{ steps.detect.outputs.lock_path }} |
Usage
Once the workflow is active, the process is automatic:
- A pull request modifies a dependency manifest.
- The workflow detects the change and hands the specific file to Heisenberg.
- Heisenberg evaluates only the added or modified packages.
- A health report appears as a comment on the pull request.
- Optional: risky changes can trigger a label or cause the job to fail, blocking the merge.
Teams using additional GitHub Action hardening tools, such as Claws, can pair Heisenberg with workflow linting to reduce risks from both automated misuse and compromised dependencies.
Attack Scenario
Objective: demonstrate how a hostile dependency attempt would be detected during a realistic development flow.
- Set up a demo repository with the Heisenberg workflow enabled.
- Add or bump a dependency known for suspicious activity, poor maintenance, or very recent publishes.
- Open a pull request as if performing a routine update.
- Heisenberg evaluates only the changed dependency and posts a health report highlighting all relevant concerns.
- Point stakeholders to the flagged signals as evidence of supply-chain risk and why automated guardrails matter.
This adversarial modelling pairs well with internal reviews using Darknet’s write-ups on automation abuse, such as Weaponizing Dependabot, helping teams understand how automated tooling can be exploited without proper controls.
Red Team Relevance
Although Heisenberg is built for defenders, red teams can use it to:
- Identify weak or unvetted dependency update practices in target environments.
- Model realistic compromise paths that depend on dependency injection or typosquatting.
- Show how quickly risk would be caught if the organisation had Heisenberg or similar controls in place.
It also pairs naturally with supply-chain reconnaissance tools and GitHub workflow analysis techniques. For example, secret-exposure tools like Veles excel at key detection, while OAuth-abuse research such as GitPhish highlights broader risks inside CI/CD ecosystems.
Detection and Mitigation
- Restrict dependency changes to pull requests so that Heisenberg has complete visibility.
- Centralise reports so security teams can see patterns across repositories.
- Harden GitHub workflows to prevent bypass paths; tools like Claws help enforce safe workflow practices.
- Threat model dependency automation using lessons from Darknet’s coverage of Dependabot exploitation and broader CI/CD abuse.
- Introduce routine chaos tests using intentionally risky but harmless packages to ensure detection logic remains effective.
Comparison
Heisenberg differs from scheduled composition scanners by focusing on changes rather than the full dependency tree. It gives teams real-time merge-time intelligence without slowing developer workflows. Compared to broader GitHub workflow hardening tools, it focuses specifically on package-level supply-chain risk, making it a complementary part of a complete CI/CD security posture.
Conclusion
Heisenberg Dependency Health Check provides a high-signal, low-friction control to catch risky dependencies during code review. By focusing strictly on the packages developers are adding or updating, it keeps supply-chain risk visible without overwhelming teams with noise. It is a practical upgrade for any team that relies heavily on open-source packages and wants to prevent supply-chain compromise before it enters the build pipeline.
You can read more or download Heisenberg Dependency Health Check here: https://github.com/AppOmni-Labs/heisenberg-ssc-gha
Leave a Reply