This post was originally published on this site

Microsoft.PowerShell.SecretManagement 1.1.0-preview

The next 1.1.0 version of SecretManagement has a number of minor fixes, but also two significant changes, one of which is a potentially breaking change for extension authors.
For more information on the changes in this release, see the CHANGELOG document.
This blog discusses the primary changes, why one is potentially breaking, and is especially relevant for extension vault owners who may want to test their vault and make any changes while these updates are in a preview state.

SecretManagement extension vault modules hosting change

SecretManagement extension vaults are PowerShell modules that conform to a special format.
Currently, when SecretManagement loads an extension vault module for use, it loads the module into the current user session.
However, this method of hosting extension vault modules prevented SecretManagement from running in ConstrainedLanguage (CL) mode.
To fix this problem, v1.1.0 of SecretManagement now hosts extension vaults in a separate runspace session.
Changing how the extension module is hosted, has the potential to break existing extension vaults.

What are the effects of the hosting change?

This change mostly affects extension vault authors because they can no longer assume their loaded vault module has access to current user session state.
Generally, extension vaults should never rely on shared user session state.
But if an extension did have this dependency, it would no longer work with this next version of SecretManagement.
We tested some extension vault modules on the PowerShellGallery, but found only one module that was affected by this change (SecretManagement.KeePass).

SecretManagement.KeePass extension vault

The SecretManagement.KeePass extension vault currently relies on its module being loaded in the user session in order to support its vault unlock operation via the Unlock-KeePassSecretVault command.
With the new SecretManagement version, the Unlock-KeePassSecretVault cmdlet is no longer effective, and the user is always prompted for a password when required by the vault.
This can be problematic for scripts being run unattended that do not support user interaction.

The KeePass vault needed to use this user shared state approach due to a deficiency in SecretManagement.
SecretManagement did not support a vault unlock operation, and required vaults that needed it to implement their own.
So one of the changes in this release is to add a new extension vault function, Unlock-SecretVault, that allows extension vaults to provide this functionality directly through SecretManagement.
With this new function, the KeePass vault no longer needs to leverage shared state with the user session.

New Unlock-SecretVault command

SecretManagement now supports a new Unlock-SecretVault command.
Extension vaults that require unlocking can optionally support this by implementing the Unlock-SecretVault function in their extension.
SecretManagement.KeePass extension vault module will be updated to use this new function, mitigating the problem.
For more information see SecretManagement Readme and Design documentation.

Other differences you may notice

Since the extension vaults are no longer loaded in the user session, you will no longer see them listed when you run the Get-Module command, which lists the currently loaded modules in your session.
This is arguably a good thing, since users generally don’t want or need to know about extension vault modules, and don’t need to see them in their current session.
Seeing extension vault modules unexpectedly loaded in their sessions may be confusing to users.

Some extension vault modules, such as Microsoft.PowerShell.SecretStore and SecretManagement.KeePass, include additional commands for the user.
The Microsoft.PowerShell.SecretStore vault provides additional commands for configuring the vault.
The SecretManagement.KeepPass vault provides additional commands for unlocking and registering the vault.
These commands will continue to work.
When these commands are run, the extension vault module will be visible from Get-Module because the commands are run in the current user session.
But that is the only time the extension vault modules will be loaded in the user session.

What is a runspace?

A PowerShell runspace encompasses the session context in which PowerShell scripts run, and can be thought of as an individual PowerShell session.
The PowerShell command shell usually has just a single session, but can support any number of sessions via multiple runspaces.
The runspace isolates multiple running scripts from each other within a single process.

What is CL mode?

Constrained Language is a PowerShell language mode that restricts language elements which can be used to invoke arbitrary APIs.
It is commonly used within a system wide application control policy, such as Windows AppLocker or Windows Defender Application Control, that restricts what applications are available and what scripts are trusted on the system.
Untrusted scripts run in ConstrainedLanguage while trusted scripts run in FullLanguage mode.

Feedback and Support

Community feedback has been essential to the iterative development of these modules.
Thank you to everyone who has contributed issues, and feedback thus far!
To file issues or get support for the SecretManagement interface or vault development experience please use the SecretManagement repository.
For issues which pertain specifically to the SecretStore and its cmdlet interface please use the SecretStore repository.

The post SecretManagement Module v1.1.0 preview update appeared first on PowerShell Team.

This post was originally published on this site

