microsoft / secmgmt-open-powershell

Security and Management Open PowerShell Module

Security and Management Open PowerShell Module

Requirements

Security and Management Open PowerShell works with PowerShell 5.1 or higher on Windows, or PowerShell Core 6.x and later on all platforms. If you aren't sure if you have PowerShell, or are on macOS or Linux, install the latest version of PowerShell Core.

To check your PowerShell version, run the command:

$PSVersionTable.PSVersion

To run Security and Management Open PowerShell in PowerShell 5.1 on Windows:

1. Update to Windows PowerShell 5.1 if needed. If you're on Windows 10, you already have PowerShell 5.1 installed.
2. Install .NET Framework 4.7.2 or later.

There are no additional requirements for Security and Management Open PowerShell when using PowerShell Core.

Install the Security and Management Open PowerShell module

The recommended install method is to only install for the active user:

Install-Module -Name SecMgmt -AllowClobber -Scope CurrentUser

If you want to install for all users on a system, this requires administrator privileges. From an elevated PowerShell session either run as administrator or with the sudo command on macOS or Linux:

Install-Module -Name SecMgmt -AllowClobber -Scope AllUsers

By default, the PowerShell gallery isn't configured as a trusted repository for PowerShellGet. The first time you use the PSGallery you see the following prompt:

Untrusted repository

You are installing the modules from an untrusted repository. If you trust this repository, change
its InstallationPolicy value by running the Set-PSRepository cmdlet.

Are you sure you want to install the modules from 'PSGallery'?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"):

Answer Yes or Yes to All to continue with the installation.

Discovering cmdlets

Use the Get-Command cmdlet to discover cmdlets within a specific module, or cmdlets that follow a specific search pattern:

# List all cmdlets in the SecMgmt module
Get-Command -Module SecMgmt

# List all cmdlets that contain Hybrid
Get-Command -Name '*Hybrid*'

# List all cmdlets that contain Hybrid in the SecMgmt module
Get-Command -Module SecMgmt -Name '*Hybrid*'

Cmdlet help and examples

To view the help content for a cmdlet, use the Get-Help cmdlet:

# View the basic help content for Initialize-SecMgmtHybirdDeviceEnrollment
Get-Help -Name Initialize-SecMgmtHybirdDeviceEnrollment

# View the examples for Initialize-SecMgmtHybirdDeviceEnrollment
Get-Help -Name Initialize-SecMgmtHybirdDeviceEnrollment -Examples

# View the full help content for Initialize-SecMgmtHybirdDeviceEnrollment
Get-Help -Name Initialize-SecMgmtHybirdDeviceEnrollment -Full

# View the help content for Initialize-SecMgmtHybirdDeviceEnrollment on https://docs.microsoft.com
Get-Help -Name Initialize-SecMgmtHybirdDeviceEnrollment -Online

secmgmt-open-powershell's Issues

Unit tests

Feature Request

Is your feature request related to a problem?
As a maintainer of this project, I am frustrated when bugs are not caught before the module is pushed to the PowerShell Gallery.

Describe the solution you would like
There should be unit tests associated with each command. Also, guidance should be incorporated into the documentation on how the test should be developed.

Insights connector installation

Feature Request

Is your feature request related to a problem?
As an administrator I am frustrated with the number of steps required to leverage the Security and Management Insights Power BI connector.

Describe the solution you would like
Ideally there should be automation for ensuring the connector is configured and installed correctly.

Resolving assembly dependency conflicts

Feature Request

Is your feature request related to a problem?
As a consumer of the module I am frustrated when the module is broken by updates to other modules.

Describe the solution you would like
Typically the module breaks due to assembly dependency conflicts. This article provides details on how best to address the potential for assembly dependency conflicts

Domain parameter should be optional

Feature Request

Is your feature request related to a problem?
I am frustrated when invoking the Initialize-SecMgmtHybirdDeviceEnrollment cmdlet that I have to specify the domain

