feat(build): enable npm pinning enforcement in dependency scan (#838)

## Description

Enabled **npm pinning enforcement** in the CI dependency-pinning scan
workflow. Updated the workflow default to scan
`github-actions,npm,workflow-npm-commands`, activating automatic
detection of unpinned npm commands in GitHub Actions workflow `run:`
blocks.

Three PowerShell functions were added to *Test-DependencyPinning.ps1*:

- **`Test-NpmCommandLine`** — regex-based detection of unpinned npm
commands (`npm install`, `npm i`, `npm update`, `npm install-test`)
while excluding safe variants (`npm ci`, `npm run`, `npm test`, `npm
audit`)
- **`Get-WorkflowNpmCommandViolations`** — indentation-aware YAML parser
that tracks nesting depth to confine detection to actual shell content
and avoid flagging comments
- **`New-NpmCommandViolation`** — constructs violation objects with
Medium severity and remediation guidance

Pester test coverage was added with fixture files for both safe and
unsafe npm command patterns.

### Scope Change: npm Exact-Version Enforcement

This PR introduces a **strategic departure** from SHA-pinning for npm
dependencies. Unlike GitHub Actions (which use 40-character commit SHAs
for immutable references), npm dependencies use **exact-version
enforcement** (`X.Y.Z` with no `^`, `~`, `*`, or range operators).

**Rationale for exact-version enforcement over SHA-pinning:**

| Factor | GitHub Actions (SHA) | npm (Exact Version) |
|--------|---------------------|---------------------|
| Registry model | Git repositories with mutable tags | Immutable
registry artifacts |
| Integrity verification | SHA pins to specific commit | Lockfile
integrity hashes (SHA-512) |
| Audit compatibility | N/A | `npm audit` requires semver versions |
| Reproducibility | SHA guarantees exact code | Lockfile + exact version
guarantees exact code |
| Human readability | 40-char hex strings | Semantic version numbers |

The validation regex enforces exact versions: `^\d+\.\d+\.\d+$` — no
ranges, no prefixes, no wildcards.

### Follow-Up Hardening (commit `b8bd099`)

Additional improvements shipped on this branch:

- **pip ExcludePatterns** — Virtual environment directories (`.venv`,
`venv`, `.tox`, `.nox`, `__pypackages__`) are now excluded from pip
dependency scanning to avoid false positives
- **SARIF integration tests** — Expanded from 1 weak assertion to 8
focused tests validating SARIF 2.1.0 schema compliance, severity mapping
(High→error, Medium→warning), location structure, and metadata
properties
- **Dependency pinning documentation** — New
`docs/security/dependency-pinning.md` page documenting all pinning
strategies with rationale, validation rules, CI integration flowchart,
and a dedicated comparison of SHA-pinning vs exact-version enforcement
for npm

## Related Issue(s)

Closes #526

## Type of Change

Select all that apply:

**Code & Documentation:**

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

**Infrastructure & 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`)
* [ ] Copilot skill (`.github/skills/*/SKILL.md`)

**Other:**

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

## Testing

Validated with 100 Pester tests covering:

- Detected 4 violations in multi-command fixture (install, update,
install-test, shorthand i)
- Returned zero violations for safe-only workflow (ci, run, test, audit)
- Handled nonexistent files gracefully
- Excluded commented-out commands
- Detected violations in multi-line run blocks with mixed safe/unsafe
commands
- SARIF 2.1.0 output: version, schema, tool driver, result count,
severity mapping (High→error, Medium→warning), location structure,
metadata properties (8 tests)
- pip ExcludePatterns for virtual environment directories

## Checklist

### Required Checks

* [x] Documentation is updated (if applicable)
* [x] Files follow existing naming conventions
* [x] Changes are backwards compatible (if applicable)
* [x] Tests added for new functionality (if applicable)

### Required Automated Checks

The following validation commands must pass before merging:

* [x] Markdown linting: `npm run lint:md`
* [x] Spell checking: `npm run spell-check`
* [x] Frontmatter validation: `npm run lint:frontmatter`
* [x] Skill structure validation: `npm run validate:skills`
* [x] Link validation: `npm run lint:md-links`
* [x] PowerShell analysis: `npm run lint:ps`
* [x] Plugin freshness: `npm run plugin:generate`

## Security Considerations

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

## Additional Notes

This PR enforces npm dependency pinning using exact-version enforcement
rather than SHA-pinning. The scanner uses regex-only analysis with no
code execution, and `Test-Path -LiteralPath` guards all file reads. Test
count increased from 93 to 100 with comprehensive SARIF integration
coverage.

---------

Signed-off-by: Marcel Bindseil <marcelbindseil@gmail.com>
Co-authored-by: Bill Berry <wbery@microsoft.com>
Co-authored-by: Marcel Bindseil <marcelbindseil@gmail.com>
Co-authored-by: Jordan Knight <jakkaj@gmail.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Vaughan Knight <vaughan@vaughanknight.com>

Author: 6 people

.cspell.json

@@ -23,7 +23,8 @@
     "Cargo.lock",
     "**/Cargo.lock",
     "CHANGELOG.md",
-    "logs/**"
+    "logs/**",
+    "docs/docusaurus/build/**"
   ],
   "ignoreRegExpList": [
     "/#.*/g",

.cspell/general-technical.txt

@@ -131,6 +131,7 @@ containerd
 contravariance
 coredns
 corent
+coreutils
 corosync
 cortana
 couchbase
@@ -369,6 +370,7 @@ deserialize
 deserialized
 devopsdays
 devtest
+dgst
 diego
 differenced
 dimensionality
@@ -799,6 +801,7 @@ pulsant
 pulumi
 purescale
 pyodbc
+pypackages
 pypi
 pytest
 qgis
@@ -864,6 +867,7 @@ rescaling
 resiliency
 resourcegroups
 resourceless
+retargeted
 retraining
 reuse
 reverification

.github/instructions/workflows.instructions.md

@@ -312,7 +312,7 @@ Avoid `format()` workarounds or environment variable indirection when the simple
 
 The following scripts enforce compliance:
 
-* `scripts/security/Test-DependencyPinning.ps1` - Validates SHA pinning
+* `scripts/security/Test-DependencyPinning.ps1` - Validates dependency pinning
 * `scripts/security/Test-SHAStaleness.ps1` - Checks for stale dependencies
 * `scripts/security/Test-WorkflowPermissions.ps1` - Validates workflow permissions declarations
 * `scripts/linting/Invoke-YamlLint.ps1` - Runs actionlint validation

.github/workflows/README.md

@@ -98,7 +98,7 @@ Each modular workflow implements comprehensive 4-channel result publishing:
 
 All workflows in this repository follow security best practices:
 
-### SHA Pinning
+### Dependency Pinning
 
 * All GitHub Actions use full 40-character commit SHAs
 * Comments include semantic version tags for human readability
@@ -126,7 +126,7 @@ The repository includes PowerShell scripts in `scripts/security/` for SHA pinnin
 * `Update-DockerSHAPinning.ps1` - Update Docker image SHA pins
 * `Update-ShellScriptSHAPinning.ps1` - Update shell script dependencies
 * `Test-SHAStaleness.ps1` - Check for stale SHA pins
-* `Test-DependencyPinning.ps1` - Validate SHA pinning compliance
+* `Test-DependencyPinning.ps1` - Validate dependency pinning compliance
 
 ### Dependabot Integration
 
@@ -264,7 +264,7 @@ To add a new workflow to the repository:
 
 1. Create `{tool-name}.yml` following existing patterns
 2. Implement 4-channel result publishing (annotations, artifacts, SARIF if security, summaries)
-3. Use SHA pinning for all actions
+3. Use dependency pinning for all dependencies
 4. Use minimal permissions
 5. Add soft-fail input support
 6. Update `pr-validation.yml` and `release-stable.yml` to include new job

.github/workflows/dependency-pinning-scan.yml

@@ -12,7 +12,7 @@ on:
         description: 'Comma-separated list of dependency types to check'
         required: false
         type: string
-        default: 'github-actions'
+        default: 'github-actions,npm,workflow-npm-commands'
       soft-fail:
         description: 'Whether to continue on compliance violations'
         required: false
@@ -59,7 +59,7 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Run SHA Pinning Validation
+      - name: Run Dependency Pinning Validation
         id: pinning
         shell: pwsh
         run: |
@@ -71,7 +71,6 @@ jobs:
           # Build parameter list for JSON output (always generate)
           $params = @{
             Path = '.'
-            Recursive = $true
             Format = 'json'
             OutputPath = 'logs/dependency-pinning-results.json'
           }
@@ -165,7 +164,7 @@ jobs:
           
           ### ⚠️ Action Required
           
-          **$unpinnedCount dependencies are not SHA-pinned.**
+          **$unpinnedCount dependencies are not properly pinned.**
           
           Review the warnings in the workflow log and pin dependencies to specific SHA commits.
           
@@ -175,7 +174,7 @@ jobs:
           
           ### ✅ All Dependencies Pinned
           
-          All dependencies are properly SHA-pinned.
+          All dependencies are properly pinned.
           
           "@
           })

