Add comprehensive documentation for PowerShell architecture, security, and development#27714
Open
TravisEz13 wants to merge 4 commits into
Open
Add comprehensive documentation for PowerShell architecture, security, and development#27714TravisEz13 wants to merge 4 commits into
TravisEz13 wants to merge 4 commits into
Conversation
…, 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.
|
Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run. |
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 newdocs/*.mdengineering reference documents (architecture, API surface, business logic, dependencies, dev guide, error model, security). - Expands
.github/SECURITY.mdwith 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. |
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. |
| | `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). |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
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).
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This was referenced Jul 22, 2026
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:
AGENTS.md, including a quick reference, documentation index, and descriptions of key engineering documents.docs/ARCHITECTURE.mdto describe overall system context, internal architecture, and project-to-layer mapping for the PowerShell codebase.docs/API_SURFACE.mddetailing the cmdlet/command surface by module and the .NET hosting API, with references to source locations and module purposes.docs/BUSINESS_LOGIC.mdto explain the core execution model, command types, provider/drive abstraction, pipeline semantics, language modes, extensibility points, and domain glossary.docs/DEPENDENCIES.mddocumenting .NET, NuGet, native, and script module dependencies, as well as runtime external systems and ownership/escalation procedures.Security and Reporting Clarifications:
.github/SECURITY.mdwith guidance on PowerShell security boundaries, emphasizing the distinction between security boundaries and defense-in-depth features, and referencing the new security documentation.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
.h,.cpp,.cs,.ps1and.psm1files have the correct copyright header