# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.

# SPDX-License-Identifier: Apache-2.0

#

# Security Workflows — security suite reusable workflow.

#

# Fans out to the published scanner workflows. Jobs deliberately have no dependencies

# on each other so GitHub Actions schedules the enabled scans in parallel.

#

# Every scan is opt-in: a caller enables exactly the scans that apply to its repository,

# because no single scan set fits every repository (runner access, CodeQL Default setup,

# and language mix all differ).

#

# CONVENTION FOR FUTURE SCANS: add a new scan here with `enable-<scan>: false`. Flipping a

# default from false to true silently changes what every existing caller runs, so it is a

# MAJOR version bump — see the Versioning section of ../../README.md.

#

# PERMISSIONS: a caller must grant the union of every scan job's permissions below, including

# scans it disables. GitHub validates the caller against the permissions this file declares

# before evaluating any `if:`, so a short grant is a startup failure, not a skipped job. Adding

# a scan that needs a scope no existing scan declares is therefore also a MAJOR version bump.

name: Security Suite

on:

workflow_call:

inputs:

enable-secret-scan:

description: >-

Run the Pulse secret scan (secret-scan-pulse.yml). Off by default.

Requires self-hosted nv-gha-runners.

type: boolean

required: false

default: false

enable-vuln-scan:

description: >-

Run the Pulse OSS vulnerability scan (vuln-scan-pulse-oss.yml). Off by default.

Requires self-hosted nv-gha-runners. Set nspect-id to record findings against an

nSpect registration; without it the scan runs unregistered and rapid-only.

type: boolean

required: false

default: false

enable-malware-scan:

description: >-

Run the Pulse malware scan (malware-scan-pulse.yml). Off by default.

Requires self-hosted nv-gha-runners and an nSpect registration — set nspect-id when you do.

type: boolean

required: false

default: false

enable-sast-scan:

description: >-

Run the CodeQL SAST scan (sast-scan-codeql.yml). Off by default.

Enable it only for repositories deliberately on Advanced setup, and set sast-languages when you do.

type: boolean

required: false

default: false

suite-runs-on:

description: >-

Runner for the suite's short helper jobs — the preflight check and the CodeQL language-matrix resolver.

Set this only if the repository cannot use GitHub-hosted runners.

type: string

required: false

default: ubuntu-latest

nspect-id:

description: >-

nSpect ID for the calling repository (NSPECT-xxxx-xxxx), normally passed from the

vars.NSPECT_ID repository variable. Carries no scan prefix because an nSpect ID

belongs to the repository rather than to one scan — every scan here that reports to

nSpect reads this one input.

Optional for enable-vuln-scan: left empty, the vulnerability scan runs unregistered and rapid-only.

Required for enable-malware-scan.

type: string

required: false

default: ''

secret-runs-on:

description: Runner label for the Pulse secret scan (an nv-gha-runners label).

type: string

required: false

default: linux-amd64-cpu4

secret-failure-policy:

description: >-

Pulse finding policy: unverified (default), strict, or all.

See secret-scan-pulse.yml for the full policy semantics.

type: string

required: false

default: unverified

vuln-registered-branch:

