Add support for PackageGuard and run it in the pipeline

Adds a Fallout CLI tool wrapper for PackageGuard's analyze command,
based on AnalyzeCommandSettings.cs
(https://github.com/dennisdoomen/packageguard/blob/main/Src/PackageGuard/AnalyzeCommandSettings.cs),
and wires it into the build pipeline as a compliance gate plus SBOM
and risk reporting.

Tool wrapper:
- src/Fallout.Common/Tools/PackageGuard/PackageGuard.json, covering
  all 18 analyze settings, plus NpmPackageManager and SbomFormat
  enumerations for the properties restricted to a fixed set of
  values.
- PackageGuard.Generated.cs, regenerated via ./build.ps1
  GenerateTools.
- A row in the supported-tools table in
  docs/website/03-common/08-cli-tools.md.
- TestPackageGuard in tests/Fallout.Common.Specs/SettingsSpecs.cs.

Build pipeline:
- New PackageGuard target (build/Build.PackageGuard.cs) runs the
  policy-violation check on every PR (added to build.yml's required
  gate, alongside VerifyGeneratedTools/Test/Pack) — a license or
  package-policy violation now blocks the PR gate like any other
  check.
- The SBOM (CycloneDX) and HTML + SARIF risk report are only
  generated on main, develop, release/*, or support/* — via
  GitRepository.IsOn*Branch() (including a new IsOnSupportBranch()
  extension), or, for the tag-triggered release workflow where HEAD
  is detached, because that workflow's own validate-ref job already
  proved the tag is reachable from a production branch.
- New security-scan workflow (generated from a third [GitHubActions]
  attribute, using the existing IConfigureGitHubActions custom-step
  hook) runs on every push to those branches and uploads the SARIF
  report to GitHub code scanning via github/codeql-action/upload-sarif.
- publish-packages-release.yml now runs PackageGuard alongside
  Test+Pack and attaches both the SBOM and the HTML risk report to
  the GitHub Release as assets.
- Added .packageguard/config.json: an allowlist covering the
  permissive license family this repo's actual dependencies use
  (MIT, Apache-2.0, BSD-2/3-Clause, ISC, 0BSD, MS-PL), plus an
  explicit package-name allowance for FluentAssertions — its pinned
  8.10.0 reports no SPDX license expression at all (a licenseFile
  plus a note that commercial use requires a paid Xceed license), so
  no license-based match would ever cover it. Mirrors the same
  package-name allowance PackageGuard's own repo uses on itself.
  Without a config file, PackageGuard's NuGet analysis throws on
  every run instead of defaulting permissive, which would have
  broken every PR the moment this became a required check.

Purely additive — no breaking changes.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: dennisdoomen

.fallout/build.schema.json

@@ -34,6 +34,7 @@
         "GenerateTools",
         "Install",
         "Pack",
+        "PackageGuard",
         "Publish",
         "References",
         "ReportCoverage",

.github/workflows/build.yml

@@ -55,5 +55,7 @@ jobs:
           global-json-file: global.json
       - name: 'Restore: dotnet tools'
         run: dotnet tool restore
-      - name: 'Run: VerifyGeneratedTools, Test, Pack'
-        run: dotnet fallout VerifyGeneratedTools Test Pack
+      - name: 'Run: VerifyGeneratedTools, Test, Pack, PackageGuard'
+        run: dotnet fallout VerifyGeneratedTools Test Pack PackageGuard
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/publish-packages-release.yml

@@ -119,22 +119,36 @@ jobs:
           global-json-file: global.json
       - name: 'Restore: dotnet tools'
         run: dotnet tool restore
-      - name: 'Run: Test + Pack'
-        run: dotnet fallout Test Pack
+      - name: 'Run: Test + Pack + PackageGuard'
+        run: dotnet fallout Test Pack PackageGuard
         env:
           # We check out the tag above, so HEAD is detached and matches none of
           # version.json's publicReleaseRefSpec entries (they're all branch refs,
           # and nbgv never matches that spec against refs/tags/*). Without this,
           # NB.GV treats the build as non-public and stamps a git-height suffix
           # onto every package — v10.4.0-rc.3 shipped as 10.4.0-rc.3.geabd043cc2.
           PublicRelease: true
+          # PackageGuard's own target (build/Build.PackageGuard.cs) is gated on either being on
+          # a long-lived branch or running in this workflow (GitHubActions.Workflow ==
+          # "publish-packages-release") — the tag checkout above leaves HEAD detached, so the
+          # branch check alone can't pass here; validate-ref already proved the tag is
+          # reachable from a production branch. GITHUB_TOKEN lets it authenticate to GitHub
+          # (license lookups) instead of hitting anonymous rate limits.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: 'Upload: package artifacts'
         uses: actions/upload-artifact@v7
         with:
           name: packages
           path: output/packages/*.nupkg
           retention-days: 7
           if-no-files-found: error
+      - name: 'Upload: PackageGuard SBOM + risk report'
+        uses: actions/upload-artifact@v7
+        with:
+          name: packageguard
+          path: output/packageguard/*
+          retention-days: 7
+          if-no-files-found: error
 
   # Tier 1 — production / nuget.org. **OPT-IN ONLY.** Tag pushes do NOT trigger
   # this job; you must invoke workflow_dispatch with publish-to-nugetorg=true.
@@ -241,9 +255,11 @@ jobs:
               --skip-duplicate
           done
 
-  # Bundled artifact distribution. Attaches all nupkgs to the GitHub Release
-  # for the tag. Idempotent: if the release already exists (workflow_dispatch
-  # retry case), uploads or replaces missing assets via --clobber.
+  # Bundled artifact distribution. Attaches all nupkgs, plus the PackageGuard SBOM and HTML
+  # risk report, to the GitHub Release for the tag. Idempotent: if the release already exists
+  # (workflow_dispatch retry case), uploads or replaces missing assets via --clobber. The .sarif
+  # itself isn't attached here — it's reported to GitHub's code-scanning feature instead
+  # (security-scan.yml); the HTML is the human-readable counterpart of the same report.
   publish-github-releases:
     name: publish → GitHub Releases
     runs-on: ubuntu-latest
@@ -262,6 +278,11 @@ jobs:
         with:
           name: packages
           path: output/packages
+      - name: 'Download: PackageGuard SBOM + risk report'
+        uses: actions/download-artifact@v8
+        with:
+          name: packageguard
+          path: output/packageguard
       - name: 'Create or update GitHub Release with package artifacts'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -273,14 +294,21 @@ jobs:
             TAG="${GITHUB_REF_NAME}"
           fi
           echo "Tag: $TAG"
+          assets=(output/packages/*.nupkg)
+          if [ -f output/packageguard/sbom.json ]; then
+            assets+=("output/packageguard/sbom.json")
+          fi
+          if [ -f output/packageguard/risk-report.html ]; then
+            assets+=("output/packageguard/risk-report.html")
+          fi
           if gh release view "$TAG" > /dev/null 2>&1; then
             echo "Release $TAG already exists — uploading assets with --clobber."
-            gh release upload "$TAG" output/packages/*.nupkg --clobber
+            gh release upload "$TAG" "${assets[@]}" --clobber
           else
             echo "Creating new release $TAG."
             gh release create "$TAG" \
               --title "$TAG" \
               --target "$(git rev-parse HEAD)" \
               --generate-notes \
-              output/packages/*.nupkg
+              "${assets[@]}"
           fi

.github/workflows/security-scan.yml

@@ -0,0 +1,67 @@
+# ------------------------------------------------------------------------------
+# <auto-generated>
+#
+#     This code was generated.
+#
+#     - To turn off auto-generation set:
+#
+#         [GitHubActions (AutoGenerate = false)]
+#
+#     - To trigger manual generation invoke:
+#
+#         fallout --generate-configuration GitHubActions_security-scan --host GitHubActions
+#
+# </auto-generated>
+# ------------------------------------------------------------------------------
+
+name: security-scan
+
+on:
+  push:
+    branches:
+      - develop
+      - main
+      - 'release/*'
+      - 'support/*'
+    paths-ignore:
+      - 'docs/**'
+      - '.assets/**'
+      - '**/*.md'
+
+permissions:
+  security-events: write
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ubuntu-latest:
+    name: ubuntu-latest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: 'Cache: .fallout/temp, ~/.nuget/packages'
+        uses: actions/cache@v6
+        with:
+          path: |
+            .fallout/temp
+            ~/.nuget/packages
+          key: ${{ runner.os }}-${{ hashFiles('**/global.json', '**/*.csproj', '**/Directory.Packages.props') }}
+      - name: 'Setup: .NET SDK'
+        uses: actions/setup-dotnet@v6
+        with:
+          global-json-file: global.json
+      - name: 'Restore: dotnet tools'
+        run: dotnet tool restore
+      - name: 'Run: PackageGuard'
+        run: dotnet fallout PackageGuard
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: 'Upload risk-report SARIF to GitHub code scanning'
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: output/packageguard/risk-report.sarif

.packageguard/config.json

@@ -0,0 +1,18 @@
+{
+  "Settings": {
+    "Allow": {
+      "Licenses": [
+        "MIT",
+        "Apache-2.0",
+        "BSD-2-Clause",
+        "BSD-3-Clause",
+        "ISC",
+        "0BSD",
+        "MS-PL"
+      ],
+      "Packages": [
+        "FluentAssertions"
+      ]
+    }
+  }
+}

build/Build.CI.GitHubActions.cs

@@ -1,9 +1,11 @@
+using System.Collections.Generic;
 using Fallout.Common.CI.GitHubActions;
+using Fallout.Common.CI.GitHubActions.Configuration;
 using Fallout.Components;
 
-// Two generated build workflows. Both run Test+Pack; both are GENERATED from the
-// attributes below — edit here and regenerate (`./build.sh`), never hand-edit the
-// `.yml`.
+// Three generated workflows. build.yml and build-cross-platform.yml both run Test+Pack; all
+// three are GENERATED from the attributes below — edit here and regenerate (`./build.sh`),
+// never hand-edit the `.yml`.
 //
 //   build.yml               — the Linux PR gate, and the ONLY required status
 //                             check (job `ubuntu-latest`; branch protection keys on
@@ -15,7 +17,12 @@
 //                             merge SHA, keeping HEAD attached so
 //                             GitHubTasksTest.GitHubRepositoryFromLocalDirectoryTest
 //                             (which reads .git/HEAD via GitRepository.FromLocalDirectory)
-//                             resolves a non-null branch.
+//                             resolves a non-null branch. Also runs PackageGuard — its
+//                             policy-violation check gates every PR, though the target skips
+//                             SBOM/risk-report generation here (build/Build.PackageGuard.cs,
+//                             IsOnLongLivedBranch — this checkout is never on one of the four).
+//                             EnableGitHubToken avoids anonymous GitHub API rate-limiting on
+//                             PackageGuard's license lookups, now that it runs on every PR.
 //
 //   build-cross-platform.yml — macOS + Windows in ONE workflow (one job per image).
 //                             Cross-platform full Test+Pack is gated to RELEASE
@@ -44,7 +51,8 @@
     // long-lived and protected; all require the ubuntu-latest check.
     OnPullRequestBranches = new[] { DevelopBranch, MainBranch, ReleaseBranchPattern, SupportBranchPattern },
     OnPullRequestExcludePaths = new[] { "docs/**", ".assets/**", "**/*.md" },
-    InvokedTargets = new[] { nameof(VerifyGeneratedTools), nameof(ITest.Test), nameof(IPack.Pack) },
+    InvokedTargets = new[] { nameof(VerifyGeneratedTools), nameof(ITest.Test), nameof(IPack.Pack), nameof(PackageGuard) },
+    EnableGitHubToken = true,
     PublishArtifacts = false)]
 [GitHubActions(
     "build-cross-platform",
@@ -61,7 +69,34 @@
     OnPullRequestExcludePaths = new[] { "docs/**", ".assets/**", "**/*.md" },
     InvokedTargets = new[] { nameof(ITest.Test), nameof(IPack.Pack) },
     PublishArtifacts = false)]