Describe the solution you would like
Since a connection is being established to Microsoft Graph, the domain value should be obtained from Azure Active Directory. If the parameter is not specified, then is should be requested.

Install-SecMgmtInsightsConnector : Code: Request_BadRequest

Steps to reproduce

Invoke the following PowerShell

Install-SecMgmtInsightsConnector -ApplicationDisplayName 'Security and Management Insights'

Expected behavior

That the command create and configure the Azure AD application, and then install the connector.

Actual behavior

Install-SecMgmtInsightsConnector : Code: Request_BadRequest
Message: Missing property: expiryTime
Inner error:
        AdditionalData:
        date: 2020-07-02T17:35:02
        request-id: 0429a18f-866f-49f2-bef7-5515ad530ee1
ClientRequestId: 0429a18f-866f-49f2-bef7-5515ad530ee1
At line:1 char:1
+ Install-SecMgmtInsightsConnector -ApplicationDisplayName 'Security an ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : CloseError: (:) [Install-SecMgmtInsightsConnector], ServiceException
    + FullyQualifiedErrorId : Microsoft.Online.SecMgmt.PowerShell.Commands.InstallSecMgmtInsightsConnector

Environment

Windows 10
PowerShell version 5.1

Unable to install module

Steps to reproduce

Install-Module -Name SecMgmt -AllowClobber -Scope AllUsers

Expected behavior

i expected the module to be installed

Actual behavior

I get the following

PackageManagement\Install-Package : No match was found for the specified search criteria and module name 'SecMgmt'. Try Get-PSRepository to see all available registered module repositories.
At C:\Users\dgross\Documents\WindowsPowerShell\Modules\PowerShellGet\2.2.4.1\PSModule.psm1:9709 char:34

• ... talledPackages = PackageManagement\Install-Package @PSBoundParameters

•                  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

  • CategoryInfo : ObjectNotFound: (Microsoft.Power....InstallPackage:InstallPackage) [Install-Package], Exception
  • FullyQualifiedErrorId : NoMatchFoundForCriteria,Microsoft.PowerShell.PackageManagement.Cmdlets.InstallPackage

Diagnostic logs

Please share test platform diagnostics logs.
The logs may contain test assembly paths, kindly review and mask those before sharing.

Environment

Version: 1.46.1 (user setup)
Commit: cd9ea6488829f560dc949a8b2fb789f3cdc05f5d
Date: 2020-06-17T21:13:20.174Z
Electron: 7.3.1
Chrome: 78.0.3904.130
Node.js: 12.8.1
V8: 7.8.279.23-electron.0
OS: Windows_NT x64 10.0.17134

Tenant value

Steps to reproduce

The tenant identifier value should be a parameter

Expected behavior

The keywords property on the container contains the correct tenant identifier

Actual behavior

When the value is written it will have the wrong identifier

Environment

Windows 2019
PowerShell 5.1
Version 0.0.1

Cloud domain join

Feature Request

Is your feature request related to a problem?
As an administrator, or partner, I would like a way to automate the cloud domain join process for Windows 10

Describe the solution you would like
I would like to have a command to perform the cloud domain join process without being prompted for credentials. Also, this process should enroll the device into MDM

MSAL lockfile

Steps to reproduce

Invoke the following

Connect-SecMgmtAccount

Expected behavior

Expecting successful authentication

Actual behavior

Connect-SecMgmtAccount : Could not get access to the shared lock file.
At line:1 char:1
+ Connect-SecMgmtAccount -Debug
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : CloseError: (:) [Connect-SecMgmtAccount], InvalidOperationException
    + FullyQualifiedErrorId : Microsoft.Online.SecMgmt.PowerShell.Commands.ConnectSecMgmtAccount

Diagnostic logs

The msal.cache.lockfile is not being released which is blocking all requests for access tokens

