Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Abhay Daga added note for reqd access. 6c30eff Aug 16, 2019
11 contributors

Users who have contributed to this file

@SINIKI @Khushboo-msft @Akreddy123 @RiniChandra @ShrutiBhambhani @VishalHaibatpure @v-zhgup @TarunKrShukla @sapsh-msft @ganesh-msft @abhaydaga
985 lines (760 sloc) 53.5 KB

NOTE: This article has been updated to use the new Azure PowerShell Az module. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module.

AzSK Subscription Security Package

Subscription_Security

Contents:

AzSK: Subscription Health Scan

AzSK: Subscription Security Provisioning

AzSK: Subscription Access Control Provisioning

AzSK: Subscription Activity Alerts

AzSK: Azure Security Center (ASC) configuration

AzSK: Subscription Security - ARM Policy

AzSK: Update subscription security baseline configuration

AzSK support for Azure Government and Azure China

AzSK: Privileged Identity Management (PIM) helper cmdlets


AzSK: Subscription Health Scan

Overview

The subscription health check script runs a set of automated scans to examine a subscription and flags off conditions that are indications that your subscription may be at a higher risk due to various security issues, misconfigurations or obsolete artifacts/settings.

The following aspects of security are checked:

  1. Access control configuration - identity and access management related issues in the subscription
  2. Alert configuration - configuration of activity alerts for sensitive actions for the subscription and various cloud resources
  3. Azure Security Center configuration - configuration of ASC (security point of contact, various ASC policy settings, etc.)
  4. ARM Policy and Resource Locks configuration - presence of desired set of ARM policy rules and resource locks.

Back to top…

Scan the security health of your subscription

The subscription health check script can be run using the command below after replacing <SubscriptionId> with your subscriptionId

Get-AzSKSubscriptionSecurityStatus -SubscriptionId <SubscriptionId>

The parameters used are:

  • SubscriptionId – Subscription ID is the identifier of your Azure subscription

You need to have at least Reader role at the subscription scope to run this command. If you also have access to read the Graph in your tenant, the RBAC information and checking will be richer.

Note: The check for presence of Management Certificates cannot be performed just with "Reader" privilege. This check only works if you are running as a Co-Administrator. This is in itself a bad practice. Hence, in most situations, the user running the subscription health check will likely not be a co-admin and, because we will not be able to actually perform the check, the outcome of this control will be listed as 'Manual'.

In general, in any scenario where the runtime account used to run an AzSK cmdlet does not have enough access to evaluate a control, the evaluation status is marked as "Manual" in the report. Basically, for such controls, someone with the correct access needs to manually verify the control and record the information through the "Control Attestation" feature. A common situation for this is in respect to "Graph Access" which is not available by default to SPNs.

Back to top…

Subscription Health Scan - What is covered?

The various security checks performed by the health check script are listed in the table here.

The next section explains how to interpret output in the LOG file and how to address control failures.

Back to top…

Subscription Health Scan - How to fix findings?

All cmdlets in AzSK generate outputs which are organized as under:

  • summary information of the control evaluation (pass/fail) status in a CSV file,
  • detailed control evaluation log in a LOG file and
  • a few other ancillary files for additional support

The overall layout and files in the output folder are also described in the README.txt file present in the root output folder.

To address findings, you should do the following:

  1. See the summary of control evaluation first in the CSV file. (Open the CSV in XLS. Use "Format as Table", "Hide Columns", "Filter", etc.)
  2. Review controls that are marked as "Failed", "Verify" or "Manual"
  3. The 'Recommendation' column for each control in the XLS will tell you the command/steps needed to resolve the issue.
  4. The LOG file contains details about why AzSK has flagged each control as "Failed" or "Verify".
  5. Use the following approach based on control status:
    • For "Failed" controls, look at the LOG file and use the Recommendation field to address the issue. (e.g., If the 'external accounts (LiveId)' control has failed, the list of such external accounts found is displayed in the LOG file. Remove these using the cmdlet mentioned in the Recommendation field.)
    • For "Verify" controls, look at the LOG file to get the supporting information that should help you to decide whether to consider the control as "Passed" or not. (e.g., For an RBAC control, you should look at the actual list of users and confirm that it is appropriate. Then use the "Control Attestation" feature to record your attestation.)
    • For "Manual" controls, follow the steps using the Recommendation field in the CSV. (There will not be anything in the LOG file for "Manual" controls.)

