fix(security): add artifact attestation for signed releases (#257)

WilliamBerryiii · web-flow · commit c52d6e268f8e · 2026-01-24T16:28:26.000-08:00
## Description

Add GitHub Artifact Attestations to the release workflow, enabling
cryptographic signing of VSIX release artifacts using Sigstore. This
satisfies the OSSF Best Practices `signed_releases` criterion by
establishing verifiable build provenance.

- Added `attest-and-upload` job to `main.yml` that downloads the VSIX
artifact, attests it with Sigstore, and uploads it to the GitHub Release
- Configured OIDC permissions (`id-token: write`, `attestations: write`,
`contents: write`) for Sigstore integration
- Documented verification process in SECURITY.md with GitHub CLI
commands

## Related Issue(s)

Related to OSSF Silver badge requirements for signed releases.

## Type of Change

Select all that apply:

**Code &amp; Documentation:**

- [ ] Bug fix (non-breaking change fixing an issue)
- [ ] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to
change)
- [x] Documentation update

**Infrastructure &amp; Configuration:**

- [x] GitHub Actions workflow
- [ ] Linting configuration (markdown, PowerShell, etc.)
- [x] Security configuration
- [ ] DevContainer configuration
- [ ] Dependency update

**AI Artifacts:**

- [ ] Reviewed contribution with `prompt-builder` agent and addressed
all feedback
- [ ] Copilot instructions (`.github/instructions/*.instructions.md`)
- [ ] Copilot prompt (`.github/prompts/*.prompt.md`)
- [ ] Copilot agent (`.github/agents/*.agent.md`)

