GitHub Action

AI-BOM provides an official GitHub Action for automated scanning in CI/CD pipelines. It handles Python setup, AI-BOM installation, scanning, and automatic SARIF upload to GitHub Code Scanning.

Quick start

name: AI-BOM Scan
on: [push, pull_request]
permissions:
  security-events: write
  contents: read

jobs:
  ai-bom:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Scan for AI components
        uses: trusera/ai-bom@main
        with:
          format: sarif
          output: ai-bom-results.sarif
          fail-on: critical
          scan-level: deep

Action inputs

Input	Default	Description
format	sarif	Output format (sarif, cyclonedx, json, html, csv)
output	ai-bom-results.sarif	Output file path
fail-on	None	Fail the workflow if severity threshold is met (critical, high, medium, low)
scan-level	None	Set to deep for AST-based analysis
target	.	Path to scan
policy	None	Path to policy YAML file

Examples

SARIF upload to GitHub Code Scanning

This is the recommended setup. Scan results appear as annotations in pull requests and in the Security tab.

name: AI-BOM Scan
on: [push, pull_request]
permissions:
  security-events: write
  contents: read

jobs:
  ai-bom:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Scan for AI components
        uses: trusera/ai-bom@main
        with:
          format: sarif
          output: results.sarif
          fail-on: critical

CycloneDX SBOM artifact

Generate a CycloneDX SBOM and upload it as a workflow artifact:

name: AI-BOM SBOM
on: [push]

jobs:
  sbom:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate AI SBOM
        uses: trusera/ai-bom@main
        with:
          format: cyclonedx
          output: ai-bom.cdx.json

      - name: Upload SBOM artifact
        uses: actions/upload-artifact@v4
        with:
          name: ai-bom-sbom
          path: ai-bom.cdx.json

Policy gate

Use a policy file to enforce custom rules:

name: AI-BOM Policy Check
on: [pull_request]

jobs:
  policy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check AI policy
        uses: trusera/ai-bom@main
        with:
          policy: .ai-bom-policy.yml
          fail-on: high

With a policy file:

# .ai-bom-policy.yml
max_critical: 0
max_high: 5
max_risk_score: 75
block_providers: []
block_flags:
  - hardcoded_api_key
  - hardcoded_credentials

Manual setup (without the action)

If you prefer to install AI-BOM manually:

name: AI-BOM Scan
on: [push, pull_request]

jobs:
  ai-bom:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install AI-BOM
        run: pipx install ai-bom

      - name: Scan for AI components
        run: ai-bom scan . --fail-on critical --quiet -f sarif -o results.sarif

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif
        if: always()

Required permissions

For SARIF upload to work, the workflow needs:

permissions:
  security-events: write  # Required for SARIF upload
  contents: read          # Required for checkout

PR comment integration

To post scan results as a PR comment:

- name: Scan and generate markdown
  run: ai-bom scan . -f markdown -o scan-results.md --quiet

- name: Comment on PR
  uses: marocchino/sticky-pull-request-comment@v2
  with:
    path: scan-results.md

Caching

Speed up scans by caching the AI-BOM installation:

- name: Cache pip packages
  uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: ai-bom-${{ runner.os }}

- name: Install AI-BOM
  run: pipx install ai-bom