Skip to main content

Security Documentation

📋 Overview​

Security documentation for the Physical AI Toolchain covering threat analysis, deployment hardening, and vulnerability reporting.

📄 Documents​

DocumentDescription
Threat ModelSTRIDE-based threat analysis and remediation roadmap
Deployment Security GuideSecurity configuration inventory and deployment responsibilities
Release VerificationVerify release artifact provenance and SBOM attestations
Workflow PermissionsGitHub Actions permission scopes and OSSF Scorecard exceptions
SECURITY.mdVulnerability disclosure and reporting process

🔒 Security Posture​

This reference architecture deploys AKS clusters with GPU node pools, Azure Machine Learning, and NVIDIA OSMO for robotics training and inference. All components are infrastructure-as-code artifacts; no hosted service or user-facing application exists.

The threat model documents:

  • 19 threats across STRIDE categories
  • Security controls mapped to each threat
  • Trust boundary analysis across IaC, cluster, and ML pipeline layers
  • Prioritized remediation roadmap

The security guide documents:

  • Default security configurations shipped with the architecture
  • Deployment team responsibilities before, during, and after provisioning
  • Security considerations checklist with Azure documentation references

🛠️ Operational Scripts​

Automated security and freshness checks that run on GitHub Actions schedules and publish findings to the Security tab.

ScriptWorkflowPurpose
scripts/security/Modules/PinnedToolVersions.psm1check-binary-freshness.yml, check-binary-integrity.ymlProvide literal tool version discovery across tracked shell, PowerShell, JSON, and JSONC files
scripts/security/Test-BinaryFreshness.ps1check-binary-integrity.ymlVerify pinned binary SHA-256 hashes and detect Helm chart version drift (SARIF output)
scripts/security/Test-DependencyPinning.ps1dependency-pinning-scan.ymlValidate exact pins for GitHub Actions, packages, inline pip/uv installs, workflow container images, and AzureML environment assets (Dockerfile base images: OpenSSF Scorecard)
scripts/security/Test-SHAStaleness.ps1sha-staleness-check.ymlDetect SHA pins that have drifted behind upstream release tags
scripts/update-chart-hashes.shRun manually after chart bumpsRefresh pinned Helm chart versions and SHA-256 hashes in infrastructure/setup/defaults.conf
scripts/update-image-digests.shcheck-image-digest-freshness.yml (weekly); manual after tag bumpsDetect registry digest drift and refresh @sha256 pins and derived AzureML environment versions across tracked non-Dockerfile surfaces; excludes gh-aw lock files and test artifacts

Script parameters vary by check: Test-BinaryFreshness.ps1 uses -SarifFile and -ConfigPreview, Test-DependencyPinning.ps1 uses -Format sarif -OutputPath <path>, Test-SHAStaleness.ps1 uses -OutputFormat and -OutputPath, and update-image-digests.sh uses --check --sarif-output <path>.

check-binary-freshness.yml uses PinnedToolVersions.psm1 to discover configured tool pins without per-file workflow registration. Discovery excludes scripts/tests/Fixtures/ and *.Tests.ps1 while retaining executable test helpers.

update-image-digests.sh --check exits 0 when pins are current, 2 when image-digest or AzureML environment-version drift findings are written to SARIF, and 1 for resolution or report-generation failures. The scheduled workflow keeps drift non-gating while propagating failures.

The script resolves anonymous OCI registries, including hosts with ports. It acquires anonymous pull tokens only for Docker Hub and NGC; registries that require other authentication flows are not supported.

Run scripts/update-chart-hashes.sh locally whenever a pinned Helm chart version is updated so defaults.conf stays in sync. Likewise, run scripts/update-image-digests.sh after bumping a container image tag so the @sha256 digest pins stay in sync.

Test-DependencyPinning.ps1 -Apply rewrites tag-pinned GitHub Actions references with their resolved commit SHAs in place; run it manually to remediate pinning findings.

Test-DependencyPinning.ps1 also flags unpinned inline pip install / uv pip install commands embedded in workflow YAML and shell scripts, scanned under the shell-inline-pip type. A compliant install uses an exact == pin, a lockfile (-r/--requirement, a uv export | uv pip install pipe, or frozen uv sync), or an editable local project (-e .). To exempt an intentional non-pin, add a # pinning-ignore comment on the install line:

uv pip install "numpy>=1.26,<2.0"  # pinning-ignore

Under the docker type, the scanner flags workflow-YAML image: references that are not pinned by an immutable @sha256 digest. Submission-time templated ({{ image }}) and shell-variable references are skipped.

Under the azureml-environments type, AzureML environment: asset references require an explicit version; labels and unversioned references are mutable and rejected. Repository policy also rejects the ambiguous explicit version name latest; use a digest-derived version. Refresh digest and environment pins with scripts/update-image-digests.sh. To exempt an intentional non-pin, add a # pinning-ignore comment on the image: or environment: line, or on the line directly above it.

Under the workflow-npm-commands type, the scanner flags npm install, npm i, npm update, and npm install-test (and the npm.cmd shim) in workflow and composite-action run: steps, requiring npm ci for reproducible installs from the lockfile. Indentation-aware parsing confines detection to run: block content, so npm in step names, keys, or comments is not flagged. Add a # pinning-ignore comment on or directly above the command line to exempt an intentional non-ci install.

🔗 Related Resources​

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.