Summary

7 of the 14 open OpenSSF Scorecard Token-Permissions alerts (alerts #8-14) flag security-events: write or contents: write on jobs that legitimately require those permissions. These were analyzed in #292 and confirmed as scanner false positives — the permissions are minimally scoped at job level and functionally required for SARIF upload or release attestation.

These alerts will persist because the permissions cannot be removed without breaking CI. This issue proposes documenting them as accepted risks to prevent recurring triage cycles.

Alert-to-Justification Matrix

Why These Are False Positives

The OpenSSF Scorecard Token-Permissions check flags any write permission grant. It cannot distinguish between:

• Overly broad permissions (genuine findings) — e.g., a job with contents: write that never uploads artifacts
• Minimally scoped required permissions (false positives) — e.g., CodeQL needs security-events: write to upload SARIF

All 7 flagged jobs use write permissions for their documented purpose. The permissions are job-scoped (not top-level), follow least-privilege within their functional scope, and are required by the GitHub Actions they invoke (github/codeql-action/upload-sarif, actions/upload-artifact, actions/attest-build-provenance).

Proposed Documentation

1. Security documentation (docs/security/)

Add a section or page documenting the accepted risk rationale per alert category, including:

• Which alerts are accepted risks and why
• The analysis from [Issue]: Residual OpenSSF Scorecard Token-Permissions fixes from #182 #292 establishing the false-positive determination
• How to verify the permissions are still minimally scoped

2. Inline workflow comments

Add comments above each write permission block in the affected workflow files:

# Required: security-events:write needed by github/codeql-action/upload-sarif
# Accepted risk per OpenSSF Scorecard alert #NN — see docs/security/
security-events: write

This prevents future contributors from opening duplicate issues or attempting to remove the permissions.

Acceptance Criteria

• A page or section in docs/security/ documents all 7 alerts as accepted risks with justification
• All 7 affected workflow jobs have inline YAML comments above their write permission lines
• [Issue]: Residual OpenSSF Scorecard Token-Permissions fixes from #182 #292 is referenced as the original analysis source
• Future maintainers can find the rationale without searching closed issues

References

• Alerts: https://github.com/microsoft/hve-core/security/code-scanning/8 through https://github.com/microsoft/hve-core/security/code-scanning/14
• Original analysis: [Issue]: Residual OpenSSF Scorecard Token-Permissions fixes from #182 #292 (confirmed false-positive determination)
• Predecessor: chore(build): Clean up GitHub Actions workflow permissions for OpenSSF Scorecard compliance #182 (initial permissions cleanup)
• Related: fix(build): add top-level permissions to copilot-setup-steps.yml for OpenSSF Scorecard compliance #456 (the one genuine Token-Permissions fix — copilot-setup-steps.yml)

How to Build This

This is a documentation and inline commenting task using the task-implementor workflow.

Workflow: /task-research → /task-plan → /task-implement → /task-review

Phase 1: Research

Source Material

• This issue body
• #file:docs/security/threat-model.md (existing security documentation)
• #file:docs/security/README.md (security docs index)
• #file:.github/workflows/main.yml (alerts Add NPM/Node.js dependencies and configuration #8, Add security scanning scripts #9: contents:write and security-events:write)
• #file:.github/workflows/pr-validation.yml (alerts Add linting and validation scripts #10, Add GitHub Copilot chat modes #11)
• #file:.github/workflows/security-scan.yml (alert Add GitHub Copilot instruction files #12)
• #file:.github/workflows/weekly-security-maintenance.yml (alerts Add GitHub metadata, templates, and MCP configuration #13, Add validation reusable workflows #14)
• #file:.github/instructions/markdown.instructions.md (documentation conventions)

Steps

1. Type /clear to start a fresh context.
2. Attach or open the files listed above.
3. Copy and run this prompt:

/task-research topic="documenting accepted OpenSSF Scorecard Token-Permissions risks"

Research how to document the 7 accepted Token-Permissions risks. Investigate:

1. The current docs/security/ structure and where accepted risk documentation fits
2. The existing threat-model.md content and whether a new page or a new section is more appropriate
3. The exact permission lines in each of the 4 affected workflow files (find the specific
   YAML blocks with security-events: write and contents: write)
4. How other Microsoft repos document accepted security scanner findings
5. The analysis from #292 that established the false-positive determination
6. Inline YAML comment conventions used elsewhere in the repository workflows
7. Whether a structured table format or narrative format better serves future maintainers

Output: Research document at .copilot-tracking/research/{{YYYY-MM-DD}}-token-permissions-docs-research.md

Phase 2: Plan

Source Material

• Research document from Phase 1

Steps

1. Type /clear to start a fresh context.
2. Open the research document from Phase 1.
3. Copy and run this prompt:

/task-plan

Create an implementation plan for documenting the accepted Token-Permissions risks.
The plan should cover the new security documentation page or section, inline YAML
comments for all 7 affected permission blocks across 4 workflow files, and cross-references
to #292 for the original analysis.

Output: Plan at .copilot-tracking/plans/ and details at .copilot-tracking/details/

Phase 3: Implement

Source Material

• Plan from Phase 2

Steps

1. Type /clear to start a fresh context.
2. Open the plan document from Phase 2.
3. Copy and run this prompt:

/task-implement

Implement the Token-Permissions documentation following the plan. Create or update
the security documentation with accepted risk rationale, and add inline YAML comments
above each write permission block in the 4 affected workflow files.

Output: New/modified documentation and workflow files, changes log at .copilot-tracking/changes/

Phase 4: Review

Source Material

• Plan from Phase 2
• Changes log from Phase 3

Steps

1. Type /clear to start a fresh context.
2. Open the plan and changes log.
3. Copy and run this prompt:

/task-review

Review the Token-Permissions documentation. Run these validation commands:
- npm run lint:md (markdown linting for documentation changes)
- npm run lint:yaml (validate modified workflow files)
Verify all 7 alerts are documented with justification, inline comments reference
the documentation page, #292 is cited as the analysis source, and the documentation
helps future maintainers find rationale without searching closed issues.

Output: Review log at .copilot-tracking/reviews/

After Review

• Pass: All criteria met. Create a PR referencing this issue.
• Iterate: Review found issues. Run /clear, return to Phase 3 with the review feedback.
• Escalate: Fundamental design issue discovered. Run /clear, return to Phase 1 to research the gap.

Authoring Standards

• Documentation follows .github/instructions/markdown.instructions.md
• Writing style follows .github/instructions/writing-style.instructions.md
• Inline YAML comments are brief and reference the documentation page
• Tables use aligned pipes with leading and trailing pipes

Success Criteria

• Security documentation page or section covers all 7 alerts with justification
• All 7 affected workflow permission blocks have inline YAML comments
• [Issue]: Residual OpenSSF Scorecard Token-Permissions fixes from #182 #292 is referenced as the original analysis source
• Documentation is discoverable without searching closed issues
• npm run lint:md passes
• npm run lint:yaml passes