Add comprehensive documentation for PowerShell architecture, security, and development - #27714
Open
Travis Plunk (TravisEz13) wants to merge 5 commits into
Open
Add comprehensive documentation for PowerShell architecture, security, and development#27714Travis Plunk (TravisEz13) wants to merge 5 commits into
Travis Plunk (TravisEz13) wants to merge 5 commits into
Conversation
Copy link
Copy Markdown
Member
Sorry, something went wrong.
…, and development - Introduced AGENTS.md for an overview of the PowerShell service and repo. - Added API_SURFACE.md detailing cmdlet and .NET hosting API surfaces. - Created ARCHITECTURE.md to explain PowerShell's internal structure and components. - Documented BUSINESS_LOGIC.md outlining command execution models and language semantics. - Added DEPENDENCIES.md listing .NET runtime, NuGet packages, and native components. - Created DEV_GUIDE.md for building, testing, and contributing to PowerShell. - Introduced ERROR_HANDLING.md to describe the error model and handling practices. - Added SECURITY.md detailing security concerns, boundaries, and reporting vulnerabilities. - Updated existing SECURITY.md to reflect new security guidelines and reporting processes.
Copy link
Copy Markdown
|
Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run. |
Sorry, something went wrong.
Copy link
Copy Markdown
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new set of engineering-focused documentation intended to centralize architectural, API-surface, dependency, development, error-handling, and security-boundary information for the PowerShell codebase, and links it from the repository security reporting page.
Changes:
- Introduces a top-level documentation index (AGENTS.md) and several new docs/*.md engineering reference documents (architecture, API surface, business logic, dependencies, dev guide, error model, security).
- Expands .github/SECURITY.md with PowerShell-specific guidance to help reporters distinguish security boundaries from defense-in-depth features.
- Cross-links the new documentation set to improve discoverability and onboarding for contributors.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.
Show a summary per file| File | Description |
|---|---|
| docs/SECURITY.md | New security-focused engineering doc covering boundaries, mechanisms, ownership, and vuln reporting. |
| docs/ERROR_HANDLING.md | New doc describing the ErrorRecord model and terminating vs non-terminating errors. |
| docs/DEV_GUIDE.md | New contributor guide for bootstrapping, building, testing, and conventions. |
| docs/DEPENDENCIES.md | New doc summarizing platform, NuGet, native, and optional external dependencies. |
| docs/BUSINESS_LOGIC.md | New doc explaining command execution model, pipeline semantics, and language modes. |
| docs/ARCHITECTURE.md | New doc mapping major components and projects to architecture layers. |
| docs/API_SURFACE.md | New doc describing cmdlet/module surface and the .NET hosting API surface. |
| AGENTS.md | New entrypoint/index tying together the engineering documentation set. |
| .github/SECURITY.md | Updated to reference the new security-boundary documentation before reporting issues. |
Sorry, something went wrong.
Comment thread
docs/SECURITY.md
Outdated
Comment thread
docs/SECURITY.md
Comment on lines
+14
to
+17
| security descriptors**, and **remote session secrets**. Code touching these must avoid logging | ||
| or persisting plaintext secrets. See [OBSERVABILITY / logging] guidance in | ||
| [DEV_GUIDE.md](DEV_GUIDE.md) - never write secret values into telemetry, error records, or | ||
| transcripts. |
Copy link
Copy Markdown
Member
Author
There was a problem hiding this comment.
Copilot Address this issue
Sorry, something went wrong.
Comment thread
docs/BUSINESS_LOGIC.md
| | `RestrictedLanguage` | Data-only; used by data sections / manifests. | | ||
| | `NoLanguage` | Only pre-defined commands, no script text (e.g. JEA endpoints). | | ||
|
|
||
| These are security boundaries — see [SECURITY.md](SECURITY.md). |
Copy link
Copy Markdown
Member
Author
There was a problem hiding this comment.
Copilot address this issue
Sorry, something went wrong.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Copy link
Copy Markdown
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.
Comments suppressed due to low confidence (2)docs/SECURITY.md:17
- The bracketed text "[OBSERVABILITY / logging]" isn’t a valid link and renders as literal brackets. Consider linking directly to the relevant section or rephrasing so the sentence reads cleanly.
or persisting plaintext secrets. See [OBSERVABILITY / logging] guidance in [DEV_GUIDE.md](DEV_GUIDE.md) - never write secret values into telemetry, error records, or transcripts.
docs/BUSINESS_LOGIC.md:80
- This sentence states that language/execution modes are security boundaries, but elsewhere in this PR (docs/SECURITY.md and .github/SECURITY.md) language modes are explicitly described as enforcement mechanisms that only become a boundary when anchored to an OS-enforced trust decision (for example ACfB/WDAC). This should be aligned to avoid misleading threat models.
These are security boundaries — see [SECURITY.md](SECURITY.md).
Sorry, something went wrong.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This was referenced Jul 22, 2026
Comment thread
docs/ARCHITECTURE.md
Outdated
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR Summary
This pull request introduces a comprehensive set of engineering documentation for PowerShell, focusing on system architecture, API surface, business logic, dependencies, and security boundaries. The new documentation provides clear, organized references for developers and contributors, clarifies security reporting procedures, and centralizes technical details about the codebase and its modules.
New and Updated Documentation:
Security and Reporting Clarifications:
These changes significantly improve developer onboarding, clarify project structure and boundaries, and provide a single source of truth for engineering and security practices.
PR Context
PR Checklist