GitHub SBOM Generator

A Python tool that generates Software Bill of Materials (SBOM) files for GitHub repositories using GitHub's Dependency Graph API. This tool efficiently creates SPDX-format SBOMs with vulnerability information for entire organizations.

Features

• 🚀 Fast & Efficient: Uses GitHub's pre-analyzed dependency graphs instead of parsing files manually
• 📊 Comprehensive: Includes direct dependencies, transitive dependencies, and vulnerability data
• 🔒 Security-Focused: Integrates Dependabot alerts and security advisories
• 📄 Standards-Compliant: Generates SPDX 2.3 format SBOMs
• 🏢 Batch Processing: Process entire organizations or repository lists
• 🛡️ Multi-Ecosystem: Supports npm, pip, Maven, Go, Ruby, and more automatically

Prerequisites

• Python 3.6 or higher
• GitHub Personal Access Token with appropriate permissions
• requests library

Installation

1. Clone this repository:

git clone <repository-url>
cd github-sbom-generator

2. Install required dependencies:

pip install requests

Setup

1. Create a GitHub Personal Access Token

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token (classic)"
3. Select the following scopes:
   • repo (for private repositories)
   • public_repo (for public repositories)
   • security_events (for vulnerability information)
4. Copy the generated token

2. Set Environment Variable

export GITHUB_TOKEN="your_github_personal_access_token"

Or pass it directly using the --token parameter.

3. Create Repository List File

Create a text file (e.g., repos.txt) with one repository name per line:

webapp-frontend
api-backend
mobile-app
data-pipeline
infrastructure-tools
# This is a comment - lines starting with # are ignored

Usage

Basic Usage

python github_sbom_generator.py repos.txt --organization your-org-name

Advanced Options

python github_sbom_generator.py repos.txt \
    --organization your-org-name \
    --output-dir ./output \
    --token ghp_your_token_here \
    --no-vulnerabilities

Command Line Options

Option	Description	Required	Default
repo_list	Path to text file containing repository names	✅	-
--organization	GitHub organization name	✅	-
--token	GitHub personal access token	❌*	GITHUB_TOKEN env var
--output-dir	Directory to save SBOM files	❌	sboms
--no-vulnerabilities	Skip vulnerability information	❌	Include vulnerabilities

*Required via either --token parameter or GITHUB_TOKEN environment variable.

Output

The tool generates individual SBOM files for each repository in JSON format following SPDX 2.3 standards:

sboms/
├── webapp-frontend-sbom.json
├── api-backend-sbom.json
├── mobile-app-sbom.json
└── data-pipeline-sbom.json

SBOM Content

Each SBOM includes:

• Repository metadata: Name, URL, license information
• Dependencies: All direct and transitive dependencies with versions
• Package URLs (PURLs): Standard package identifiers
• Vulnerability information: Security alerts from Dependabot
• Ecosystem data: Package manager and language information

Sample SBOM Structure

{
  "spdxVersion": "SPDX-2.3",
  "dataLicense": "CC0-1.0",
  "SPDXID": "SPDXRef-DOCUMENT",
  "name": "SBOM for myorg/webapp-frontend",
  "documentNamespace": "https://github.com/myorg/webapp-frontend/sbom",
  "creationInfo": {
    "created": "2025-08-15T10:30:00Z",
    "creators": ["Tool: GitHub-Dependency-Graph", "Tool: GitHub-SBOM-Generator"]
  },
  "packages": [
    {
      "SPDXID": "SPDXRef-Package-Root",
      "name": "webapp-frontend",
      "downloadLocation": "https://github.com/myorg/webapp-frontend.git",
      "licenseDeclared": "MIT"
    },
    {
      "SPDXID": "SPDXRef-Package-1",
      "name": "react",
      "versionInfo": "18.2.0",
      "externalRefs": [
        {
          "referenceCategory": "PACKAGE-MANAGER",
          "referenceType": "purl",
          "referenceLocator": "pkg:npm/react@18.2.0"
        }
      ]
    }
  ]
}

GitHub API Endpoints Used

The tool leverages these GitHub API endpoints:

Endpoint	Purpose
/repos/{org}/{repo}	Repository metadata and license information
/repos/{org}/{repo}/dependency-graph/sbom	Pre-generated SBOM from GitHub
/repos/{org}/{repo}/dependabot/alerts	Security vulnerability alerts

Supported Ecosystems

GitHub's Dependency Graph automatically supports:

• JavaScript/Node.js: npm, Yarn
• Python: pip, pipenv, poetry
• Java: Maven, Gradle
• Go: go mod
• Ruby: RubyGems, Bundler
• PHP: Composer
• C#/.NET: NuGet
• Rust: Cargo
• And more...

Error Handling

The tool handles common scenarios gracefully:

• Private repositories: Requires appropriate token permissions
• Missing dependency graphs: Creates minimal SBOMs with repository info
• Rate limiting: Implements proper error handling and logging
• Network issues: Retries and continues with remaining repositories

Limitations

• Requires GitHub Dependency Graph to be enabled for the repository
• Private repositories need repo scope permissions
• Vulnerability information requires security_events scope
• Some older or archived repositories may not have dependency graphs

Integration Examples

CI/CD Pipeline

# GitHub Actions example
name: Generate SBOMs
on:
  schedule:
    - cron: '0 2 * * 1'  # Weekly on Monday at 2 AM

jobs:
  generate-sboms:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      - name: Install dependencies
        run: pip install requests
      - name: Generate SBOMs
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: python github_sbom_generator.py repos.txt --organization myorg
      - name: Upload SBOMs
        uses: actions/upload-artifact@v3
        with:
          name: sboms
          path: sboms/

Docker Usage

FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt github_sbom_generator.py ./
RUN pip install -r requirements.txt

ENTRYPOINT ["python", "github_sbom_generator.py"]

docker build -t sbom-generator .
docker run -v $(pwd)/repos.txt:/app/repos.txt \
           -v $(pwd)/output:/app/sboms \
           -e GITHUB_TOKEN=$GITHUB_TOKEN \
           sbom-generator repos.txt --organization myorg

Troubleshooting

Common Issues

"Dependency graph not available"

• Ensure the repository has dependency files
• Check if dependency graph is enabled in repository settings
• Verify token has appropriate permissions

"Rate limit exceeded"

• Use a personal access token instead of default GitHub Actions token
• Implement delays between requests for large repository lists

"404 Not Found"

• Verify organization and repository names are correct
• Ensure token has access to the specified repositories

Logging

Enable debug logging for troubleshooting:

import logging
logging.basicConfig(level=logging.DEBUG)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Security

• Never commit GitHub tokens to version control
• Use environment variables or secure secret management
• Regularly rotate personal access tokens
• Follow principle of least privilege for token scopes

Related Tools

• GitHub CLI - Command line tool for GitHub
• SPDX Tools - Python library for SPDX
• Syft - Generate SBOMs from container images
• CycloneDX - Alternative SBOM format