-partial class Build
+//   security-scan.yml        — continuous SBOM + risk-report generation
+//                             (build/Build.PackageGuard.cs). PackageGuard's policy-violation
+//                             check already runs on every PR via build.yml above; this workflow
+//                             is for the SBOM/SARIF/HTML side, which build.yml's target
+//                             deliberately skips (its checkout is never one of the four
+//                             long-lived branches, so IsOnLongLivedBranch is false there).
+//                             Push-only, and only to develop/main/release/*/support/* — a push
+//                             is when there's actually a new commit on one of those branches to
+//                             report on. EnableGitHubToken feeds GITHUB_TOKEN to PackageGuard
+//                             (avoids GitHub API rate-limiting on license lookups) and to the
+//                             upload-sarif step's security-events:write use.
+[GitHubActions(
+    "security-scan",
+    GitHubActionsImage.UbuntuLatest,
+    FetchDepth = 0,
+    ConcurrencyGroup = "${{ github.workflow }}-${{ github.ref }}",
+    ConcurrencyCancelInProgress = true,
+    OnPushBranches = new[] { DevelopBranch, MainBranch, ReleaseBranchPattern, SupportBranchPattern },
+    OnPushExcludePaths = new[] { "docs/**", ".assets/**", "**/*.md" },
+    InvokedTargets = new[] { nameof(PackageGuard) },
+    EnableGitHubToken = true,
+    // Specifying any `permissions:` block switches the job from GitHub's default read-all to
+    // explicit-only — contents:read has to be listed too, or upload-sarif (and checkout) lose
+    // it. See GitHub's own upload-sarif docs for this exact pairing.
+    ReadPermissions = new[] { GitHubActionsPermissions.Contents },
+    WritePermissions = new[] { GitHubActionsPermissions.SecurityEvents },
+    PublishArtifacts = false)]
+partial class Build : IConfigureGitHubActions
 {
     // The release workflow is intentionally hand-written at
     // .github/workflows/publish-packages-release.yml — that lets us name the GitHub
@@ -71,4 +106,24 @@ partial class Build
     // workflow's `name:` — it gates ICreateGitHubRelease.CreateGitHubRelease
     // (Build.cs) to the release workflow only.
     const string ReleaseWorkflow = "publish-packages-release";
+
+    // Injects the SARIF upload after security-scan's "dotnet fallout PackageGuard" run step —
+    // GitHubActionsStepPosition.PostRun is exactly "after the run block, before the built-in
+    // artifact upload". Scoped to this one generated job by WorkflowName; other jobs get no
+    // insertions.
+    void IConfigureGitHubActions.ConfigureSteps(GitHubActionsStepPipeline pipeline)
+    {
+        if (pipeline.WorkflowName == "security-scan")
+        {
+            pipeline.Insert(GitHubActionsStepPosition.PostRun, new GitHubActionsCustomStep
+            {
+                Name = "Upload risk-report SARIF to GitHub code scanning",
+                Uses = "github/codeql-action/upload-sarif@v3",
+                With = new Dictionary<string, string>
+                {
+                    ["sarif_file"] = "output/packageguard/risk-report.sarif",
+                },
+            });
+        }
+    }
 }