PlatyPS is the primary tool for creating the PowerShell help displayed using Get-Help.

What is PlatyPS

PowerShell external help files have been authored by hand or using complex tool chains and stored as
MAML XML for use as console help.
MAML is cumbersome to edit by
hand, and common tools and editors don’t support it for complex scenarios like they do with
markdown. Markdown is adopted widely by
Open Source, supported by many editors including
Visual Studio Code, and with minimal rules, easier to author.
PlatyPS is provided as a solution to allow documenting PowerShell help in any editor or tool
that supports markdown.

PlatyPS handles PowerShell documentation for complex scenarios (e.g. very large, closed source,
and/or C#/binary modules) where it may be desirable to have documentation abstracted away from the
codebase. PlatyPS does not need source access to generate documentation. PlatyPS solves this
scenario today at Microsoft by delivering
updatable help
files for PowerShell, SCCM, Windows, and other supported modules. Module authors may also use
PlatyPS to create the help that ships with their modules.

Announcing PlatyPS 2.0-Preview1

We are pleased to announce the release of PlatyPS 2.0.0-Preview1.

Our main goal for the 2.0.0 release is to maintain compatibility while fixing long standing issues.
We are re-writing PlatyPS in C# to leverage the existing markdown C# library allowing us to
address many of the open issues and make schema improvements recommended by the community. The main
functionality of PlatyPS remains unchanged except for community suggested bug fixes and
enhancements. We do expect a few necessary breaking changes in future previews.

In this Preview release, we focused on:

• re-write in C# leveraging Markdig for parsing markdown.
• updated New-MarkdownHelp
• updated Get-MarkdownMetadata

Future preview releases will include more performance improvements and cmdlet updates.

What’s supported

PlatyPS 2.0.0-Preview1 is currently available for download from the PowerShell Gallery.

Supported PowerShell versions for PlatyPS 2.0.0:

• Windows PowerShell 5.1+
• PowerShell 7.0+

Installing PlatyPS

To begin working with PlatyPS 2.0 Preview1, download and install the PlatyPS module from PSGallery.

Install-Module PlatyPS -AllowPrerelease

Markdown Schema Updates

Markdown is designed to be human-readable, without rendering. This makes writing and editing easy
and efficient. Many editors support markdown including Visual Studio Code. PlatyPS expects
markdown to be authored in a particular way. We have defined a schema to determine how parameters
are described, where scripts examples are shown, and so on.

The schema closely resembles the existing output format of the Get-Help cmdlet in PowerShell. If
you break the schema in your markdown, you will receive error messages.

For more information about the planned changes, see the
PlatyPS Design Specification.
Note, this is a draft specification subject to change.

Documentation to get started

For information about PlatyPS including cmdlet reference, see PlatypS

For additional information and examples of working with PlatyPS, see
Create XML-based help using PlatyPS.

Call to action

Our goal is to make it easier to update and maintain module/cmdlet help files. We value your ideas
and feedback. Stop by our GitHub repository and let us know of any issues or features you would like
added.

For more information about PlatyPS issues and features, see:
PlatyPS on GitHub

Jason Helmick
Program Manager, PowerShell

The post Announcing PlatyPS 2.0.0-Preview1 appeared first on PowerShell Team.

This post was originally published on this site

Continuing our investment in DSC, we are pleased to announce the release of
PSDesiredStateConfiguration 2.0.5 for DSC as a separate module on PowerShell Gallery. This is in
preparation for publishing previews of the 3.0 version of this module which will have new
capabilities, but also some breaking changes.

DSC is an important platform in configuration management, and we value the feedback we are
receiving from the community. To further the goals of DSC, PSDesiredStateConfiguration module
will no longer be included in the PowerShell package beginning in a future release of PowerShell 7.2
preview. Separating DSC into its own module allows us to invest and develop DSC independent of
PowerShell and reduces the size of the PowerShell package. Users of DSC will enjoy the benefit of
upgrading DSC without the need to upgrade PowerShell, accelerating time to deployment of new DSC
features.

Customers impacted by this change and wishing to remain on DSC v2 can download
PSDesiredStateConfiguration 2.0.5 for Windows PowerShell from the PowerShell Gallery. Customers
working with non-Windows environments can expect cross-platform features in DSC v3. For more
information about DSC and the teams on-going investments for 2021, see
PowerShell Team 2021 Investments

To download PSDesiredStateConfiguration from the PowerShell Gallery:

• PSDesiredStateConfiguration 2.0.5 on PowerShell Gallery

To install PSDesiredStateConfiguration:

Install-Module -Name PSDesiredStateConfiguration -Repository PSGallery -MaximumVersion 2.99

For more information about DSC v3 and the teams investments for 2021, see
PowerShell Team 2021 Investments

The post Announcing PSDesiredStateConfiguration on PowerShell Gallery appeared first on PowerShell Team.

This post was originally published on this site

We are pleased to announce the second preview of PowerShell Crescendo, a framework to rapidly
develop PowerShell cmdlets for native commands, regardless of platform.

The updated preview releases are now available for download on the PowerShell Gallery:

• Microsoft.PowerShell.Crescendo Preview 2

To install Microsoft.PowerShell.Crescendo:

Install-Module Microsoft.PowerShell.Crescendo -AllowPrerelease

For more information on Microsoft.PowerShell.Crescendo, check out these previous blog posts:

• Announcing PowerShell Crescendo Preview.1
• Native Commands in PowerShell Part 1
• Native Commands in PowerShell Part 2

Crescendo Preview 2 Updates

This update to Crescendo adds elevation support for native commands, and generation of a module
manifest when exporting a Crescendo module. Read the full list of changes below:

• Added support for native command elevation on Windows and Linux platforms. (Issue #50)
• Export-CrescendoModule now exports a module manifest (psd1) along with the module file (psm1). (Issue #51)
• Added support for generating aliases for Crescendo cmdlets (Issue #52)
• Added support for SupportsShouldProcess. Thanks jdhitsolutions! (Issue #59)

Native Command elevation

Native commands may require administrative elevation to perform the requested operation. The
Crescendo schema has been extended to support elevation on Windows and Linux/macOS platforms. The schema
supports the new keyword Elevation that has two properties Command and Arguments.

• Command: Defines the elevation mechanism to be used to elevate the native command. The function
  Invoke-WindowsNativeAppWithElevation has been included to aid with elevation on Windows. sudo
  has been tested as well.
• Arguments: These are the parameters to be used in conjunction with the elevation command. This can
  be a collection of parameters.
  • OriginalName: This is the parameter to be used with the elevation command.
  • DefaultValue: The default parameter value.

Windows Native Command Elevation

Elevation on Windows is supported using the built-in function
Invoke-WindowsNativeAppWithElevation. Invoke-WindowsNativeAppWithElevation uses Start-Process
with a PSCredential to invoke the native command and captures the output and errors of the native
command which are returned to the user. This function is inserted into the Crescendo module you
export. In the example below, the PowerShell cmdlet Get-Credential will prompt for credentials
necessary to elevate the native command when the exported Crescendo function is executed.

"Elevation": {
        "Command": "Invoke-WindowsNativeAppWithElevation",
        "Arguments": [
            {
                "OriginalName" : "-Credential",
                "DefaultValue": "(get-credential)"
            }
        ]
    },

In automation scenarios that require elevation without user interaction, Crescendo supports
retrieving credentials from secured vaults. In the example below, credentials for elevation are
retrieved from SecretManagement and SecretStore.

For more information about storing and managing secrets, see [SecretManagement Announcement](https://devblogs.microsoft.com/powershell/secretmanagement-and-secretstore-are-generally-available/

"Elevation": {
        "Command": "Invoke-WindowsNativeAppWithElevation",
        "Arguments": [
            {
                "OriginalName" : "-Credential",
                "DefaultValue": "(get-secret admin)"
            }
        ]
    },

Elevation can be defined for each cmdlet. When authoring a Crescendo json configuration, include
the elevation definition before the parameters are defined. In the example below, the native command
netsh.exe requires elevation to enable and disable the Windows Firewall.

{
    "$schema": "./Microsoft.PowerShell.Crescendo.Schema.json",
    "Verb": "Set",
    "Noun": "WinFirewall",
    "Platform": ["Windows"],
    "OriginalCommandElements": ["advfirewall", "set", "allprofiles", "state"],
    "OriginalName": "$env:Windir/system32/netsh.exe",
    "Elevation": {
        "Command": "Invoke-WindowsNativeAppWithElevation",
        "Arguments": [
            {
                "OriginalName" : "-Credential",
                "DefaultValue": "(get-credential)"
            }
        ]
    },
    "DefaultParameterSetName": "Enable",
    "Parameters": [
        {
            "OriginalName": "on",
            "Name": "On",
            "ParameterType": "switch",
            "ParameterSetName": ["Enable"]
        },
        {
            "OriginalName": "off",
            "Name": "Off",
            "ParameterType": "switch",
            "ParameterSetName": ["Disable"]
        }
    ]
}

Linux Native Command Elevation

Native command elevation for Linux and macOS is handled through the command sudo. To enable
elevation for Crescendo, include sudo as the Command value. In the example below, when the
function Get-TimeServer is executed, the user is prompted for the sudo password. The native
command is elevated with sudo privileges. In automation scenarios that require elevation without
user interaction, configure the sudoers file.

{
    "$schema": "../src/Microsoft.PowerShell.Crescendo.Schema.json",
    "Verb": "Get",
    "Noun": "TimeServer",
    "Elevation": {
        "Command": "sudo"
    },
    "OriginalCommandElements": ["-getnetworktimeserver"],
    "OriginalName": "/usr/sbin/systemsetup",
    "Platform": ["MacOS"],
    "OutputHandlers": [
        {
            "ParameterSetName": "Default",
            "Handler": "$args|%{[pscustomobject]@{ TimeServer = $_.Split(':')[1].Trim()}}"
        }
    ]
}

SupportsShouldProcess

Cmdlets that cause change to the system, such as files and service configurations, create a risk
that could negatively impact operations. To help mitigate risk, cmdlets support common parameters
-WhatIf and -Confirm. These parameters provide greater detail about the target of each
change, and provides a confirmation mechanism allowing the user to approve each change. Crescendo
supports this functionality when wrapping native commands though the schema keyword
SupportsShouldProcess.

In the example below, The keyword SupportsShouldProcess accepts a boolean to enable the common
parameters -WhatIf and -Confirm.

{
    "$schema": "../src/Microsoft.PowerShell.Crescendo.Schema.json",
    "Verb": "Remove",
    "Noun": "DockerImage",
    "OriginalName": "docker",
    "SupportsShouldProcess": true,
    "OriginalCommandElements": [
        "image",
        "rm"
    ],
    "Parameters": [
        {
            "Name": "ID",
            "OriginalName": "",
            "Mandatory": true,
            "ValueFromPipelineByPropertyName": true
        }
    ]
}

Executing Remove-DockerImage with the -WhatIf parameter supported by SupportsShouldProcess.

Get-DockerImage | Where-Object {$_.id -match "d70eaf7277ea"} | Remove-DockerImage -WhatIf

When SupportsShouldProcess is set True, the following expected output will result.

What if: Performing the operation "Remove-DockerImage" on target "docker image rm d70eaf7277ea".

Aliases

Aliases for Crecendo wrapped native commands are now supported in the Crescendo schema with the
keyword Aliases. In the snippet below, the cmdlet definition Set-WinFirewall includes the alias
definition SFW. When exported, the Crescendo created module will include the Set-WinFirewall
function and SFW alias.

{
    "$schema": "./Microsoft.PowerShell.Crescendo.Schema.json",
    "Verb": "Set",
    "Noun": "WinFirewall",
    "Platform": ["Windows"],
    "OriginalCommandElements": ["advfirewall", "set", "allprofiles", "state"],
    "OriginalName": "$env:Windir/system32/netsh.exe",
    "Aliases": ["SFW"],
    "Elevation": {
        "Command": "Invoke-WindowsNativeAppWithElevation",
        "Arguments": [
            {
                "OriginalName" : "-Credential",
                "DefaultValue": "(get-credential)"
            }
        ]
    },

Future plans

Next/Future plans for preview.3 will be based on feedback and include a few items under investigation:

• Improved OutputHandler support for building objects from native command string output.
• Support for multiple cmdlet definitions in a single json configuration.

Our goal is to make it easier to convert your native commands to PowerShell cmdlets and receive the
benefits that PowerShell provides. We value your ideas and feedback and hope you will give Crescendo
a try, then stop by our GitHub repository and let us know of any issues or features you would like
added.

For more information about PowerShell Crescendo issues and features, see:
Crescendo on GitHub

Jason Helmick

Program Manager, PowerShell

The post Announcing PowerShell Crescendo Preview.2 appeared first on PowerShell Team.