Skip to content

docs(security): add security assurance case and threat model for OSSF Silver#259

Merged
WilliamBerryiii merged 19 commits intomainfrom
docs/issue-244-security-threat-model
Jan 27, 2026
Merged

docs(security): add security assurance case and threat model for OSSF Silver#259
WilliamBerryiii merged 19 commits intomainfrom
docs/issue-244-security-threat-model

Conversation

@WilliamBerryiii
Copy link
Copy Markdown
Member

@WilliamBerryiii WilliamBerryiii commented Jan 23, 2026

Summary

Adds comprehensive security threat model documentation for OSSF Silver badge compliance, aligned with GitHub's defensive architecture principles.

Closes #244

Changes

This PR adds 5 files:

Security Documentation

  • docs/security/threat-model.md - Comprehensive threat model with 36 threats (STRIDE + AI-specific + RAI), 18+ controls, and MCP server trust analysis
  • docs/security/README.md - Security documentation index
  • SECURITY.md - Added link to new security documentation

Bug Fixes

  • scripts/linting/Validate-MarkdownFrontmatter.ps1 - Fixed repo-relative path detection for template exclusion; updated comment wording for clarity
  • .github/workflows/pester-tests.yml - Updated Pester from 5.6.1 to 5.7.1 to resolve PSGallery availability issues

Threat Model Highlights

  • 36 identified threats across STRIDE categories, AI/ML-specific risks, and Responsible AI concerns
  • 18+ security controls mapped to threats with implementation guidance
  • MCP server trust boundaries - Analysis of ADO, GitHub, Microsoft Docs, and Context7 integrations
  • Data flow diagrams - Mermaid-based visualization of system boundaries

Testing

  • ✅ All linting passes (npm run lint)
  • ✅ All 338 Pester tests pass (npm run test:ps)
  • ✅ Frontmatter validation passes with template exclusion fix

@WilliamBerryiii WilliamBerryiii requested a review from a team as a code owner January 23, 2026 22:12
Copilot AI review requested due to automatic review settings January 23, 2026 22:12
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Jan 23, 2026

Dependency Review

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

Scanned Files

None

@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented Jan 23, 2026

Codecov Report

❌ Patch coverage is 46.15385% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 37.31%. Comparing base (d8337b8) to head (dacea3d).

Files with missing lines Patch % Lines
scripts/linting/Validate-MarkdownFrontmatter.ps1 0.00% 7 Missing ⚠️
Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main     #259      +/-   ##
==========================================
- Coverage   38.21%   37.31%   -0.91%     
==========================================
  Files          15       15              
  Lines        2805     2814       +9     