&gt; **Note for AI Artifact Contributors**:
&gt;
&gt; - **Agents**: Research, indexing/referencing other project (using
standard VS Code GitHub Copilot/MCP tools), planning, and general
implementation agents likely already exist. Review `.github/agents/`
before creating new ones.
&gt; - **Model Versions**: Only contributions targeting the **latest
Anthropic and OpenAI models** will be accepted. Older model versions
(e.g., GPT-3.5, Claude 3) will be rejected.
&gt; - See [Agents Not
Accepted](../docs/contributing/custom-agents.md#agents-not-accepted) and
[Model Version
Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements).

**Other:**

- [ ] Script/automation (`.ps1`, `.sh`, `.py`)
- [ ] Other (please describe):

## Sample Prompts (for AI Artifact Contributions)

N/A - This PR does not include AI artifact contributions.

## Testing

- Validated workflow YAML syntax
- Verified action SHA pinning follows repository conventions
- Ran `npm run lint:md` and `npm run lint:frontmatter` (passed)

## Checklist

### Required Checks

- [x] Documentation is updated (if applicable)
- [x] Files follow existing naming conventions
- [x] Changes are backwards compatible (if applicable)

### AI Artifact Contributions

N/A

### Required Automated Checks

The following validation commands must pass before merging:

- [x] Markdown linting: `npm run lint:md`
- [ ] Spell checking: `npm run spell-check`
- [x] Frontmatter validation: `npm run lint:frontmatter`
- [ ] Link validation: `npm run lint:md-links`
- [ ] PowerShell analysis: `npm run lint:ps`

## Security Considerations

- [x] This PR does not contain any sensitive or NDA information
- [ ] Any new dependencies have been reviewed for security issues
- [x] Security-related scripts follow the principle of least privilege

## Additional Notes

The `attest-and-upload` job runs only when `release_created == 'true'`,
ensuring attestation occurs only for actual releases. Actions use SHA
pinning per repository conventions:

- `actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16`
(v4.1.8)
-
`actions/attest-build-provenance@c074443f1aee8d4aeeae555aebba3282517141b2`
(v2.2.3)

🔒 - Generated by Copilot
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -58,28 +58,13 @@ jobs:
       changed-files-only: false
       code-coverage: true
 
-  extension-package:
-    name: Package VS Code Extension
-    needs:
-      - spell-check
-      - markdown-lint
-      - table-format
-      - dependency-pinning-scan
-      - pester-tests
-    uses: ./.github/workflows/extension-package.yml
-    with:
-      dev-patch-number: ${{ github.run_number }}
-    permissions:
-      contents: read
-
   release-please:
     name: Release Please
     needs:
       - spell-check
       - markdown-lint
       - table-format
       - dependency-pinning-scan
-      - extension-package
       - pester-tests
     runs-on: ubuntu-latest
     outputs:
@@ -106,3 +91,45 @@ jobs:
           token: ${{ steps.app-token.outputs.token }}
           config-file: release-please-config.json
           manifest-file: .release-please-manifest.json
+
+  extension-package-release:
+    name: Package VS Code Extension (Release)
+    needs: [release-please]
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    uses: ./.github/workflows/extension-package.yml
+    with:
+      version: ${{ needs.release-please.outputs.version }}
+    permissions:
+      contents: read
+
+  attest-and-upload:
+    name: Attest and Upload Release Assets
+    needs: [release-please, extension-package-release]
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+      attestations: write
+    steps:
+      - name: Download VSIX artifact
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: extension-vsix
+          path: ./dist
+
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@c074443f1aee8d4aeeae555aebba3282517141b2 # v2.2.3
+        with:
+          subject-path: 'dist/*.vsix'
+
+      - name: Upload VSIX to GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          VSIX_FILE=$(find dist -name '*.vsix' | head -1)
+          if [ -z "$VSIX_FILE" ]; then
+            echo "::error::No VSIX file found in dist/"
+            exit 1
+          fi
+          gh release upload "${{ needs.release-please.outputs.tag_name }}" "$VSIX_FILE" --clobber -R "${{ github.repository }}"
diff --git a/SECURITY.md b/SECURITY.md
@@ -53,6 +53,48 @@ Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https:
 
 <!-- END MICROSOFT SECURITY.MD BLOCK -->
 
+## Verifying Release Integrity
+
+HVE Core releases are cryptographically signed using GitHub Artifact Attestations. This establishes provenance and allows you to verify that release artifacts were built from this repository's official CI/CD pipeline.
+
+### Verification Steps
+
+1. Install the GitHub CLI if not already available:
+
+   ```bash
+   # Windows (winget)
+   winget install GitHub.cli
+
+   # macOS (Homebrew)
+   brew install gh
+   ```
+
+2. Download the release artifact (replace `<version>` with the release tag, e.g., `v1.2.0`):
+
+   ```bash
+   gh release download <version> -R microsoft/hve-core -p '*.vsix'
+   ```
+
+3. Verify the attestation:
+
+   ```bash
+   gh attestation verify hve-core-<version>.vsix -R microsoft/hve-core
+   ```
+
+A successful verification confirms:
+
+* The artifact was built from the microsoft/hve-core repository
+* The build occurred in GitHub Actions
+* The artifact has not been modified since signing
+
+### What Gets Signed
+
+| Artifact               | Channel         | Signed                |
+|------------------------|-----------------|-----------------------|
+| VSIX extension package | GitHub Releases | Yes                   |
+| VS Code Marketplace    | Stable          | Marketplace signature |
+| VS Code Marketplace    | Pre-Release     | Marketplace signature |
+
 ---
 
 🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.
diff --git a/docs/architecture/workflows.md b/docs/architecture/workflows.md
@@ -126,29 +126,29 @@ The `main.yml` workflow runs after merges to main, performing validation and rel
 
 ```mermaid
 flowchart LR
-    V1[spell-check] --> PKG[extension-package]
-    V2[markdown-lint] --> PKG
-    V3[table-format] --> PKG
-    V4[dependency-pinning-scan] --> PKG
-    V1 --> RP[release-please]
-    V2 --> RP
-    V3 --> RP
-    V4 --> RP
-    PKG --> RP
+    V1[spell-check] --> RP[release-please]
+    V2[markdown-lint] --> RP
+    V3[table-format] --> RP
+    V4[dependency-pinning-scan] --> RP
+    V5[pester-tests] --> RP
+    RP -->|release_created| PKG[extension-package-release]
+    PKG --> ATT[attest-and-upload]
 ```
 
 ### Main Branch Jobs
 
-| Job                     | Purpose                        | Dependencies        |
-|-------------------------|--------------------------------|---------------------|
-| spell-check             | Post-merge spelling validation | None                |
-| markdown-lint           | Post-merge markdown validation | None                |
-| table-format            | Post-merge table validation    | None                |
-| dependency-pinning-scan | Security pinning check         | None                |
-| extension-package       | Build VS Code extension VSIX   | All validation jobs |
-| release-please          | Automated release management   | All jobs            |
-
-The release-please job creates release PRs and tags based on conventional commits.
+| Job                       | Purpose                        | Dependencies                 |
+|---------------------------|--------------------------------|------------------------------|
+| spell-check               | Post-merge spelling validation | None                         |
+| markdown-lint             | Post-merge markdown validation | None                         |
+| table-format              | Post-merge table validation    | None                         |
+| dependency-pinning-scan   | Security pinning check         | None                         |
+| pester-tests              | PowerShell unit tests          | None                         |
+| release-please            | Automated release management   | All validation jobs          |
+| extension-package-release | Build release VSIX             | release-please (conditional) |
+| attest-and-upload         | Sign and upload VSIX           | extension-package-release    |
+
+When release-please creates a release, the `extension-package-release` job builds the VSIX with the correct version, and `attest-and-upload` signs it with Sigstore attestation before uploading to the GitHub Release.
 
 ## Security Workflows
 
diff --git a/scripts/security/Update-ActionSHAPinning.ps1 b/scripts/security/Update-ActionSHAPinning.ps1
@@ -242,8 +242,10 @@ $ActionSHAMap = @{
     "actions/cache@v3"                     = "actions/cache@88522ab9f39a2ea568f7027eddc7d8d8bc9d59c8" # v3.3.1
     "actions/upload-artifact@v4"           = "actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808" # v4.3.6
     "actions/upload-artifact@v3"           = "actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3" # v3.1.3
+    "actions/download-artifact@v7"         = "actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131" # v7.0.0
     "actions/download-artifact@v4"         = "actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16" # v4.1.8
     "actions/download-artifact@v3"         = "actions/download-artifact@9bc31d5ccc31df68ecc42ccf4149144866c47d8a" # v3.0.2
+    "actions/attest-build-provenance@v2"   = "actions/attest-build-provenance@c074443f1aee8d4aeeae555aebba3282517141b2" # v2.2.3
     "github/super-linter@v6"               = "github/super-linter@4ac6c1e9bce95c4e5e456c8c2c6b468998248097" # v6.8.0
     "github/super-linter@v5"               = "github/super-linter@45fc0d88288beee4701c62761281edfee85655d7" # v5.7.2
     "hashicorp/setup-terraform@v3"         = "hashicorp/setup-terraform@651471c36a6092792c552e8b1bef71e592b462d8" # v3.1.1
