A GitHub Action to map your software supply chain using Sourcegraph and GitHub GraphQL APIs.

This tool discovers public repositories that depend on your project. It automatically generates an interactive Universal Dependency Graph (UDG) and compliance-ready SPDX snippets mapping the dependency relationship.

Rather than relying strictly on standard package manager registries (like npm or PyPI), this tool utilizes Sourcegraph's GraphQL API to execute massive-scale source code searches (e.g., C/C++ #include statements and linker pragmas).

Once a dependent repository is identified, it leverages GitHub's GraphQL API to extract rich repository metrics (Stars, Commit History, Contributors, Latest Releases, and exact Commit SHAs).

SPDX (Software Package Data Exchange) is an internationally recognized standard for communicating Software Bill of Materials (SBOM) data.

By generating an SPDX manifest for every detected consumer, you create a machine-readable declaration that "Repository A depends on Repository B."

The SPDX files generated by this tool do not point arbitrarily to the default branch. They are strictly and securely pinned to the exact commitSha where the dependency was discovered, ensuring your generated compliance manifests are immutable and protected.

GitHub utilizes these SPDX manifests through its Dependency Submission API. Submitting these files directly feeds into GitHub's native Dependents/Dependencies tabs. For projects that don't deploy to centralized registries (like many C, C++, and Fortran libraries), this is the only way to officially register your supply chain natively on GitHub.

Once the action generates your spdx_snippets/ folder, you can push them to GitHub using the GitHub CLI (gh api) or via the GitHub Dependency Submission Action.

- uses: johnwparent/dependency-audit-action@main
  with:
    root_repo: 'LLNL/zfp'
    project_name: 'zfp'
    sourcegraph_token: ${{ secrets.TOKEN }}
    github_token: ${{ secrets.GITHUB_TOKEN }}
    custom_search_string: 'find_package(zfp)'
    custom_filename: 'CMakeLists.txt'
    use_defaults: false

You can add a live badge to your project's README that links directly to your interactive dashboard. Replace YOUR_ORG and YOUR_REPO with your GitHub details assuming you've checked a dependency graph into source. Otherwise replace the ?url=<url> section of the badge url with a publically accesible URI endpoint serving your dependency graph json file.

[![Dependency Graph](https://img.shields.io/badge/dependencies-dashboard-007bff)](https://corsa-center.github.io/dashboard/explore/dependents/?url=https://raw.githubusercontent.com/YOUR_ORG/YOUR_REPO/main/dependency_graph.json)

The backend crawler can be executed locally without GitHub Actions. Ensure Python 3.10+ is installed.

Prerequisites: Install required dependencies:

python audit_dependents.py \
  --repo "LLNL/zfp" \
  --name "zfp" \
  --depth 1 \
  --out "dependency_graph.json" \
  --token "YOUR_SOURCEGRAPH_ACCESS_TOKEN" \
  --gh-token "YOUR_GITHUB_PERSONAL_ACCESS_TOKEN"

• Heuristics: This tool relies on source code scraping. It may return false positives if the project name is commonly used elsewhere.
• API Limits: Large crawls might occasionally hit API rate limits. The tool implements automatic backoff, but massive graphs may take longer to generate.
• Tools: This tool searches sourcegraph for #include and #pragma comment stanzas referencing the project name to indicate usage. This breaks down for tool usage where the tool isn't typically used as a library, i.e. CMake, Godot, clang-tidy. For tools like these, this tool will not report sufficient usage information. This is an area of current development.