.github/workflows/weekly-security-maintenance.yml

@@ -19,9 +19,9 @@ permissions:
   contents: read
 
 jobs:
-  # Job 1: Validate all dependencies are SHA-pinned
+    # Job 1: Validate dependency pinning
   validate-pinning:
-    name: Validate SHA Pinning Compliance
+    name: Validate Dependency Pinning Compliance
     uses: ./.github/workflows/dependency-pinning-scan.yml
     permissions:
       contents: read
@@ -81,7 +81,7 @@ jobs:
           
           | Metric | Status | Details |
           |--------|--------|---------|
-          | SHA Pinning Compliance | $(if ($unpinnedCount -eq '0') { '✅ Pass' } else { '⚠️ Warning' }) | Score: $pinningScore% |
+          | Dependency Pinning Compliance | $(if ($unpinnedCount -eq '0') { '✅ Pass' } else { '⚠️ Warning' }) | Score: $pinningScore% |
           | Unpinned Dependencies | $(if ($unpinnedCount -eq '0') { '✅ None' } else { "⚠️ $unpinnedCount found" }) | $(if ($unpinnedCount -ne '0') { 'Review warnings above' } else { 'All pinned' }) |
           | Stale SHAs (>${{ inputs.max-age-days }} days) | $(if ($staleCount -eq '0') { '✅ None' } else { "⚠️ $staleCount found" }) | $(if ($staleCount -ne '0') { 'Review warnings above' } else { 'All current' }) |
           
@@ -98,12 +98,12 @@ jobs:
           
           ## ⚠️ Action Required: Unpinned Dependencies
           
-          **$unpinnedCount dependencies are not SHA-pinned.** This is a security risk.
+          **$unpinnedCount dependencies are not properly pinned.** This is a security risk.
           
           **To fix:**
           ``````powershell
           # Review the warnings above, then pin each dependency to a SHA
-          # Example: Change 'uses: actions/checkout@v4' to 'uses: actions/checkout@71cf2267d89c5cb81562390fa70a37fa40b1305e # v4.2.2'
+          # Example: Change 'actions/checkout@v4' to 'actions/checkout@<commit-sha> # v4.2.2'
           ``````
           
           "@
@@ -151,7 +151,7 @@ jobs:
           ## ✅ All Clear!
           
           Repository security posture is excellent:
-          - All dependencies are SHA-pinned
+          - All dependencies are properly pinned
           - All SHAs are current (< ${{ inputs.max-age-days || 30 }} days old)
           - CodeQL analysis completed successfully
           - GitHub Secret Scanning and Dependabot actively monitoring

.gitleaksignore

@@ -1,5 +1,5 @@
 # False positives: fake GitHub PAT 'ghp_test123456789' used as test fixture data
-# in Pester security test files for SHA pinning and staleness validation.
+# in Pester security test files for dependency pinning and staleness validation.
 # Rule: generic-api-key
 
 # Test-SHAStaleness.Tests.ps1

