Copyright © 2025-2026 Blackout Secure | Apache License 2.0

A drop-in composite GitHub Action that detects what's in your repo → runs the right scanners → audits repo posture → uploads one unified SARIF to GitHub Advanced Security.

Everything in one Marketplace install: secret scanning, workflow linting, shell linting, and a posture auditor that checks the Advanced Security toggles, workflow permissions, branch protection, required reviews, and CODEOWNERS for every branch you care about.

• Posture audit — 30+ rules (PS001–PS033) covering GHAS toggles, workflow permissions: blocks, branch protection, required reviews, signed commits, status checks, conversation resolution, force-push restrictions, and CODEOWNERS ownership coverage. Per-rule severity is configurable.
• Bundled scanners (v1.0) — actionlint for workflow YAML, gitleaks for secrets across the working tree, and shellcheck for *.sh / *.bash. Each runs conditionally based on what ecosystems are detected.
• Ecosystem detection — walks the working tree and surfaces what's present: Python / JavaScript / TypeScript / Go / Java / C# / Ruby / Rust / shell, plus Dockerfiles, Compose files, GitHub workflows, Terraform, Kubernetes manifests, and package-manager lockfiles.
• Unified SARIF upload — every scanner's findings and every posture finding land in a single SARIF that is uploaded to GitHub Advanced Security under one category (bos-code-scanning-kit), so they all appear on the repo Security tab.
• .bos-scan.yml config — per-repo policy lives in one human-readable YAML file at the repo root. Defaults are safe; you only declare what you want to change.
• Pure-stdlib Python core — no third-party Python deps beyond PyYAML. The composite Action installs the kit on the runner with a single pip install.

• GitHub-hosted Linux runner (ubuntu-latest or newer) — the kit installs python via actions/setup-python@v5 automatically.
• For the posture audit: a token with repo scope. The default ${{ secrets.GITHUB_TOKEN }} is enough for the code-scanning probe (PS001). Secret-scanning (PS002), Dependabot (PS003), and branch-protection probes (PS020-PS025) require a PAT — see SCANNING_PAT — advanced posture credentials for the full tick / don't-tick checklist (classic and fine-grained).
• For the SARIF upload: security-events: write in your workflow permissions: block.

name: Code scanning

on:
  push:
    branches: [main, dev]
  pull_request:
    branches: [main, dev]
  schedule:
    - cron: '17 4 * * 1'   # weekly Monday 04:17 UTC

permissions:
  contents:        read
  security-events: write   # upload SARIF
  actions:         read    # workflow context

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

      - uses: blackoutsecure/bos-code-scanning-kit@v1
        with:
          # Prefer SCANNING_PAT when the org/repo has set it (unlocks
          # PS002 / PS003 / PS020-PS025); otherwise fall back to the
          # workflow's built-in GITHUB_TOKEN (PS001 only — the other
          # posture rules emit `skip` rows). See § 'SCANNING_PAT —
          # advanced posture credentials' below for the PAT recipe.
          github_token: ${{ secrets.SCANNING_PAT || secrets.GITHUB_TOKEN }}

That's it. The kit auto-discovers your ecosystem, runs every applicable scanner, audits posture, and uploads a single SARIF.

The secrets.SCANNING_PAT || secrets.GITHUB_TOKEN form is safe to ship before you've created the PAT — when the secret is unset, the expression evaluates to secrets.GITHUB_TOKEN and the kit runs in baseline mode (PS001 only). Adding SCANNING_PAT at the org/repo level later upgrades every consuming workflow automatically with no code changes.

Pick a uses: ref shape based on how strict your supply-chain posture needs to be. All three forms are supported equally.

The SHA for any tag is git rev-list -n 1 v1.0.0 against this repo, or the commit field of the GitHub Release JSON.

The table above is auto-generated from action.yml by scripts/render_readme_inputs.py. Edit action.yml and run python3 scripts/render_readme_inputs.py --write.

The posture audit can run with either:

• secrets.GITHUB_TOKEN (baseline visibility)
• secrets.SCANNING_PAT (recommended for full posture coverage)

Recommended caller pattern:

with:
  github_token: ${{ secrets.SCANNING_PAT || secrets.GITHUB_TOKEN }}

With only GITHUB_TOKEN, rules that require admin-level visibility (for example branch protection and some security settings) may emit skip findings. Using SCANNING_PAT upgrades those to real pass/warn/fail evaluations.

Minimum PAT guidance:

• Fine-grained PAT (preferred): grant read access only to the selected repositories and security/admin metadata needed by posture checks.
• Classic PAT (fallback): repo scope.
• Store as an Actions secret named SCANNING_PAT.

Severities can be overridden per rule in .bos-scan.yml.

PS000 is reserved for tooling errors (e.g. missing token) and is always emitted at error severity.

Every scanner output is normalised to SARIF 2.1.0 and merged with the posture findings into a single upload artefact (bos-scan.sarif by default). All third-party binaries are version-pinned and downloaded fresh per run; no scanner is sourced from latest.

This table covers every external tool currently used by the shipped kit.

Only the tools listed above are executed by the current action.yml.

The scanner roster above is driven by the ecosystem detector (src/scan_kit/detect.py), which classifies the working tree along three axes. Anything not in this list will be silently ignored.

Every field is optional — the kit ships safe defaults. A representative full file:

# .bos-scan.yml — Blackout Secure Code Scanning Kit config

owner:        blackoutsecure
project_name: my-action
email:        security@example.com

scan:
  tools:   auto              # auto | explicit | none
  exclude: []                # scanners to skip even if their fingerprint matches
  fail_on: high              # critical | high | medium | low | never
  codeql:
    languages: []            # explicit CodeQL languages; empty => auto-detect
    exclude_languages: []

posture:
  ghas:
    require_code_scanning:     warn   # fail | warn | skip
    require_secret_scanning:   warn
    require_dependabot_alerts: warn

  workflows:
    require_permissions_block: warn
    forbid_write_all:          warn
    require_pinned_actions:    warn   # PS012 — fail | warn | skip
    allow_tag_pin: []                 # owner/repo entries exempted from PS012 (e.g. ['actions/checkout'])

  branches:
    main:
      required_reviews:                2
      restrict_force_push:             true
      require_status_checks:           true
      require_signed_commits:          true
      require_conversation_resolution: true
      severity:                        fail
    dev:
      required_reviews:                1
      severity:                        warn

  codeowners:
    require_file:         warn
    validate_users_exist: false   # set true to probe each @user/@org-team via API

Unknown top-level keys are ignored so that future kit versions can extend the schema without breaking older callers.

The kit also ships a standalone bos-scan CLI for local triage or non-GitHub CI:

pip install bos-code-scanning-kit

# Detect ecosystems
bos-scan detect --root .

# Validate config
bos-scan validate --root .

# Posture audit (requires GITHUB_TOKEN)
export GITHUB_TOKEN=<your-token>
bos-scan posture \
  --owner your-org \
  --repo  bos-code-scanning-kit \
  --root  . \
  --sarif posture.sarif

# Merge multiple SARIFs
bos-scan sarif \
  --input gitleaks.sarif \
  --input actionlint.sarif \
  --posture posture.sarif \
  --output bos-scan.sarif

Issues and PRs are welcome on dev. Run the tests with:

pip install -e .
pip install -r requirements-dev.txt
pytest test/ -v
ruff check src test

Apache License 2.0 — see LICENSE and NOTICE.