Exception type: System.IO.IOException

   at System.IO.__Error.WinIOError(Int32 errorCode, String maybeFullPath)
   at System.IO.FileStream.Init(String path, FileMode mode, FileAccess access, Int32 rights, Boolean useRights,
FileShare share, Int32 bufferSize, FileOptions options, SECURITY_ATTRIBUTES secAttrs, String msgPath, Boolean
bFromProxy, Boolean useLongPath, Boolean checkHost)
   at System.IO.FileStream..ctor(String path, FileMode mode, FileAccess access, FileShare share, Int32 bufferSize,
FileOptions options)
   at Microsoft.Identity.Client.Extensions.Msal.CrossPlatLock..ctor(String lockfilePath, Int32 lockFileRetryDelay,
Int32 lockFileRetryCount)
=== End of inner exception stack trace ===

   at Microsoft.Identity.Client.Extensions.Msal.CrossPlatLock..ctor(String lockfilePath, Int32 lockFileRetryDelay,
Int32 lockFileRetryCount)
   at Microsoft.Identity.Client.Extensions.Msal.MsalCacheHelper.CreateCrossPlatLock(StorageCreationProperties
storageCreationProperties)
   at Microsoft.Identity.Client.Extensions.Msal.MsalCacheHelper.<CreateAsync>d__23.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at System.Runtime.CompilerServices.ConfiguredTaskAwaitable`1.ConfiguredTaskAwaiter.GetResult()
   at Microsoft.Online.SecMgmt.PowerShell.Utilities.PersistentTokenCache.GetMsalCacheStorage()

Environment

• PowerShell 5.1
• Windows 10 2004

Create recommended Microsoft Intune policies

Feature Request

Is your feature request related to a problem?
As an administrator it would be helpful to have a mechanism to create recommended policies, so I can ensure that my tenant has a better security posture

Describe the solution you would like
Ideally there would be a cmdlet that would create policies with the recommended settings

New-SecMgmtIntuneRecommendedPolicies [-TenantId <identifier>]

Describe alternatives you have considered
It is possible to create compliance and configuration policies using .NET or the Intune PowerShell module. However, the recommended policies are not well defined which means that I have to develop code similar to the following

DeviceConfiguration endpointPolicy = await client.DeviceManagement.DeviceConfigurations.Request().AddAsync(new Windows10EndpointProtectionConfiguration
{
    BitLockerEncryptDevice = true,
    DefenderEmailContentExecutionType = DefenderAttackSurfaceType.AuditMode,
    DefenderGuardMyFoldersType = FolderProtectionType.AuditMode,
    DefenderNetworkProtectionType = DefenderProtectionType.AuditMode,
    DefenderOfficeAppsLaunchChildProcessType = DefenderAttackSurfaceType.AuditMode,
    DefenderOfficeAppsExecutableContentCreationOrLaunchType = DefenderAttackSurfaceType.AuditMode,
    DefenderScriptDownloadedPayloadExecutionType = DefenderAttackSurfaceType.AuditMode,
    DisplayName = "Windows 10 - Endpoint protection policy"
}).ConfigureAwait(false);

DeviceConfiguration generalPoliy = await client.DeviceManagement.DeviceConfigurations.Request().AddAsync(new Windows10GeneralConfiguration
{
    DefenderPromptForSampleSubmission = DefenderPromptForSampleSubmission.PromptBeforeSendingPersonalData,
    DefenderRequireCloudProtection = true,
    DefenderRequireRealTimeMonitoring = true,
    DisplayName = "Windows 10 - General configuration policy",
    EdgeRequireSmartScreen = true,
    PasswordMinutesOfInactivityBeforeScreenTimeout = 5
}).ConfigureAwait(false);

Initialize-SecMgmtHybirdDeviceEnrollment

If you stare at that cmdlet name long enough you're going to chuckle to yourself ... then maybe blush. To my knowledge this isn't a docs issue: that's the actual name of the cmdlet.