feat: add security scanners workflow (awslabs#161)

* feat: auto-label PRs using actions/labeler

Adds an auto-label job to the Pull Request Validation workflow using
actions/labeler v6.0.1. Labels are applied based on changed file paths
and removed when those files are no longer changed (sync-labels: true).

Works for fork PRs via pull_request_target — no checkout of fork code,
the action only reads file paths from the API.

Initial label rules:
- codebuild: aidlc-rules/**
- documentation: **/*.md, docs/**
- workflows: .github/**

* refactor: rename label to 'rules', refine labeler config

- Rename 'codebuild' label to 'rules' in codebuild.yml (conditions,
  reminder text, and marker)
- Rename 'workflows' label to 'github' matching .github/**
- Scope 'documentation' label to *.md files NOT under aidlc-rules/
  using all-globs-to-any-file with negation

* fix: add issues:write permission for auto-label job

Allows actions/labeler to create labels that don't yet exist in the
repository, preventing failures on first use of a new label rule.

* docs: update administrative guide for auto-labeling and rules label

- Rename all 'codebuild' label references to 'rules' (preserving
  CodeBuild service/environment references)
- Add auto-label job to Pipeline 3 diagram and workflow reference
- Document label rules table (rules, documentation, github)
- Add actions/labeler to external actions table
- Add auto-label job to permissions table
- Add labeler.yml to repository tree diagram

* feat: add security scanners workflow

Adds five security scanning jobs as a new workflow:
- gitleaks: secret detection across full git history
- semgrep: SAST with SARIF output and GitHub compatibility fixes
- grype: dependency vulnerability scanning
- checkov: IaC scanning (GitHub Actions workflows, configs)
- clamav: malware scanning via service container

All jobs run on push to main, PRs to main, daily schedule, and
manual dispatch. SARIF results are uploaded as artifacts and to
GitHub Code Scanning (when available). Follows the deny-all
permissions pattern with per-job grants.

* feat: add bandit job for Python SAST scanning

Scans Python code under scripts/aidlc-evaluator/ for security issues.
Uses bandit v1.9.3 with SARIF output, matching the pattern from
awslabs/agent-plugins.

* feat: add security scanner configuration and baseline files

- .gitleaks.toml: extends default rules, allowlists lock files
- .gitleaks-baseline.json: baselines 12 known findings (all fake
  credentials in test_credential_scrubber.py test fixtures)
- .semgrepignore: skips lock files, test fixtures, build artifacts
- .checkov.yaml: scopes to github_actions + dockerfile frameworks,
  skips CKV_GHA_7 (conflicts with inline buildspec pattern)
- .bandit: targets scripts/aidlc-evaluator, excludes tests,
  medium+ confidence only
- .grype.yaml: fail-on-severity high, with placeholder ignore list

* chore: add gitleaks baseline to semgrepignore and expand comments

Add .gitleaks-baseline.json to .semgrepignore and expand all ignore
comments with specific reasoning for why each entry is excluded from
Semgrep scanning.

* fix: raise bandit confidence to high, add suppression docs, fix clamav deferred failure

- Raise bandit confidence-level from medium to high to reduce noise
- Add inline suppression documentation to .grype.yaml and .checkov.yaml
- Fix clamav job to use deferred-failure pattern (always upload artifact
  before failing) consistent with all other scanner jobs

* docs: add security scanner remediation guide to DEVELOPERS_GUIDE

Document each scanner's failure thresholds, how to review findings,
and how to remediate or suppress them (inline comments, config-level
ignores, baselines). Includes summary tables for quick reference.

* docs: add security scanners to ADMINISTRATIVE_GUIDE

Add security-scanners.yml workflow reference, Pipeline 3 architecture
diagram, updated permissions model and security posture tables, and
Security Finding Requirements section requiring all HIGH and CRITICAL
findings to be remediated or have documented risk acceptance.

* fix: apply deny-all permissions to release workflows

Move release.yml, release-pr.yml, and tag-on-merge.yml to the same
deny-all-then-grant pattern used by all other workflows. All 16
permission scopes are now set to none at the workflow level with only
the required scopes granted at the job level.

* chore: update security scanner tools and actions to latest versions

Scanner tools:
- Gitleaks 8.30.0 → 8.30.1
- Semgrep 1.151.0 → 1.157.0
- Grype 0.104.3 → 0.110.0
- Bandit 1.9.3 → 1.9.4
- Checkov 3.2.500 → 3.2.513
- ClamAV image digest updated to latest stable

GitHub Actions:
- github/codeql-action v4.32.2 → v4.35.1

Remove specific version numbers from ADMINISTRATIVE_GUIDE docs (they
go stale), note that versions are pinned and should be updated
periodically, and add TODO for update procedure documentation.

* fix: move exit code interpolation from run: blocks to env: variables

Replace six instances of ${{ steps.*.outputs.exit_code }} in run:
blocks with step-level env: variables, eliminating all expression
interpolation in run: blocks. This restores the "zero ${{ }}
interpolation in run: blocks" invariant documented in the Security
Posture table.

* fix: include event_name in concurrency group to protect scheduled scans

Add github.event_name to the concurrency group key so that scheduled
runs (group: ...-schedule-refs/heads/main) and push runs (group:
...-push-refs/heads/main) use separate groups. This prevents a push
to main from silently cancelling the daily scheduled scan.

* docs: merge duplicate deny-all-then-grant paragraphs in admin guide

Remove the contradictory paragraph that listed only three workflows
and merge its "strictest possible configuration" clause into the
correct paragraph that covers all six workflows.

* fix: use .bandit configuration

Co-authored-by: Copilot <[email protected]>

* fix(doc): Update how bandit looks for files

Co-authored-by: Copilot <[email protected]>

* fix: add issues write to create labels as necessary

Co-authored-by: Copilot <[email protected]>

* fix: remove security event write to clamav

Co-authored-by: Copilot <[email protected]>

* fix: load grype configurations

Co-authored-by: Copilot <[email protected]>

* fix: convert .bandit config from INI to YAML format

Bandit 1.9.4 expects YAML config but .bandit used legacy INI format,
causing a parse error (exit code 2) that failed the CI job. Convert to
valid YAML and add -ll flag for high-confidence filtering.

* fix: report all bandit findings in SARIF, fail only on HIGH severity

- Remove -ll severity filter so LOW/MEDIUM/HIGH all appear in SARIF
- Check SARIF for HIGH severity (level=error) to decide pass/fail
- Move scan targets into .bandit config so new Python directories
  can be added without editing the workflow

* fix: semgrep reports all findings, fails only on ERROR severity

Match the bandit pattern: report all severity levels in SARIF for
GitHub Code Scanning visibility, but only fail the build when
ERROR-level findings exist.

* fix: checkov reports all findings, fails only on ERROR severity

Match the bandit/semgrep pattern: report all severity levels in SARIF
for GitHub Code Scanning visibility, but only fail the build when
ERROR-level findings exist.

* fix: remove duplicate semgrep step id

* fix: restore -r flag for bandit targets

The YAML config does not support a "targets" key — that was
INI-format only. Without -r on the CLI, bandit gets no scan
targets and produces an empty SARIF file.

---------

Co-authored-by: Scott Schreckengaust <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Sam Castro Oropeza <[email protected]>

Author: 3 people

.bandit

@@ -0,0 +1,11 @@
+# Bandit configuration (YAML format, bandit 1.9+)
+# https://bandit.readthedocs.io/en/latest/config.html
+#
+# NOTE: scan targets must be passed via -r on the CLI; the YAML config
+# does not support a "targets" key.  Edit the workflow's bandit command
+# to add new directories.
+
+# Exclude test directories (test code often has intentional patterns
+# that trigger false positives like assert, subprocess in fixtures)
+exclude_dirs:
+  - "*/tests/*"

.checkov.yaml

@@ -0,0 +1,28 @@
+# Checkov configuration
+# https://www.checkov.io/2.Basics/CLI%20Command%20Reference.html
+
+# Scan GitHub Actions workflows and Dockerfiles
+framework:
+  - github_actions
+  - dockerfile
+
+# Skip checks that conflict with this repo's patterns.
+#
+# Repo-wide suppressions go here. For file-level suppressions, use inline
+# comments in the source file:
+#
+#   Dockerfile:
+#     # checkov:skip=CKV_DOCKER_2:healthcheck not needed for build-only image
+#     FROM python:3.12-slim
+#
+#   GitHub Actions YAML:
+#     # checkov:skip=CKV_GHA_7:buildspec-override requires user parameters
+#     - uses: aws-actions/aws-codebuild-run-build@v1
+#
+# Multiple skips on one line:
+#     # checkov:skip=CKV_DOCKER_2,CKV_DOCKER_3:reason for both
+skip-check:
+  # CKV_GHA_7: "The build output cannot be affected by user parameters other
+  # than the build entry point and the top-level source location"
+  # — conflicts with inline buildspec-override in codebuild.yml
+  - CKV_GHA_7

.github/workflows/release-pr.yml

@@ -22,12 +22,29 @@ on:
         type: string
 
 permissions:
-  contents: write
-  pull-requests: write
+  actions: none
+  attestations: none
+  checks: none
+  contents: none
+  deployments: none
+  discussions: none
+  id-token: none
+  issues: none
+  models: none
+  packages: none
+  pages: none
+  pull-requests: none
+  repository-projects: none
+  security-events: none
+  statuses: none
 
 jobs:
   release-pr:
     name: Create Release PR
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code

.github/workflows/release.yml

@@ -24,11 +24,27 @@ on:
       - 'v*'
 
 permissions:
-  contents: write
+  actions: none
+  attestations: none
+  checks: none
+  contents: none
+  deployments: none
+  discussions: none
+  id-token: none
+  issues: none
+  models: none
+  packages: none
+  pages: none
+  pull-requests: none
+  repository-projects: none
+  security-events: none
+  statuses: none
 
 jobs:
   release:
     name: Create Release
+    permissions:
+      contents: write
     runs-on: ubuntu-latest
 
     steps: