feat(workflows): add gitleaks binary-based secret scanning as PR gate

[WilliamBerryiii]

Description

This PR introduces gitleaks as a binary-based secret scanning gate across both CI pipelines, complementing GitHub's native secret scanning with a locally verified, SHA-pinned binary that produces SARIF output for the Security tab.

The branch addresses #260 by creating a reusable workflow that downloads, verifies, and runs gitleaks as part of every PR validation and main-branch push.

Gitleaks Reusable Workflow

A new gitleaks-scan.yml reusable workflow was created with three configurable inputs: soft-fail, upload-sarif, and upload-artifact. The workflow downloads gitleaks v8.30.0, verifies the tarball against a pinned SHA256 checksum, and runs a full-repository scan in git mode. SARIF output at logs/gitleaks-results.sarif integrates with GitHub's Security tab via github/codeql-action/upload-sarif.

• Exit code handling distinguishes clean scans (0), detected secrets (1, respects soft-fail), and unexpected errors
• A .gitleaksignore file is respected when present for suppressing known findings
• Job summary table displays scan status directly in the Actions UI
• All third-party actions are pinned to full SHA with version comments

Pipeline Integration

Both pr-validation.yml and main.yml now call the reusable workflow with soft-fail: false and upload-sarif: true. The PR pipeline disables artifact upload to reduce storage noise, while the main pipeline retains artifacts for 90 days. The main pipeline's aggregation gate job depends on gitleaks-scan completing successfully.

Threat Model Documentation

The security threat model was updated to reflect expanded coverage. VM-2 now references both GitHub native scanning and the gitleaks PR gate. The workflow coverage table includes a new main.yml row and lists gitleaks as a security check for both pipelines.

Related Issue(s)

Closes #260

Type of Change

Select all that apply:

Code & 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)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• 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)

Note for AI Artifact Contributors:

• 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.
• Skills: Must include both bash and PowerShell scripts. See Skills.
• 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.
• See Agents Not Accepted and Model Version Requirements.

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Sample Prompts (for AI Artifact Contributions)

User Request:

Execution Flow:

Output Artifacts:

Success Indicators:

For detailed contribution requirements, see:

• Common Standards: docs/contributing/ai-artifacts-common.md - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
• Agents: docs/contributing/custom-agents.md - Agent configurations with tools and behavior patterns
• Prompts: docs/contributing/prompts.md - Workflow-specific guidance with template variables
• Instructions: docs/contributing/instructions.md - Technology-specific standards with glob patterns
• Skills: docs/contributing/skills.md - Task execution utilities with cross-platform scripts

Testing

Automated Validations

Command	Status
npm run lint:md	Passed
npm run spell-check	Passed
npm run lint:frontmatter	Passed
npm run validate:skills	Passed
npm run lint:md-links	Passed (12 pre-existing broken links in unrelated files)
npm run lint:ps	Passed
npm run lint:yaml	Passed
npm run lint:version-consistency	Passed
npm run plugin:generate	Passed (no diff)

Diff-Based Assessment

• All third-party actions verified as SHA-pinned with version comments
• persist-credentials: false confirmed on checkout step
• Permissions scoped to minimum required (contents: read, security-events: write)
• Binary download verified via SHA256 checksum before execution
• No secrets or sensitive data present in the diff

Manual Testing

Manual testing was not performed. Workflow execution validates on PR creation and main-branch push.

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (N/A — GitHub Actions workflows are validated by pipeline execution)

AI Artifact Contributions

• Used /prompt-analyze to review contribution
• Addressed all feedback from prompt-builder review
• Verified contribution follows common standards and type-specific requirements

Required Automated Checks

The following validation commands must pass before merging:

• Markdown linting: npm run lint:md
• Spell checking: npm run spell-check
• Frontmatter validation: npm run lint:frontmatter
• Skill structure validation: npm run validate:skills
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps
• YAML/actionlint validation: npm run lint:yaml
• Action version consistency: npm run lint:version-consistency
• Plugin freshness: npm run plugin:generate

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues (N/A — no dependency changes)
• Security-related scripts follow the principle of least privilege (N/A — no security scripts modified)

Additional Notes

The gitleaks workflow respects a .gitleaksignore file when present, allowing suppression of known findings. No .gitleaksignore currently exists in the repository. If pre-existing secrets are detected during the first pipeline run, create a .gitleaksignore at the repository root with the finding fingerprints to suppress them.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

OpenSSF Scorecard

Package	Version	Score	Details
actions/actions/checkout	de0fac2e4500dabe0009e67214ff5f5447ce83dd	🟢 6.2	Details Check Score Reason Maintained 🟢 4 5 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 4 Code-Review 🟢 10 all changesets reviewed CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected Dangerous-Workflow 🟢 10 no dangerous workflow patterns detected Binary-Artifacts 🟢 10 no binaries found in the repo License 🟢 10 license file detected Fuzzing ⚠️ 0 project is not fuzzed Packaging ⚠️ -1 packaging workflow not detected Token-Permissions ⚠️ 0 detected GitHub workflow tokens with excessive permissions Signed-Releases ⚠️ -1 no releases found Pinned-Dependencies 🟢 3 dependency not pinned by hash detected -- score normalized to 3 Security-Policy 🟢 9 security policy file detected Branch-Protection 🟢 6 branch protection is not maximal on development and all release branches SAST 🟢 8 SAST tool detected but not run on all commits
actions/actions/upload-artifact	b7c566a772e6b6bfb58ed0dc250532a479d7789f	🟢 6.2	Details Check Score Reason Code-Review 🟢 10 all changesets reviewed Dangerous-Workflow 🟢 10 no dangerous workflow patterns detected Maintained 🟢 10 27 commit(s) and 1 issue activity found in the last 90 days -- score normalized to 10 Packaging ⚠️ -1 packaging workflow not detected CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected Token-Permissions ⚠️ 0 detected GitHub workflow tokens with excessive permissions Binary-Artifacts 🟢 10 no binaries found in the repo Fuzzing ⚠️ 0 project is not fuzzed License 🟢 10 license file detected Pinned-Dependencies ⚠️ 1 dependency not pinned by hash detected -- score normalized to 1 Signed-Releases ⚠️ -1 no releases found Security-Policy 🟢 9 security policy file detected Branch-Protection ⚠️ 0 branch protection not enabled on development/release branches SAST 🟢 10 SAST tool is run on all commits
actions/github/codeql-action/upload-sarif	ce729e4d353d580e6cacd6a8cf2921b72e5e310a	Unknown	Unknown

Scanned Files

• .github/workflows/gitleaks-scan.yml

[github-advanced-security]

This pull request sets up GitHub code scanning for this repository. Once the scans have completed and the checks have passed, the analysis results for this pull request branch will appear on this overview. Once you merge this pull request, the 'Security' tab will show more code scanning analysis results (for example, for the default branch). Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results. For more information about GitHub code scanning, check out the documentation.