For provisioning related failures (e.g., you don't have central accounts correctly configured), you should use the corresponding provisioning cmdlet as described in respective sections below. (E.g., Set-AzSKSubscriptionRBAC for provisioning mandatory accounts).

Back to top…

Target specific controls during a subscription health scan

The subscription health check supports multiple parameters as specified below:

  • SubscriptionId – Subscription ID is the identifier of your Azure subscription
  • FilterTags - Comma-separated tags to filter the security controls. E.g., RBAC, SOX, AuthN, etc.
  • ExcludeTags - Comma-separated tags to exclude the security controls. E.g., RBAC, SOX, AuthN, etc.
  • ControlIds - Comma-separated AzSK control id's to filter security controls. E.g., Azure_Subscription_AuthZ_Limit_Admin_Owner_Count, Azure_Subscription_Config_Azure_Security_Center, etc.
Get-AzSKSubscriptionSecurityStatus -SubscriptionId <SubscriptionId> [-ControlIds <ControlIds>] [-FilterTags <FilterTags>] [-ExcludeTags <ExcludeTags>]

These different parameters would enable you to execute different 'flavors' of subscription health scan. For example, they will let you scan only SOX relevant controls or AuthZ related controls or exclude best practices or even execute one specific control. Here are some examples:

  1. Execute only SOX related controls
Get-AzSKSubscriptionSecurityStatus -SubscriptionId <SubscriptionId> -FilterTags "SOX"
  1. Exclude Best-Practice while doing AuthZ related subscription health scan
Get-AzSKSubscriptionSecurityStatus -SubscriptionId <SubscriptionId> -FilterTags "AuthZ" -ExcludeTags "Best Practice"
  1. Execute ASC related security control of subscription health scan
Get-AzSKSubscriptionSecurityStatus -SubscriptionId <SubscriptionId> -ControlIds Azure_Subscription_Config_Azure_Security_Center
List of Tags Purpose
Access Access activities
ACLS Access control activities
AppService Azure App Services
Audit Audit activities
AuthN Authentication activities
AuthZ Authorization activities
Automated Controls which are automated by AzSK
Availability Availability
BCDR Backup and disaster recovery
Best Practice Controls which should be implemented to ensure your application security
Classic Classic services
Config Configurations
Deploy Deployment activities
Diagnostics Diagnostics activities
DP Data protection
FunctionApp Azure FunctionApp
Information Controls which are default behaviour by Azure but additional check for notification
KeyRotation Key rotation
KeySecretPermissions Controls which can be attested only when the user has access permissions on the concerned keys and secrets
Linux Linux virtual machine
Manual Controls which are not automated and user need to verify it manually
NetSec Network security
OwnerAccess Controls which require owner/co-admin permission to get required output
RBAC Role based access controls
SDL Software development lifecycle
SecIntell Security intellisense
SI System integrity
SOX Controls which are enforced by SOX
SqlDatabase Azure SQL Database
TCP Controls which must be implemented to ensure your application security
Windows Windows virtual machine

Back to top…


AzSK: Subscription Security Provisioning

Overview

The Subscription Security Provisioning script is a master script that, in turn, invokes multiple other scripts to setup up all of the following in the target subscription:

  • A set of mandatory accounts that are required for central scanning/audit/compliance functions.
  • A group of subscription and resource activity alerts for activities with significant security implications.
  • A baseline set of ARM policies corresponding to certain actions that are considered insecure.
  • Default enterprise policy settings for Azure Security Center (ASC).
  • Security contact information in ASC.

Back to top…

Provision security for your subscription

The Subscription Security setup script can be run by providing the subscriptionID, security contact E-mails (comma separated values) and a contact phone number.

Set-AzSKSubscriptionSecurity -SubscriptionId <subscriptionId> -SecurityContactEmails <SecurityContactEmails> -SecurityPhoneNumber <SecurityPoCPhoneNumber>
Config Param Name Purpose
SecurityContactEmails Comma-separated list of emails (e.g., 'abc@microsoft.com, def@microsoft.com') for contact preference
SecurityPhoneNumber Single phone number (e.g., '425-882-8080' or '+91-98765-43210' or '+1-425-882-8080') for contact preference

Note:

  • This command overwrites the contact emails and phone number previously configured in Azure Security Center.
  • This command also helps you to recover if any of the base resources are accidentally deleted, like AzSK resource group, storage account, attestation container, continuous assurance log container etc.

While running command, you may see message that configuration in your subscription is already up to date. This indicates your subscription already have latest security configurations. If you still see any failures for controls in Get-AzSKSubscriptionSecurityStatus command, you can pass -Force parameter to the provisioning script and reconfigure AzSK artifacts ( Alerts, RBAC, ARM policies, etc.) in the subscription.

Back to top…

Remove AzSK subscription security provisioning from your subscription

The subscription setup created by the provisioning command can be removed by running:

Remove-AzSKSubscriptionSecurity -SubscriptionId <subscriptionId> -Tags <TagNames>

This command cleans up various security provisioning that was previously done using the Set-AzSKSubscriptionSecurity command such as alerts, access control (RBAC) settings, ARM policies, etc.

This command does not affect the Azure Security Center related settings (whether they were previously configured by AzSK or directly by the user).

To remove access control related configuration, it is mandatory to use the -Tags parameter. If this parameter is not specified, previously setup RBAC will not be deprovisioned will be done. Typically you would want to specify the tags which were used when setting up RBAC. If you did not specify any tags during provisioning then, by default, only the accounts marked as 'Mandatory' would get provisioned. Typically, you should not have to remove those accounts but if you must you can do so using -Tags "Mandatory" in the command.

Back to top…

FAQs

Is it possible to setup an individual feature (e.g., just alerts or just ARM Policy)?

Yes, each of the components of the overall subscription provisioning setup can be individually run/controlled. You can run cmdlets in isolation for the following:

  1. RBAC roles/permissions - Set-AzSKSubscriptionRBAC
  2. Alerts - Set-AzSKAlerts
  3. ARM Policy - Set-AzSKARMPolicies
  4. Azure Security Center configuration - Set-AzSKAzureSecurityCenterPolicies

Set-AzSKSubscriptionSecurity or Set-AzSKAzureSecurityCenterPolicies returns - InvalidOperation: The remote server returned an error: (500) Internal Server Error

Currently we are seeing an issue with an Azure Security Center API which is causing the error you are seeing. You can follow the steps below until the issue is resolved:

  1. Login to your subscription.
  2. Go to 'Security Center' > 'Security policy'.
  3. Select your subscription and click on 'Edit settings'.
  4. Select 'Email notifications'.
  5. Update 'Security contact emails' and 'Phone number'.
  6. Click on 'Save'.

You can try running the recommendation command again after doing the above change.

Back to top…


AzSK: Subscription Access Control Provisioning

Overview

The subscription access control provisioning script will setup certain permissions in the subscription that enable central security and compliance teams to perform automated scans and manual review/assessment activities in the subscription. This basically involves addition of some common accounts (service principals or security groups) to one or more roles in the subscription. The script also supports provisioning of some optional accounts based on the scenarios that the subscription is used for. (The specific accounts and the roles they are deployed into are configurable by the central security team in your organization.)

Back to top…

Setup pre-approved mandatory accounts

The subscription access control provisioning script can be run using the following command (by specifying the subscriptionId for the subscription in which you want to provision the various roles):

Set-AzSKSubscriptionRBAC -SubscriptionId <subscriptionId> 

The subscription access control provisioning script ensures that certain central accounts and roles are setup in your subscription.

Back to top…

Remove previously provisioned accounts

The Remove-AzSKSubscriptionRBAC command can be used to remove access control (RBAC) settings that were previously provisioned using AzSK.

To remove access control related configuration, use the '-Tags' parameter. If this parameter is not specified, only the deprecated accounts will be deleted from the subscription. Typically you would want to specify the tags which were used when setting up RBAC. If you did not specify any tags during provisioning then, by default, only the accounts marked as 'Mandatory' would get provisioned. Typically, you should not have to remove those accounts but if you must you can do so using '-Tags "Mandatory"' in the command.

Run the below command with the subscriptionId which you want to remove RBAC accounts from:

Remove-AzSKSubscriptionRBAC -SubscriptionId <subscriptionId> [-Tags <TagName>]

Back to top…


AzSK: Subscription Activity Alerts

Subscription Activity Alerts (based on Azure Insights)

Note: The alerts setup covered on this page uses the native 'Insights-based' alerts mechanism offered by the Azure PG. In the 'Alerting & Monitoring' section, we also cover support for Log Analytics-based alerts which enable similar scenarios (and more). We have found that both approaches are in use across LoB application teams.

Overview

This module helps setup and manage subscription and resource activity-based alerts in your Azure subscription. These alerts can be configured against actions that get recorded in Azure Audit Logs. These activity logs are natively generated upon resource activity by various ARM-based log providers (which are typically correspond to the different resource types in Azure).

It is important to understand the concept of 'control plane' and 'data plane' in order to follow exactly which type of activities get covered by these alerts. In the ARM-model for Azure, everything that you can create from a subscription (at the portal or from PS) is considered a 'resource'. Various activities performed on these resources that you can do using the ARM APIs generate activity logs. For e.g., you can change the replication type of a storage account or you can set the size of an availability set, etc. These activities are usually considered 'control plane' activities. However, there are a set of activities that can happen "inside" the resource. For e.g., if you have a VM, you could log in to it as an Admin and add someone as a Guest user. Or just create a new folder under "C:\windows". These actions are usually considered 'data plane'. Insights-based alerts don't directly support alerting on 'data plane' actions. As is evident, each type of resource (VM, SQL Server, ADLS, etc.) will have their own ways of generating 'data plane' activity so alerting from that layer is usually very specific to each resource type. (Events from the 'data plane' are sometimes called 'Diagnostic Logs' whereas events from the 'control plane' are called 'Activity Logs'.)

In the context of this script, we have triaged the 200 or so activities that generate activity log entries and distilled them down to a subset that can be of interest to security. That subset was further triaged into Critical, High, Medium and Low severity alerts.

The basic script flow configures these alerts after taking an email id as input. After the alerts are setup, whenever a particular activity happens (e.g., adding a new person in the "Owners" group or modifying user defined routes on a virtual network), the configured email ID receives an email notification.

Back to top…

Configure alerts for your subscription

You can setup alerts for a subscription using the following command:

Set-AzSKAlerts -SubscriptionId <subscriptionid> -SecurityContactEmails <SecurityContactEmails> [-SecurityPhoneNumbers <SecurityPhoneNumbers>]

As noted above, by default alerts are configured for activities that are deemed to be Critical or High in severity by AzSK.

Config Param Name Purpose Comments
SubscriptionId Subscription ID against which the alerts would be setup
SecurityContactEmails Email address of Security Point of Contact, can be a mail enabled security group or a distribution list abc@contoso.com, xyz@contoso.net
SecurityPhoneNumbers Phone numbers of Security Point of Contact, provide contact no. with country code. '+91-98765-43210' or '+1-425-882-8080'

Back to top…

Remove previously configured alerts from your subscription

  • Steps to remove all the alerts configured by AzSK:
    Run the below command:
Remove-AzSKAlerts -SubscriptionId <SubscriptionID> -Tags <TagNames>
Config Param Name Purpose
SubscriptionID Subscription ID against which these alerts would be setup
Tags Comma-separated alert tag names which needs to be removed, supported tag names "Optional","Mandatory","SMS"

For e.g., to remove only optional alerts, run following command:

Remove-AzSKAlerts -SubscriptionId <SubscriptionID> -Tags "Optional"

Note: This command cleans up all alerts in the resource group 'AzSKRG' with matched tag. This resource group is used internally as a container for AzSK objects. As a result, it is advisable to not add other alerts (or other types of resources) to this RG.

Back to top…

Configure alerts scoped to specific resource groups

You may be interested in enabling alerts but only for resources within a particular (target) resource group. This may be done using the -TargetResourceGroup parameter.

Run the below command

Set-AzSKAlerts -SubscriptionId <subscriptionid> -TargetResourceGroup <TargetRGName>

These parameters above have to be updated with the appropriate values. See the table below for details.

Config Param Name Purpose
SubscriptionId Subscription ID against which these alerts would be setup
TargetResourceGroup Target resource group on which alerts needs to be configured

Back to top…

FAQs

Can I get the alert emails to go to a distribution group instead of an individual email id?

Yes it is possible. While setting up the alerts you are asked to provide the SecurityContactEmails. It supports individual point of contact or mail enabled security group or a distribution list.

How can I find out more once I receive an alert email?

You should visit portal with the details data provided in the Alert Email. For example, you could visit the resource id and look for the action that has been called out in the email, or to get more details about the alert, visit the Activity Log in the portal and look for this resource type, you should find more details on the action performed.

Note: These alerts template and the generation is completely controlled through Azure Application Insights framework.

Is there a record maintained of the alerts that have fired?

You could run the below command to check the alerts raised on the subscription.

Get-AzLog | where {$_.OperationName -eq "Microsoft.Insights/AlertRules/Activated/Action"}

Troubleshooting

Error Description Comments
Error: Please enter valid subscription id! Provided subscription id is incorrect
Error Occurred! Try running the command with -Debug option for more details. Failed to setup the policy. Share the details of the errors to AzSKSup@microsoft.com

Back to top…


AzSK: Azure Security Center (ASC) configuration

Setup Azure Security Center (ASC) on your subscription

The Set-AzSKAzureSecurityCenterPolicies provisions the following for Azure Security Center (ASC) configuration:

  1. Configure Azure Security Center by enabling all the required policies and rules.
  2. Configure email address and phone number for contact preferences.
  3. Enable automatic provisioning for the subscription.

Prerequisites:

  1. You need to be owner on the subscription which you want to onboard on to ASC.
  2. Ensure you have the latest AzSK modules installed.

Steps to onboard onto ASC:

  1. Open PowerShell under non admin mode.
  2. Login into your Azure Account using Connect-AzAccount.
  3. Run the below command with the subscriptionId on which you want to configure Azure Security Center.
Set-AzSKAzureSecurityCenterPolicies -SubscriptionId <SubscriptionId> `
        -SecurityContactEmails <ContactEmails> `
        -SecurityPhoneNumber <ContactPhone> `
        [-OptionalPolicies]
Config Param Name Purpose
SubscriptionId Subscription ID against which ASC would be setup
SecurityContactEmails Comma-separated list of emails (e.g., 'abc@microsoft.com, def@microsoft.com') for contact preference
SecurityPhoneNumber Single phone number (e.g., '425-882-8080' or '+91-98765-43210' or '+1-425-882-8080') for contact preference
OptionalPolicies Switch to enable policies which are marked as optional

This command will overwrite the contact emails and contact phone previously set in Azure Security Center. Here is the list of all the policies (both mandatory & optional) that are enabled via this command.

Note: The Get-AzSKSubscriptionSecurityStatus cmdlet can be used to check Azure Security Center settings (amongst other things). That script checks for the following w.r.t. Azure Security Center:

  1. All ASC policies are configured per expectation.
  2. There are no pending ASC tasks.
  3. There are no pending ASC recommendations.
    (Presence of either of Tasks/Recommendations indicates that there are some security issues that need attention.)

Back to top…


AzSK: Subscription Security - ARM Policy

Overview

The native ARM Policy feature in Azure can be used control access to resources by explicitly auditing or denying access to certain operations on them. The ARM Policy setup script in the AzSK uses this feature to define and deploy some broadly applicable security policies in the subscription. By using the setup script (either standalone or through the overall Provisioning script), you can be assured that the subscription is compliant with respect to the core set of policies expected to be in place by AzSK.

Back to top…

Setup ARM policies on your subscription

You can install the ARM policies via the Set-AzSKARMPolicies cmdlet as below:

  1. Login to your Azure Subscription using below command
Connect-AzAccount
  1. Once you have installed the AzSK, you should be able to run the below command
Set-AzSKARMPolicies -SubscriptionId <subscriptionid>
Config Param Name Purpose
SubscriptionId Subscription ID against which these alerts would be setup

Back to top…

Remove ARM policies from your subscription

Use the following command to remove the ARM policies setup via the AzSK

Remove-AzSKARMPolicies -subscriptionId <subscriptionId> -Tags <TagNames>

You can also use native Azure PS commands to do the same. Refer to this MSDN article for more details.

Back to top…

FAQs

What happens if an action in the subscription violates the policy?

Currently "effect" parameter of all the AzSK policies is configured as "audit". So, in the event of policy violation, it would generate an audit log entry. You should watch for these policy violation audit events in the Azure audit log.

Which ARM policies are installed by the setup script?

The ARM policy configuration script currently enables the policies (Refer the list here) in the subscription. Note that the policy level is currently set to 'Audit'.

Policy definitions exist in the JSON file at this location: C:\Users\SampleUser\Documents\WindowsPowerShell\Modules\AzSK\<version>\Framework\Configurations\SubscriptionSecurity\Subscription.ARMPolicies.json

How can I check for policy violations?

You could run the below command to check for the policy violations on the subscription. By default this shows the violations for the last one hour. Other intervals can be specified.

Get-AzLog | where {$_.OperationName -eq "Microsoft.Authorization/policies/audit/action"} 

Refer to this MSDN article for more details

Are there more policies available for use?

We have covered for the below resource types so far:

  • Azure SQL DB
  • Azure Storage
  • Scheduler Service
  • Usage of classic (v1/non-ARM) resources More policies will be added in upcoming releases.

Troubleshooting

Error Description Comments
Error: Please enter valid subscription id! Provided subscription id is incorrect
Error Occurred! Try running the command with -Debug option for more details. Failed to setup the policy. Share the details of the errors to AzSKSup@microsoft.com

Reach out to AzSKSup@microsoft.com for any further help

Back to top…

AzSK: Update subscription security baseline configuration

Update subscription security baseline configuration

AzSK team is constantly improving subscription security capabilities so it is possible that newer AzSK version has enhanced baselines for ASC, Alerts, ARM policies, CA runbook etc. This is where below command can help you to update your baseline configuration for different features (ARM Policies, Alerts, ASC, Access control, Continuous Assurance runbook).

Update-AzSKSubscriptionSecurity -SubscriptionId <subscriptionid>
Config Param Name Purpose
SubscriptionId Subscription for which AzSK subscription security baseline would be upgraded

Note:

  • This command is useful only for updating AzSK subscription security baseline. If you have never setup baseline, then you can set it up using Set-AzSKSubscriptionSecurity command.
  • This command also helps you to recover if any of the base resources are accidentally deleted, like AzSK resource group, storage account, attestation container, continuous assurance log container etc.

Back to top…

AzSK support for Azure Government and Azure China

Pre-requisites:

  • AzSK version 3.8.0 or above.

From release 3.8.0, AzSK has started supporting a few core scenarios for Azure Government and Azure China environments. Please follow the steps as under to use AzSK in those environments.

Spotcheck/Manual Scans:

Follow the steps below to successfully run the local AzSK scans (GRS, GSS and other commands):

  1. Follow instructions in our installation guide to download the latest version of AzSK (3.9.0 or above).

  2. Configure AzSK for your Azure environment using the following command:

Set-AzSKPolicySettings -AzureEnvironment '<your environment name>'
E.g., Set-AzSKPolicySettings -AzureEnvironment AzureUSGovernment 

Once you have run through the steps above, any AzSK commands you run will start targeting the configured Azure cloud environment.

Notes:

  • When no specific environment is configured (as in Step-2 above), AzSK assume AzureCloud as the default environment.
  • If you have access to multiple Azure environments and need to switch from one to the other (e.g., AzurePublic to AzureChina) then you can use the Clear-AzSKSessionState command after running Step-2. This will cause AzSK to reload the newly configured environment.

CICD:

To use the CICD extension, no special steps are required beyond those outlined in the AzSK CICD extensions doc.

CA:

Once you have run through the steps outlined in the 'Spotcheck/Manual' section, You can easily use AzSK Continuous Assurance. Click here for more details on Continuous Assurance.

Please refer this set up CA. As Azure Government and Azure China are limited to particular location, provide 'AutomationAccountLocation' parameter because the default value is EastUS2.

E.g., Install-AzSKContinuousAssurance -SubscriptionId <SubscriptionId> `
		    -AutomationAccountLocation "USGov Virginia" `                    (for Azure Government)
	        -ResourceGroupNames <ResourceGroupNames> `
	        -LAWSId <WorkspaceId> `
	        -LAWSSharedKey <SharedKey> 

Customizing AzSK for your organization:

Please refer this for more details

Note:

As Azure Government and Azure China are limited to particular location, provide 'ResourceGroupLocation' parameter because the default value is EastUS2

E.g., Install-AzSKOrganizationPolicy -SubscriptionId <SubscriptionId> `
           -OrgName <OrgName> `
           -PolicyFolderPath <PolicyFolderPath> `
           -ResourceGroupLocation "USGov Virginia"                          (for Azure Government)

AzSK: Privileged Identity Management (PIM) helper cmdlets

AzSK now supports the Privileged Identity Management (PIM) helper cmdlets. This command provides a quicker way to perform Privileged Identity Management (PIM) operations and enables you to manage access to important Azure subscriptions, resource groups and resources.

Use Get-AzSKPIMConfiguration for querying various PIM settings/status

  1. List your PIM-eligible roles (-ListMyEligibleRoles)

    Use this command to list eligible PIM roles in the selected Azure subscription.

    Get-AzSKPIMConfiguration -ListMyEligibleRoles
  2. List permanent assignments (-ListPermanentAssignments)

    Use this command to list Azure role with permanent assignments at the specified scope. By default, it lists all role assignments in the selected Azure subscription. Use respective parameters to list assignments for a specific role, or to list assignments on a specific resource group or resource.

    Get-AzSKPIMConfiguration -ListPermanentAssignments`
                            -SubscriptionId <SubscriptionId> `
                            [-RoleNames <Comma separated list of roles>] `
                            [-ResourceGroupName <ResourceGroupName>] `
                            [-ResourceName <ResourceName>] `
                            [-DoNotOpenOutputFolder]

    Example 1: List all permanent assignments at subscription level with 'Contributor' and 'Owner' roles.

    Get-AzSKPIMConfiguration -ListPermanentAssignments `
                            -SubscriptionId "65be5555-34ee-43a0-ddee-23fbbccdee45" `
                            -RoleNames "Contributor,Owner" `
                            -DoNotOpenOutputFolder

    Example 2: List all permanent assignments at 'DemoRG' resource group level with 'Contributor' role.

    Get-AzSKPIMConfiguration -ListPermanentAssignments `
                             -SubscriptionId "65be5555-34ee-43a0-ddee-23fbbccdee45" `
                             -RoleNames "Contributor" `
                             -ResourceGroupName "DemoRG" `
                             -DoNotOpenOutputFolder

    Example 3: List all permanent assignments at resource level with 'Contributor' and 'Owner' role.

    Get-AzSKPIMConfiguration -ListPermanentAssignments `
                             -SubscriptionId "65be5555-34ee-43a0-ddee-23fbbccdee45" `
                             -RoleNames "Contributor,Owner" `
                             -ResourceGroupName "DemoRG" `
                             -ResourceName "AppServiceDemo" `
                             -DoNotOpenOutputFolder
  3. List PIM assignments (-ListPIMAssignments)

    Use this command to list Azure role with PIM assignments at the specified scope. By default, it lists all role assignments in the selected Azure subscription. Use respective parameters to list assignments for a specific role, or to list assignments on a specific resource group or resource.

    Get-AzSKPIMConfiguration -ListPIMAssignments `
                            -SubscriptionId <SubscriptionId> `
                            [-RoleNames <Comma separated list of roles>] `
                            [-ResourceGroupName <ResourceGroupName>] `
                            [-ResourceName <ResourceName>] `
                            [-DoNotOpenOutputFolder]

    Example 1: List 'Contributor' and 'Owner' PIM assignments at subscription level.

    Get-AzSKPIMConfiguration -ListPIMAssignments `
                            -SubscriptionId "65be5555-34ee-43a0-ddee-23fbbccdee45" `
                            -RoleNames "Contributor,Owner" `
                            -DoNotOpenOutputFolder

    Example 2: List 'Contributor' PIM assignments at 'DemoRG' resource group level.

    Get-AzSKPIMConfiguration -ListPIMAssignments `
                             -SubscriptionId "65be5555-34ee-43a0-ddee-23fbbccdee45" `
                             -RoleNames "Contributor" `
                             -ResourceGroupName "DemoRG" `
                             -DoNotOpenOutputFolder

    Example 3: List 'Contributor' and 'Owner' PIM assignments at resource level.

    Get-AzSKPIMConfiguration -ListPIMAssignments `
                             -SubscriptionId "65be5555-34ee-43a0-ddee-23fbbccdee45" `
                             -RoleNames "Contributor,Owner" `
                             -ResourceGroupName "DemoRG" `
                             -ResourceName "AppServiceDemo" `
                             -DoNotOpenOutputFolder

Use Set-AzSKPIMConfiguration for configuring/changing PIM settings:

  1. Assigning users to roles (-AssignRole)

    Use this command to assign PIM role to the specified principal, at the specified scope.

    NOTE: You must have owner access to run this command.

    Set-AzSKPIMConfiguration -AssignRole `
                            -SubscriptionId <SubscriptionId> `
                            -DurationInDays <Int> `
                            -RoleName <RoleName> `
                            -PrincipalName  <PrincipalName> `
                            [-ResourceGroupName <ResourceGroupName>] `
                            [-ResourceName <ResourceName>] `
                            [-DoNotOpenOutputFolder]

    Example 1: Grant PIM access with 'Contributor' role to a user for 30 days on a subscription.

    Set-AzSKPIMConfiguration -AssignRole `
                             -SubscriptionId "65be5555-34ee-43a0-ddee-23fbbccdee45" `
                             -DurationInDays 30 `
                             -RoleName "Contributor" `
                             -PrincipalName "john.brown@microsoft.com" `
                             -DoNotOpenOutputFolder

    Example 2: Grant PIM access with 'Owner' role to a user for 20 days on a resource group 'DemoRG'.

    Set-AzSKPIMConfiguration -AssignRole `
                             -SubscriptionId "65be5555-34ee-43a0-ddee-23fbbccdee45" `
                             -DurationInDays 20 `
                             -ResourceGroupName "DemoRG" `
                             -RoleName "Owner" `
                             -PrincipalName "john.brown@microsoft.com" `
                             -DoNotOpenOutputFolder

    Example 3: Grant PIM access with 'Owner' role to a user for 30 days on a resource 'AppServiceDemo'.

    Set-AzSKPIMConfiguration -AssignRole `
                             -SubscriptionId "65be5555-34ee-43a0-ddee-23fbbccdee45" `
                             -DurationInDays 30 `
                             -ResourceGroupName "DemoRG" `
                             -ResourceName "AppServiceDemo" `
                             -RoleName "Owner" `
                             -PrincipalName "john.brown@microsoft.com" `
                             -DoNotOpenOutputFolder
  2. Activating your roles (-ActivateMyRole)

    Use this command to activate your PIM access.

    NOTE:
    a. Activation duration should range between 1 to 8 hours.
    b. Make sure that the PIM role you are activating is eligible. If your PIM role has expired, contact subscription administrator to renew/re-assign your PIM role.

    Set-AzSKPIMConfiguration -ActivateMyRole `
                            -SubscriptionId <SubscriptionId> `
                            -RoleName <RoleName> `
                            -DurationInHours <Int> `
                            -Justification <String> `
                            [-ResourceGroupName <ResourceGroupName>] `
                            [-ResourceName <ResourceName>] `
                            [-DoNotOpenOutputFolder]

    Example 1: Activate your PIM access on a resource group.

    Set-AzSKPIMConfiguration -ActivateMyRole `
                            -SubscriptionId "65be5555-34ee-43a0-ddee-23fbbccdee45" `
                            -RoleName "Owner" `
                            -DurationInHours 8 `
                            -Justification "Add a valid justification for enabling PIM role" `
                            -ResourceGroupName "DemoRG" `
                            -DoNotOpenOutputFolder
  3. Deactivating your roles (-DeactivateMyRole)

    Use this command to deactivate your PIM access.

    Set-AzSKPIMConfiguration -DeactivateMyRole `
                            -SubscriptionId <SubscriptionId> `
                            -RoleName <RoleName> `
                            [-ResourceGroupName <ResourceGroupName>] `
                            [-ResourceName <ResourceName>] `
                            [-DoNotOpenOutputFolder]

    Example 1: Deactivate your PIM access on a subscription.

    Set-AzSKPIMConfiguration -DeactivateMyRole `
                            -SubscriptionId "65be5555-34ee-43a0-ddee-23fbbccdee45" `
                            -RoleName "Owner" `
                            -DoNotOpenOutputFolder
  4. Converting permanent assignments at subscription/RG scope to PIM (-ConvertPermanentAssignmentsToPIM)

    Use this command to change permanent assignments to PIM for specified roles, at the specified scope.

    NOTE:
    This command will create PIM, but will not remove the permanent assignments. After converting permanent assignments to PIM, you can use "Set-AzSKPIMConfiguration -RemovePermanentAssignments" command with "-RemoveAssignmentFor MatchingEligibleAssignments" parameter to remove permanent assignment.

    Set-AzSKPIMConfiguration -ConvertPermanentAssignmentsToPIM `
                            -SubscriptionId <SubscriptionId> `
                            -RoleNames <Comma separated list of roles> `
                            -DurationInDays <Int> `
                            [-ResourceGroupName <ResourceGroupName>] `
                            [-ResourceName <ResourceName>] `
                            [-DoNotOpenOutputFolder]
                            [-Force]

    Example 1: Convert permanent assignments to PIM for 'Contributor' and 'Owner' roles at subscription level . This command runs in an interactive fashion so that you get an opportunity to verify the accounts being converted.

    Set-AzSKPIMConfiguration -ConvertPermanentAssignmentsToPIM `
                            -SubscriptionId "65be5555-34ee-43a0-ddee-23fbbccdee45" `
                            -RoleNames "Contributor,Owner" `
                            -DurationInDays 30 `
                            -DoNotOpenOutputFolder

    Example 2: Use '-Force' parameter to convert permanent assignments to PIM without giving runtime verification step.

    Set-AzSKPIMConfiguration -ConvertPermanentAssignmentsToPIM `
                            -SubscriptionId "65be5555-34ee-43a0-ddee-23fbbccdee45" `
                            -RoleNames "Contributor,Owner" `
                            -ResourceGroupName "DemoRG" `
                            -ResourceName "AppServiceDemo"`
                            -DurationInDays 20 `
                            -DoNotOpenOutputFolder
                            -Force
  5. Removing permanent assignments altogether (-RemovePermanentAssignments)

    Use this command to remove permanent assignments of specified roles, at the specified scope.

    There are two options with this command:

    a. -RemoveAssignmentFor MatchingEligibleAssignments (Default): Remove only those permanent roles which have a corresponding eligible PIM role.

    b. -RemoveAssignmentFor AllExceptMe: Remove all permanent role except your access.

    NOTE: This command will not remove your permanent assignment if one exists.

    Set-AzSKPIMConfiguration -RemovePermanentAssignments `
                            -SubscriptionId <SubscriptionId> `
                            -RoleNames <Comma separated list of roles> `
                            [-RemoveAssignmentFor MatchingEligibleAssignments] `
                            [-ResourceGroupName <ResourceGroupName>] `
                            [-ResourceName <ResourceName>] `
                            [-DoNotOpenOutputFolder]
                            [-Force]
    Set-AzSKPIMConfiguration -RemovePermanentAssignments `
                            -SubscriptionId <SubscriptionId> `
                            -RoleNames <Comma separated list of roles> `
                            [-RemoveAssignmentFor AllExceptMe] `
                            [-ResourceGroupName <ResourceGroupName>] `
                            [-ResourceName <ResourceName>] `
                            [-DoNotOpenOutputFolder]
                            [-Force]
    

    Example 1: Remove 'Contributor' and 'Owner' roles that have permanent assignment at subscription level. This command runs in an interactive fashion so that you get an opportunity to verify the accounts being removed. All the specified role with permanent access will get removed except your access.

    Set-AzSKPIMConfiguration -RemovePermanentAssignments `
                            -SubscriptionId "65be5555-34ee-43a0-ddee-23fbbccdee45" `
                            -RoleNames "Contributor,Owner" `
                            -RemoveAssignmentFor AllExceptMe
                            -DoNotOpenOutputFolder

    Example 2: Use '-Force' parameter to run the command in non-interactive mode. This will remove permanent assignment at resource level without giving runtime verification step. Use -RoleNames to filter the roles to be deleted. Here we have used -RemoveAssignmentFor 'MatchingEligibleAssignments'. Hence, this command deletes the specified role with permanent access only if there is a corresponding PIM role for the same.

    Set-AzSKPIMConfiguration -RemovePermanentAssignments `
                            -SubscriptionId "65be5555-34ee-43a0-ddee-23fbbccdee45" `
                            -RoleNames "Owner" `
                            -RemoveAssignmentFor MatchingEligibleAssignments
                            -ResourceGroupName "DemoRG" `
                            -ResourceName "AppServiceDemo"`
                            -DoNotOpenOutputFolder
                            -Force

AzSK: Credential hygiene helper cmdlets

To help avoid availability disruptions due to credential expiry, AzSK has introduced cmdlets that will help you track and get notified about important credentials across your subscription. AzSK now offers a register-and-track solution to help monitor the last update of your credentials. This will help you periodically track the health of your credentials which are nearing expiry/need rotation.

NOTE: Ensure you have atleast 'Contributor' access on the subscription before running the below helper commands.

Use New-AzSKTrackedCredential to onboard a credential for tracking

   New-AzSKTrackedCredential -SubscriptionId '<Subscription Id>' `
                             -CredentialName '<Friendly name of the credential>' ` 
                             -CredentialLocation '<Other|AppService|KeyVault>' ` 
                             -RotationIntervalInDays <Int> `
                             -AlertEmail '<Alert email>' ` 
                             [-AlertSMS '<Alert contact number>'] `
                             -Comment '<Comment to capture the credential info>'    
Param Name Purpose Required? Allowed Values
SubscriptionId Subscription ID of the Azure subscription in which the to-be-tracked credential resides. TRUE None
CredentialName Friendly name for the credential. TRUE None
CredentialLocation Host location of the credential. TRUE Other/AppService/KeyVault
RotationIntervalInDays Time in days before which the credential needs an update. TRUE Integer
AlertEmail Email Id for which the tracking notification is to be configured. TRUE Valid email address
AlertSMS (Optional) Contact number for which the tracking notification is to be configured. FALSE Valid contact number
Comment Comment to capture more information about the credential for the user for futire tracking purposes. TRUE None

NOTE 1: > For credential location type 'AppService', you will have to provide app service name, resource group, app config type (app setting/connection string) & app config name. Make sure you have the required access on the resource.

NOTE 2: > For credential location type 'KeyVault', you will have to provide key vault name, credential type (Key/Secret) & credential name. Make sure you have the required access on the resource.

NOTE 3: > Use credential location type 'Other', if the credential doesn't belong to an appservice or key vault.

Use Get-AzSKTrackedCredential to list the onboarded credential(s)

   Get-AzSKTrackedCredential -SubscriptionId '<Subscription Id>' [-CredentialName '<Friendly name of the credential>']

NOTE: > Not providing credential name wil list all the AzSK-tracked credentials in the subscription.

Use Update-AzSKTrackedCredential to update the credential settings and reset the last updated timestamp

   Update-AzSKTrackedCredential -SubscriptionId '<Subscription Id>' `
                                -CredentialName '<Friendly name of the credential>' `  
                                [-RotationIntervalInDays <Int>] `
                                [-AlertEmail '<Alert email>'] ` 
                                [-AlertSMS '<Alert contact number>'] `
                                [-ResetLastUpdate]
                                -Comment '<Comment to capture the credential info>'    

NOTE: > Use '-ResetLastUpdate' switch only when you want to reset the timer on the last update on the credential to current time.

Use Remove-AzSKTrackedCredential to deboard a credential from AzSK tracking

   Remove-AzSKTrackedCredential -SubscriptionId '<Subscription Id>' [-CredentialName '<Friendly name of the credential>'] [-Force]

Use New-AzSKTrackedCredentialGroup to configure email alerts to notify users about AzSK-tracked credentials that are about to expire (<= 7 days) or have already expired.

   New-AzSKTrackedCredentialGroup -SubscriptionId '<Subscription Id>' -AlertEmail '<Alert email id>'
You can’t perform that action at this time.