build/Build.PackageGuard.cs

@@ -0,0 +1,60 @@
+using Fallout.Common;
+using Fallout.Common.Git;
+using Fallout.Common.IO;
+using Fallout.Common.Tooling;
+using Fallout.Common.Tools.PackageGuard;
+using Fallout.Common.Utilities;
+using Fallout.Components;
+
+partial class Build
+{
+    // PackageGuard's own CLI only exposes an env-var override for the risk-report path
+    // (see PackageGuard.json's help text on ReportRisk) — there's no `--report-risk <path>`
+    // argument in our wrapper, matching the repo-wide convention that bool CLI flags stay
+    // presence-only. Setting this process env var instead pins the SARIF/HTML pair to a
+    // deterministic path we can reference from CI (upload-sarif, the release asset step).
+    const string PackageGuardReportRiskPathOverrideEnvironmentVariable = "PACKAGEGUARD_REPORT_RISK_PATH_OVERRIDE";
+
+    AbsolutePath PackageGuardDirectory => OutputDirectory / "packageguard";
+    AbsolutePath PackageGuardSbomFile => PackageGuardDirectory / "sbom.json";
+    AbsolutePath PackageGuardSarifFile => PackageGuardDirectory / "risk-report.sarif";
+
+    // The SBOM and risk report (HTML + SARIF) are only worth generating where they're actually
+    // consumed: security-scan.yml uploads the SARIF on a push to one of these four branches, and
+    // the release workflow attaches the SBOM/HTML to the GitHub Release. Neither happens on a PR
+    // (build.yml checks out the contributor's own branch via github.head_ref, never one of
+    // these), or on a tag-triggered release checkout (detached HEAD — hence the
+    // GitHubActions.Workflow fallback, since that workflow's own validate-ref job already
+    // proved the tag is reachable from a production branch).
+    bool IsOnLongLivedBranch =>
+        GitRepository.IsOnMainBranch() ||
+        GitRepository.IsOnDevelopBranch() ||
+        GitRepository.IsOnReleaseBranch() ||
+        GitRepository.IsOnSupportBranch() ||
+        GitHubActions?.Workflow == ReleaseWorkflow;
+
+    // Runs unconditionally — this is the PR gate's policy-violation check (build.yml), so it has
+    // to run on every branch, including a contributor's feature branch. Only the SBOM/risk-report
+    // generation is restricted to the four long-lived branches, via IsOnLongLivedBranch below.
+    Target PackageGuard => _ => _
+        .DependsOn<IRestore>()
+        .Produces(PackageGuardSbomFile)
+        .Produces(PackageGuardSarifFile)
+        .Produces(PackageGuardDirectory / "*.html")
+        .Executes(() =>
+        {
+            var generateReports = IsOnLongLivedBranch;
+
+            if (generateReports)
+                PackageGuardDirectory.CreateOrCleanDirectory();
+
+            PackageGuardTasks.PackageGuard(_ => _
+                .SetProjectPath(Solution.Path)
+                .SetGitHubApiKey(From<ICreateGitHubRelease>().GitHubToken)
+                .When(generateReports, _ => _
+                    .EnableReportRisk()
+                    .SetSbom(SbomFormat.cyclonedx)
+                    .SetSbomOutput(PackageGuardSbomFile)
+                    .SetProcessEnvironmentVariable(PackageGuardReportRiskPathOverrideEnvironmentVariable, PackageGuardSarifFile)));
+        });
+}

build/_build.csproj

@@ -58,6 +58,7 @@
          Build.cs as the canonical version source. Replaces GitVersion.Tool (#81). Direct
          dependency because _build.csproj turns off central package management. -->
     <PackageReference Include="Nerdbank.GitVersioning" Version="3.7.115" PrivateAssets="All" />
+    <PackageDownload Include="PackageGuard" Version="[2.4.0]" />
     <PackageDownload Include="ReportGenerator" Version="[5.2.0]" />
     <!-- Used by Fallout.Tooling.Tests' ToolTasksToolPathTest as a sample package
          for tool-path resolution smoke tests. Not used for running our own tests. -->