docs/architecture/workflows.md

@@ -76,7 +76,7 @@ Individual validation workflows called by orchestration workflows:
 | `table-format.yml`                  | Markdown table formatting        | `npm run format:tables`             |
 | `pester-tests.yml`                  | PowerShell unit tests            | `npm run test:ps`                   |
 | `skill-validation.yml`              | Skill structure validation       | `npm run validate:skills`           |
-| `dependency-pinning-scan.yml`       | GitHub Actions pinning           | N/A (PowerShell direct)             |
+| `dependency-pinning-scan.yml`       | Dependency pinning validation    | N/A (PowerShell direct)             |
 | `sha-staleness-check.yml`           | SHA reference freshness*         | N/A (PowerShell direct)             |
 | `codeql-analysis.yml`               | CodeQL security scanning*        | N/A (GitHub native)                 |
 | `dependency-review.yml`             | Dependency vulnerability review* | N/A (GitHub native)                 |
@@ -135,7 +135,7 @@ flowchart LR
 | skill-validation         | `skill-validation.yml`        | Skill directory structure      |
 | link-lang-check          | `link-lang-check.yml`         | Link accessibility             |
 | markdown-link-check      | `markdown-link-check.yml`     | Broken links                   |
-| dependency-pinning-check | `dependency-pinning-scan.yml` | Action SHA pinning             |
+| dependency-pinning-check | `dependency-pinning-scan.yml` | Dependency pinning             |
 | npm-audit                | Inline                        | npm dependency vulnerabilities |
 | codeql                   | `codeql-analysis.yml`         | Code security patterns         |
 | copyright-headers        | `copyright-headers.yml`       | Copyright header compliance    |
@@ -200,23 +200,23 @@ When release-please creates a release, parallel jobs build the extension VSIX (`
 
 The `weekly-security-maintenance.yml` workflow runs every Sunday at 2AM UTC, providing scheduled security posture review.
 
-| Job              | Purpose                               |
-|------------------|---------------------------------------|
-| validate-pinning | Verify GitHub Actions use SHA pinning |
-| check-staleness  | Detect outdated SHA references        |
-| codeql-analysis  | Full CodeQL security scan             |
-| summary          | Aggregate security status report      |
+| Job              | Purpose                              |
+|------------------|--------------------------------------|
+| validate-pinning | Verify dependency pinning compliance |
+| check-staleness  | Detect outdated SHA references       |
+| codeql-analysis  | Full CodeQL security scan            |
+| summary          | Aggregate security status report     |
 
 ### Security Validation Tools
 
-| Tool               | Script                       | Checks                                   |
-|--------------------|------------------------------|------------------------------------------|
-| Dependency Pinning | `Test-DependencyPinning.ps1` | Actions use SHA refs, not tags           |
-| SHA Staleness      | `Test-SHAStaleness.ps1`      | SHAs reference recent commits            |
-| npm Audit          | `npm audit`                  | Known vulnerabilities in dependencies    |
-| CodeQL             | GitHub native                | Code patterns indicating security issues |
-| Gitleaks           | `gitleaks`                   | Secret detection in repository history   |
-| Dependency Review  | GitHub native                | Dependency vulnerability analysis        |
+| Tool               | Script                       | Checks                                        |
+|--------------------|------------------------------|-----------------------------------------------|
+| Dependency Pinning | `Test-DependencyPinning.ps1` | Actions use SHA refs; npm uses exact versions |
+| SHA Staleness      | `Test-SHAStaleness.ps1`      | SHAs reference recent commits                 |
+| npm Audit          | `npm audit`                  | Known vulnerabilities in dependencies         |
+| CodeQL             | GitHub native                | Code patterns indicating security issues      |
+| Gitleaks           | `gitleaks`                   | Secret detection in repository history        |
+| Dependency Review  | GitHub native                | Dependency vulnerability analysis             |
 
 ## Extension Publishing