Agent Instructions

Guidelines for agents (and humans) working in the NVIDIA Security Workflows repository.

Overview

This repository publishes the security-compliance machinery that downstream NVIDIA repositories consume across six scan categories — Secret, License, Vulnerability, Malware, SAST, GuardWords. It exposes two surfaces:

• Reusable GitHub Actions workflows under .github/workflows/ — job-level server-side enforcement via workflow_call. Each workflow declares its own permissions: block and runs in an isolated job. This is the CI enforcement surface for security gates per guardrail #4 (least-privilege).
• Pre-commit hooks declared in .pre-commit-hooks.yaml — local-advisory checks consumed by downstream .pre-commit-config.yaml files. secret-scan-trufflehog uses language: python and downloads the pinned, SHA-256-verified TruffleHog release into pre-commit's isolated environment; consumers need no system scanner or shell installer. guardwords-scan-code-scanning is a standard-library Python wrapper around NVIDIA's internal code-scanning client, set up per machine with hooks/guardwords/install_client.py; see hooks/guardwords/README.md. Never commit the internal GitLab project URL or service endpoint: both are arguments.

Consumer repositories reference the CI workflow and pre-commit hooks by 40-character commit SHA (pre-commit pins carry the release tag in a # frozen: comment) — see README.md → Pin policy per surface. Changes here have org-wide reach.

The repository is currently in early scaffold (v0.1.0 pre-release). The first scan — Secret scanning — ships two lanes: the CI enforcement workflow .github/workflows/secret-scan-pulse.yml (NVIDIA-licensed Pulse Secret Scanner, run on nv-gha-runners), and the local-advisory pre-commit hook .pre-commit-hooks.yaml (open-source trufflesecurity/trufflehog, installed into pre-commit's isolated environment). Pulse is container-only, so it is CI-only; the pre-commit lane deliberately uses the OSS CLI to stay within the <10s DX budget on developer machines.

Read First

Before any non-trivial change, read:

• README.md — repository scope, the workflow_call contract, versioning policy
• .github/workflows/README.md and hooks/README.md — the workflow and hook catalogues; scan- and hook-specific documentation belongs there, not in the top-level README
• GOVERNANCE.md — what changes require ProdSec sign-off vs routine maintainer review
• ROADMAP.md — current status of each scan category
• CHANGELOG.md — record your change under [Unreleased]
• SECURITY.md — vulnerability reporting (never open public issues)
• Any AGENTS.md in subdirectories — nearest wins.

Workflow Development Guardrails

Everything published from this repository — workflow_call workflows and .pre-commit-hooks.yaml hooks — has org-wide reach through pinned references in downstream repositories (commit SHA on both surfaces). These constraints keep that blast radius contained.

1. workflow_call interfaces and .pre-commit-hooks.yaml hook ids are public contracts. Renaming or removing a workflow input, renaming or removing a hook id, changing hook arguments, or changing a default that affects security posture is a major version bump per README.md.
2. Default to fail-closed. A scan finding blocks the consumer's merge (workflows) or commit (pre-commit hooks). Fail-open behavior must be an explicit, opt-in input — never the default. One documented exception: guardwords-scan-code-scanning skips by default when its NVIDIA-internal service is unavailable, because failing would block every external contributor; its findings still block, and --on-unavailable=fail opts in to failing.

3. Pin every external reference per surface — full table in README.md:

   • uses: in a workflow → 40-character commit SHA
   • rev: in a consumer's .pre-commit-config.yaml → 40-character commit SHA with the release tag as a comment (rev: <commit SHA> # frozen: v0.4.0, as written by pre-commit autoupdate --freeze)

   Branch references (@main, @latest) are never acceptable.

4. Least-privilege permissions:. Default the workflow root to read-only; escalate per-job only where required (e.g. security-events: write for SARIF upload).
5. No secrets in this repository. Workflows may consume caller-supplied secrets via secrets: inputs, but no tokens, certificates, or .env files are ever committed here. If a change appears to require a committed secret, stop and ask.
6. Audit-log output is part of the contract. Each workflow is expected to emit a structured run record; changing its shape is at least a minor version bump. The shared schema is tracked in ROADMAP.md.
7. Pre-commit hooks must respect the <10s DX budget. Scans that cannot fit (malware verdict service, full SCA, full SAST) ship as workflows only — they are explicitly out of scope for the pre-commit surface.
8. Update archive pins as one reviewed unit. When changing TruffleHog, update the version, every supported platform archive URL, and every SHA-256 in hooks/trufflehog/setup.cfg, then update the third-party notice. No scanner archive or binary may be committed or published from this repository.

Changes that fall outside these guardrails require ProdSec acknowledgment per GOVERNANCE.md.

Validating Changes

This repository contains no application code beyond thin pre-commit hook wrappers and the GuardWords client setup script; validation is YAML- and Actions-focused.

# Syntactic YAML check across all tracked YAML files
python3 -c "import yaml,sys; [yaml.safe_load(open(f)) for f in sys.argv[1:]]" \
  $(git ls-files '*.yml' '*.yaml')

# GitHub Actions semantics — strongly recommended for any .github/workflows/ change.
# https://github.com/rhysd/actionlint
actionlint

Run pre-commit run --all-files before committing.

For changes to published pre-commit hooks, also run:

PRE_COMMIT_HOME="$(mktemp -d)" pre-commit try-repo . --all-files

The smoke test downloads a release archive; remove the temporary pre-commit directory afterward. It covers hooks that run at the pre-commit stage; add stage-specific smoke coverage for a hook limited to another stage.

Out of Scope

• Application source code or libraries — this is a workflow-only repository, apart from the minimal packaging metadata, thin wrappers, and setup script needed for pre-commit hooks.
• Per-repository configuration for downstream consumers — lives in each consumer repo, not here.

General Guidelines

• Prefer focused pull requests — one workflow change per PR.
• Update CHANGELOG.md under [Unreleased] for every change that affects consumers.
• When in doubt about whether a change is a patch, minor, or major version bump, raise it in the PR for maintainer review.