description: Default or release branch registered in nSpect. Never a pull-request/* mirror.

type: string

required: false

default: main

vuln-sbom-name:

description: >-

SBOM name of the nSpect registration to scan against, for a registered branch with more

than one SBOM entry. Needs nspect-id; required with vuln-inventory-writeback.

See vuln-scan-pulse-oss.yml (sbom_name).

type: string

required: false

default: ''

vuln-runs-on:

description: Runner label for the Pulse OSS vulnerability scan (an nv-gha-runners label).

type: string

required: false

default: linux-amd64-cpu4

vuln-scan-path:

description: Repository-relative directory to scan.

type: string

required: false

default: .

vuln-scan-mode:

description: >-

Scan family to run: auto (default), persistent, or rapid.

See vuln-scan-pulse-oss.yml for the full mode semantics.

type: string

required: false

default: auto

vuln-build:

description: >-

Enable scanner build mode, for ecosystems whose dependency graph is only resolvable

through a build (Maven, Go).

type: boolean

required: false

default: false

vuln-failure-policy:

description: >-

Pulse OSS finding policy: report-only (default) or fail-on-vulnerability.

Scanner and transport errors fail the job under either value.

type: string

required: false

default: report-only

vuln-detect-properties:

description: JSON object of supported Detect tuning properties. See docs/vuln-scan.

type: string

required: false

default: '{}'

vuln-show-console:

description: Print scanner output with credentials and internal destinations removed.

type: boolean

required: false

default: false

vuln-debug-logging:

description: Enable Pulse debug logging. Required redaction still applies.

type: boolean

required: false

default: false

vuln-python-wheels-artifact:

description: Current-run artifact of prebuilt Python runtime wheels. Requires vuln-python-project.

type: string

required: false

default: ''

vuln-python-project:

description: Installed Python distribution to inspect from the supplied runtime wheels.

type: string

required: false

default: ''

vuln-inventory-writeback:

description: Publish results to nSpect inventory (persistent scans only). Requires vuln-sbom-name.

type: boolean

required: false

default: false

vuln-upload-report:

description: Upload the validated vulnerability report as a 3-day artifact.

type: boolean

required: false

default: false

vuln-timeout-seconds:

description: Scanner timeout in seconds (60-3600).

type: number

required: false

default: 1800

malware-runs-on:

description: Runner label for the Pulse malware scan (an nv-gha-runners label).

type: string

required: false

default: linux-amd64-cpu4

malware-failure-policy:

description: >-

Pulse malware verdict policy: strict (default) or malicious-only.

A MALICIOUS verdict, and any scan that ends without a verdict, fail the job under either value.

type: string

required: false

default: strict

malware-upload-report:

description: Upload the validated malware report, nSpect ID redacted, as a 3-day artifact.

type: boolean

required: false

default: false

malware-timeout-minutes:

description: >-

Job timeout for the Pulse malware scan, in minutes (10 to 360). The scan's report

polling is derived from it.

type: number

required: false

default: 60

sast-languages:

description: >-

JSON array of CodeQL languages, for example '["actions","python"]'.

Entries may also be objects carrying per-language overrides: '[{"language":"go","build-mode":"autobuild"},"rust"]'.

Accepted values: actions, c-cpp, csharp, go, java-kotlin, javascript-typescript, python, ruby, rust, swift.

Each language's build mode is resolved automatically, so languages with incompatible requirements can be combined — see sast-scan-codeql.yml for per-language caveats.

Required when enable-sast-scan is true; ignored otherwise.

type: string

required: false

default: ''

sast-runs-on:

description: >-

Default runner label for the CodeQL analysis. Override per language with the object form of sast-languages.

type: string

required: false

default: ubuntu-latest

sast-build-mode:

description: >-

Preferred CodeQL build mode: none (default) or autobuild. Applied to every language that supports it;

a language that cannot honour it resolves to the mode CodeQL does support and reports the substitution.

type: string

required: false

default: none

sast-queries:

description: CodeQL query suite(s), comma-separated.

type: string

required: false

default: security-extended

sast-config-file:

description: Optional path in the consuming repository to a CodeQL config file.

type: string

required: false

default: ''

permissions:

contents: read

jobs:

preflight:

name: Suite preflight

if: >-

${{ (!inputs.enable-secret-scan && !inputs.enable-vuln-scan && !inputs.enable-malware-scan && !inputs.enable-sast-scan)

|| (inputs.enable-malware-scan && inputs.nspect-id == '')

|| (inputs.enable-sast-scan && inputs.sast-languages == '') }}

runs-on: ${{ inputs.suite-runs-on }}

steps:

- name: Report suite selection

env:

ENABLE_SECRET_SCAN: ${{ inputs.enable-secret-scan }}

ENABLE_VULN_SCAN: ${{ inputs.enable-vuln-scan }}

ENABLE_MALWARE_SCAN: ${{ inputs.enable-malware-scan }}

ENABLE_SAST_SCAN: ${{ inputs.enable-sast-scan }}

NSPECT_ID: ${{ inputs.nspect-id }}

SAST_LANGUAGES: ${{ inputs.sast-languages }}

run: |

set -euo pipefail

# Report every missing companion input before exiting, so a caller enabling two

# scans at once does not have to fix one, re-run, and discover the next.

failures=0

if [ "$ENABLE_MALWARE_SCAN" = "true" ] && [ -z "$NSPECT_ID" ]; then

echo "::error::enable-malware-scan is true but nspect-id is empty. Pass the repository's nSpect ID from the vars.NSPECT_ID repository variable."

failures=$((failures + 1))

fi

if [ "$ENABLE_SAST_SCAN" = "true" ] && [ -z "$SAST_LANGUAGES" ]; then

echo "::error::enable-sast-scan is true but sast-languages is empty. Pass a JSON array of CodeQL languages, for example: sast-languages: '[\"actions\"]'."

failures=$((failures + 1))

fi

if [ "$failures" -ne 0 ]; then

exit 1

fi

if [ "$ENABLE_SECRET_SCAN" != "true" ] && [ "$ENABLE_VULN_SCAN" != "true" ] && [ "$ENABLE_MALWARE_SCAN" != "true" ] && [ "$ENABLE_SAST_SCAN" != "true" ]; then

echo "::warning::Security suite ran no scans — every enable-* input is false. Set enable-secret-scan, enable-vuln-scan, enable-malware-scan and/or enable-sast-scan to true for this check to mean anything."

fi

secret-scan:

name: Secret scan (Pulse)

if: ${{ inputs.enable-secret-scan }}

permissions:

actions: read

contents: read

id-token: write

security-events: write

uses: ./.github/workflows/secret-scan-pulse.yml

with:

runs-on: ${{ inputs.secret-runs-on }}

failure_policy: ${{ inputs.secret-failure-policy }}

vuln-scan:

name: Vulnerability scan (Pulse OSS)

if: ${{ inputs.enable-vuln-scan }}

permissions:

contents: read

id-token: write

uses: ./.github/workflows/vuln-scan-pulse-oss.yml

with:

runs-on: ${{ inputs.vuln-runs-on }}

nspect_id: ${{ inputs.nspect-id }}

registered_branch: ${{ inputs.vuln-registered-branch }}

sbom_name: ${{ inputs.vuln-sbom-name }}

scan_path: ${{ inputs.vuln-scan-path }}

scan_mode: ${{ inputs.vuln-scan-mode }}

build: ${{ inputs.vuln-build }}

python_wheels_artifact: ${{ inputs.vuln-python-wheels-artifact }}

python_project: ${{ inputs.vuln-python-project }}

failure_policy: ${{ inputs.vuln-failure-policy }}

detect_properties: ${{ inputs.vuln-detect-properties }}

show_console: ${{ inputs.vuln-show-console }}

debug_logging: ${{ inputs.vuln-debug-logging }}

inventory_writeback: ${{ inputs.vuln-inventory-writeback }}

upload_report: ${{ inputs.vuln-upload-report }}

timeout_seconds: ${{ inputs.vuln-timeout-seconds }}

malware-scan:

name: Malware scan (Pulse)

if: ${{ inputs.enable-malware-scan && inputs.nspect-id != '' }}

permissions:

id-token: write

uses: ./.github/workflows/malware-scan-pulse.yml

with:

runs-on: ${{ inputs.malware-runs-on }}

nspect_id: ${{ inputs.nspect-id }}

failure_policy: ${{ inputs.malware-failure-policy }}

upload_report: ${{ inputs.malware-upload-report }}

timeout_minutes: ${{ inputs.malware-timeout-minutes }}

sast-scan:

name: SAST (CodeQL)

if: ${{ inputs.enable-sast-scan && inputs.sast-languages != '' }}

permissions:

actions: read

contents: read

security-events: write

uses: ./.github/workflows/sast-scan-codeql.yml

with:

languages: ${{ inputs.sast-languages }}

runs-on: ${{ inputs.sast-runs-on }}

build-mode: ${{ inputs.sast-build-mode }}

resolve-runs-on: ${{ inputs.suite-runs-on }}

queries: ${{ inputs.sast-queries }}

config-file: ${{ inputs.sast-config-file }}