==========================================
- Hits         1072     1050      -22     
- Misses       1733     1764      +31     
Flag Coverage Δ
pester 37.31% <46.15%> (-0.91%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
scripts/linting/Modules/FrontmatterValidation.psm1 96.22% <100.00%> (+0.04%) ⬆️
scripts/linting/Validate-MarkdownFrontmatter.ps1 61.86% <0.00%> (-13.38%) ⬇️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds security and architecture documentation to support OpenSSF Best Practices Silver assurance_case compliance, and adjusts frontmatter validation behavior to better scope “docs” rules.

Changes:

  • Added a comprehensive security assurance case and threat model under docs/security/.
  • Added new architecture documentation covering workflows, testing, and AI artifact structure under docs/architecture/.
  • Updated Validate-MarkdownFrontmatter.ps1 to use centralized file-type detection when applying docs-specific frontmatter rules.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
scripts/linting/Validate-MarkdownFrontmatter.ps1 Refines docs-file classification usage for frontmatter rule application.
docs/security/threat-model.md Introduces the primary assurance case and threat model content for OSSF Silver.
docs/security/README.md Adds a security documentation index and entry points to the threat model and SECURITY.md.
docs/architecture/workflows.md Documents the GitHub Actions workflow architecture and validation job inventory.
docs/architecture/testing.md Documents the Pester test structure, configuration, and coverage targets.
docs/architecture/ai-artifacts.md Documents the prompts/agents/instructions/skills artifact architecture and contracts.
docs/architecture/README.md Adds an architecture landing page summarizing major subsystems and relationships.
docs/README.md Adds/updates the docs landing page to link into architecture and other doc areas.
README.md Updates the repo’s top-level positioning and structure overview to match current scope.

Copilot AI review requested due to automatic review settings January 23, 2026 23:11
@WilliamBerryiii
Copy link
Copy Markdown
Member Author

@sharonfinden - tagging you, if you have a chance to review, or if you want to bring others to the party ... I would appreciate it.

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Copilot AI review requested due to automatic review settings January 23, 2026 23:40
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

… Silver

- add comprehensive threat model with 36 threats across STRIDE, AI, and RAI categories
- document trust boundaries and security inheritance from GitHub Copilot
- include MCP server trust analysis with risk classifications
- add GSN-style assurance argument with evidence mapping
- create security documentation directory with README index

Closes #244
📋 - Generated by Copilot
…ocused

- update README.md overview to emphasize defense-in-depth practices
- revise threat-model.md description to focus on enterprise security
- replace OSSF keyword with defense-in-depth

📝 - Generated by Copilot
- add Dev Container Environment trust boundary
- add DC-1 feature tag substitution attack threat
- add DC-2 lifecycle script tampering threat
- add DC-3 external binary download compromise threat
- update TOC to include dev container threats section

🛡️ - Generated by Copilot
…lows

- replace ASCII art with Mermaid flowchart for better rendering
- add LLM API Service as explicit network boundary
- fix MCP server direction to bidirectional tool calls
- add Dev Container to diagram
- show artifacts read into Copilot context correctly

📊 - Generated by Copilot
- fix URL language paths (remove /en-us/ from Microsoft links)
- add inline links for STRIDE, OWASP LLM Top 10, MITRE ATLAS
- replace gitleaks references with GitHub secret scanning (accurate)
- add Microsoft Docs MCP to threat model server analysis
- clarify GitHub MCP is default, others recommended
- fix README.md sentence fragment
- fix path detection in Validate-MarkdownFrontmatter.ps1
- format markdown tables

🔧 - Generated by Copilot
- Pester 5.6.1 appears unlisted from PSGallery
- 5.7.1 is current stable and passes all 338 tests

🔧 - Generated by Copilot
- Change tool-checksums.json to scripts/security/tool-checksums.json
- Add clarifying comment for IsDocsFile flag usage
- Add Security Documentation section to SECURITY.md with link to docs/security/

🔧 - Generated by Copilot
Copilot AI review requested due to automatic review settings January 24, 2026 00:23
@WilliamBerryiii WilliamBerryiii force-pushed the docs/issue-244-security-threat-model branch from 097c012 to b93e5dc Compare January 24, 2026 00:23
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

…t classification

- remove duplicate Import-Module FrontmatterValidation.psm1 that conflicts with using module
- add IsAgent classification for *.agent.md files in Get-FileTypeInfo

🔧 - Generated by Copilot
- Replace PSObject.Methods with GetType().GetMethod() for class method check
- Add diagnostic message showing type name on validation failure

🐛 - Generated by Copilot
Copilot AI review requested due to automatic review settings January 26, 2026 23:26
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

- add standard Copilot footers to docs/security/README.md and threat-model.md

- remove duplicate Get-FileTypeInfo from Validate-MarkdownFrontmatter.ps1

🔧 - Generated by Copilot
- extract ValidationSummary from array when pipeline outputs multiple objects

- add null-safe check before TotalFiles access in ChangedFilesOnly mode

🔧 - Generated by Copilot
Copilot AI review requested due to automatic review settings January 26, 2026 23:54
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

…ation

- update Test-OptionalDocsFields to check IList and IEnumerable interfaces
- resolve false positives on files with valid YAML list keywords

🐛 - Generated by Copilot
@WilliamBerryiii WilliamBerryiii merged commit a390e26 into main Jan 27, 2026
16 checks passed
@WilliamBerryiii WilliamBerryiii deleted the docs/issue-244-security-threat-model branch January 27, 2026 00:36
WilliamBerryiii pushed a commit that referenced this pull request Jan 28, 2026
🤖 I have created a release *beep* *boop*
---


##
[2.0.0](hve-core-v1.1.0...hve-core-v2.0.0)
(2026-01-28)


### ⚠ BREAKING CHANGES

* **agents:** add Task Reviewer and expand RPI to 4-phase workflow
([#277](#277))

### ✨ Features

* **agents:** add hve-core-installer agent to extension package
([#297](#297))
([c0e48c6](c0e48c6))
* **agents:** add Task Reviewer and expand RPI to 4-phase workflow
([#277](#277))
([ae76cab](ae76cab))
* **build:** add code coverage reporting to Pester workflow
([#230](#230))
([a34822a](a34822a))
* **docs:** add GOVERNANCE.md for OSSF Silver Badge compliance
([#235](#235))
([b0e752c](b0e752c))
* **docs:** add ROADMAP.md for OSSF Silver badge compliance
([#238](#238))
([4a41c16](4a41c16))
* **mcp:** add MCP server configuration guidance and installer
enhancements ([#225](#225))
([0bce418](0bce418))
* **scripts:** add YAML linting with actionlint
([#234](#234))
([d9301f9](d9301f9))
* **security:** add OpenSSF Scorecard workflow and badge
([#271](#271))
([7c6d788](7c6d788))
* **skills:** add video-to-gif conversion skill with FFmpeg two-pass
optimization ([#247](#247))
([8d65c42](8d65c42))
* **tests:** add Pester tests for LintingHelpers and
Validate-MarkdownFrontmatter
([#197](#197),
[#198](#198))
([#205](#205))
([51ae563](51ae563))


### 🐛 Bug Fixes

* **build:** detect table formatting changes via git diff
([#261](#261))
([985eee0](985eee0))
* **build:** disable MD024 lint rule in CHANGELOG for release-please
([#220](#220))
([971df94](971df94))
* **build:** quote shell variables and group redirects in workflow files
([#299](#299))
([3372509](3372509))
* **build:** resolve scorecard badge and workflow security issues
([#301](#301))
([aeaed13](aeaed13))
* **extension:** remove frontmatter from README and exclude from
markdown linting
([#223](#223))
([4272529](4272529))
* **instructions:** quote applyTo glob pattern for YAML compatibility
([#216](#216))
([085199c](085199c))
* **scripts:** add FooterExcludePaths parameter to frontmatter
validation ([#334](#334))
([64db98d](64db98d))
* **scripts:** add GHSA word and logs/ exclusion to cspell config
([#214](#214))
([5c99b3f](5c99b3f))
* **scripts:** correct type assertions in Invoke-YamlLint.Tests.ps1
([#332](#332))
([af7050d](af7050d))
* **scripts:** eliminate false positives in dependency pinning npm
pattern ([#273](#273))
([ccbdfa3](ccbdfa3))
* **security:** add artifact attestation for signed releases
([#257](#257))
([c52d6e2](c52d6e2))
* standardize markdown footers and complete frontmatter
([#217](#217))
([b4e7556](b4e7556))


### 📚 Documentation

* add OpenSSF Best Practices Passing badge to README
([#239](#239))
([91bc529](91bc529))
* **architecture:** add architecture documentation and value proposition
([#252](#252))
([0e4b02f](0e4b02f))
* **contributing:** add testing requirements for OSSF compliance
([#254](#254))
([4db1a18](4db1a18))
* **docs:** add enterprise status badges to README header
([#270](#270))
([ccb68a4](ccb68a4))
* **security:** add security assurance case and threat model for OSSF
Silver ([#259](#259))
([a390e26](a390e26))


### ♻️ Refactoring

* **application:** wrap execution with try blocks, ensure proper …
([#296](#296))
([35c4417](35c4417))
* **scripts:** extract frontmatter validation to testable module
([#293](#293))
([4e8707e](4e8707e))
* **scripts:** extract pure functions for Pester testability
([#221](#221))
([d40e742](d40e742))


### 🔧 Maintenance

* **deps-dev:** bump cspell from 9.4.0 to 9.6.0 in the npm-dependencies
group ([#208](#208))
([855914b](855914b))
* **deps-dev:** bump cspell from 9.6.0 to 9.6.1 in the npm-dependencies
group ([#294](#294))
([1e45ad6](1e45ad6))
* **deps:** bump actions/setup-node from 6.1.0 to 6.2.0 in the
github-actions group
([#209](#209))
([c4c69e2](c4c69e2))
* **deps:** bump the github-actions group with 4 updates
([#295](#295))
([d8337b8](d8337b8))
* remove step-security/harden-runner from workflows
([#246](#246))
([c5708d8](c5708d8))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

Co-authored-by: hve-core-release-please[bot] <254602402+hve-core-release-please[bot]@users.noreply.github.com>
@ashtmMSFT
Copy link
Copy Markdown

Already merged so I can't give a proper checkmark, but I reviewed and LGTM 👍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Create security assurance case and threat model for OSSF Silver badge compliance

5 participants