From dcc102215fb9b6a1f11f07f02c1c66ad72a945a5 Mon Sep 17 00:00:00 2001 From: Yorick Kuijs Date: Wed, 6 Nov 2024 20:08:25 +0100 Subject: [PATCH] Documentation updates --- CHANGELOG.md | 2 + .../Modules/M365DSCDocGenerator.psm1 | 19 ++ .../ADOOrganizationOwner.md | 0 .../ADOPermissionGroup.md | 0 .../ADOPermissionGroupSettings.md | 0 .../ADOSecurityPolicy.md | 0 .../AzureBillingAccountsAssociatedTenant.md | 0 .../AzureBillingaccountsRoleAssignment.md | 0 .../AzureDiagnosticSettings.md | 0 ...agnosticSettingsCustomSecurityAttribute.md | 0 .../{azure-ad => azure}/AzureSubscription.md | 0 .../AzureVerifiedIdFaceCheck.md | 0 ...fenderDeviceAuthenticatedScanDefinition.md | 231 ++++++++++++++++++ .../DefenderSubscriptionPlan.md} | 0 .../FabricAdminTenantSettings.md | 0 .../M365DSCRuleEvaluation.md | 0 .../intune/MdcSubscriptionDefenderPlan.md | 98 -------- .../SentinelAlertRule.md | 0 .../SentinelSetting.md | 0 .../SentinelThreatIntelligenceIndicator.md | 0 .../SentinelWatchlist.md | 0 docs/mkdocs.yml | 6 + 22 files changed, 258 insertions(+), 98 deletions(-) rename docs/docs/resources/{azure-ad => azure-devops}/ADOOrganizationOwner.md (100%) rename docs/docs/resources/{azure-ad => azure-devops}/ADOPermissionGroup.md (100%) rename docs/docs/resources/{azure-ad => azure-devops}/ADOPermissionGroupSettings.md (100%) rename docs/docs/resources/{azure-ad => azure-devops}/ADOSecurityPolicy.md (100%) rename docs/docs/resources/{azure-ad => azure}/AzureBillingAccountsAssociatedTenant.md (100%) rename docs/docs/resources/{azure-ad => azure}/AzureBillingaccountsRoleAssignment.md (100%) rename docs/docs/resources/{azure-ad => azure}/AzureDiagnosticSettings.md (100%) rename docs/docs/resources/{azure-ad => azure}/AzureDiagnosticSettingsCustomSecurityAttribute.md (100%) rename docs/docs/resources/{azure-ad => azure}/AzureSubscription.md (100%) rename docs/docs/resources/{azure-ad => azure}/AzureVerifiedIdFaceCheck.md (100%) create mode 100644 docs/docs/resources/defender/DefenderDeviceAuthenticatedScanDefinition.md rename docs/docs/resources/{Defender => defender/DefenderSubscriptionPlan.md} (100%) rename docs/docs/resources/{exchange => fabric}/FabricAdminTenantSettings.md (100%) rename docs/docs/resources/{intune => general}/M365DSCRuleEvaluation.md (100%) delete mode 100644 docs/docs/resources/intune/MdcSubscriptionDefenderPlan.md rename docs/docs/resources/{security-compliance => sentinel}/SentinelAlertRule.md (100%) rename docs/docs/resources/{security-compliance => sentinel}/SentinelSetting.md (100%) rename docs/docs/resources/{security-compliance => sentinel}/SentinelThreatIntelligenceIndicator.md (100%) rename docs/docs/resources/{security-compliance => sentinel}/SentinelWatchlist.md (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3e23fd33dd..d733fc3ba0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ # Change log for Microsoft365DSC +# UNRELEASED + # 1.24.1106.1 * AADAccessReviewDefinition diff --git a/Modules/Microsoft365DSC/Modules/M365DSCDocGenerator.psm1 b/Modules/Microsoft365DSC/Modules/M365DSCDocGenerator.psm1 index 35d03c8bef..866ba5508d 100644 --- a/Modules/Microsoft365DSC/Modules/M365DSCDocGenerator.psm1 +++ b/Modules/Microsoft365DSC/Modules/M365DSCDocGenerator.psm1 @@ -958,15 +958,27 @@ function Update-M365DSCResourceDocumentationPage 'AAD*' { $targetFolder = 'azure-ad' } + 'ADO*' + { $targetFolder = 'azure-devops' + } + 'Azure*' + { $targetFolder = 'azure' + } 'Defender*' { $targetFolder = 'Defender' } 'EXO*' { $targetFolder = 'exchange' } + 'Fabric*' + { $targetFolder = 'fabric' + } 'Intune*' { $targetFolder = 'intune' } + 'M365DSC*' + { $targetFolder = 'general' + } 'O365*' { $targetFolder = 'office365' } @@ -982,6 +994,9 @@ function Update-M365DSCResourceDocumentationPage 'SC*' { $targetFolder = 'security-compliance' } + 'Sentinel*' + { $targetFolder = 'sentinel' + } 'SPO*' { $targetFolder = 'sharepoint' } @@ -990,6 +1005,10 @@ function Update-M365DSCResourceDocumentationPage } } $destinationFolder = Join-Path -Path $resourceDocsRoot -ChildPath $targetFolder + if ((Test-Path -Path $destinationFolder) -eq $false) + { + $null = New-Item -Path $destinationFolder -ItemType 'Directory' + } Move-Item -Path $file.FullName -Destination $destinationFolder -Force } diff --git a/docs/docs/resources/azure-ad/ADOOrganizationOwner.md b/docs/docs/resources/azure-devops/ADOOrganizationOwner.md similarity index 100% rename from docs/docs/resources/azure-ad/ADOOrganizationOwner.md rename to docs/docs/resources/azure-devops/ADOOrganizationOwner.md diff --git a/docs/docs/resources/azure-ad/ADOPermissionGroup.md b/docs/docs/resources/azure-devops/ADOPermissionGroup.md similarity index 100% rename from docs/docs/resources/azure-ad/ADOPermissionGroup.md rename to docs/docs/resources/azure-devops/ADOPermissionGroup.md diff --git a/docs/docs/resources/azure-ad/ADOPermissionGroupSettings.md b/docs/docs/resources/azure-devops/ADOPermissionGroupSettings.md similarity index 100% rename from docs/docs/resources/azure-ad/ADOPermissionGroupSettings.md rename to docs/docs/resources/azure-devops/ADOPermissionGroupSettings.md diff --git a/docs/docs/resources/azure-ad/ADOSecurityPolicy.md b/docs/docs/resources/azure-devops/ADOSecurityPolicy.md similarity index 100% rename from docs/docs/resources/azure-ad/ADOSecurityPolicy.md rename to docs/docs/resources/azure-devops/ADOSecurityPolicy.md diff --git a/docs/docs/resources/azure-ad/AzureBillingAccountsAssociatedTenant.md b/docs/docs/resources/azure/AzureBillingAccountsAssociatedTenant.md similarity index 100% rename from docs/docs/resources/azure-ad/AzureBillingAccountsAssociatedTenant.md rename to docs/docs/resources/azure/AzureBillingAccountsAssociatedTenant.md diff --git a/docs/docs/resources/azure-ad/AzureBillingaccountsRoleAssignment.md b/docs/docs/resources/azure/AzureBillingaccountsRoleAssignment.md similarity index 100% rename from docs/docs/resources/azure-ad/AzureBillingaccountsRoleAssignment.md rename to docs/docs/resources/azure/AzureBillingaccountsRoleAssignment.md diff --git a/docs/docs/resources/azure-ad/AzureDiagnosticSettings.md b/docs/docs/resources/azure/AzureDiagnosticSettings.md similarity index 100% rename from docs/docs/resources/azure-ad/AzureDiagnosticSettings.md rename to docs/docs/resources/azure/AzureDiagnosticSettings.md diff --git a/docs/docs/resources/azure-ad/AzureDiagnosticSettingsCustomSecurityAttribute.md b/docs/docs/resources/azure/AzureDiagnosticSettingsCustomSecurityAttribute.md similarity index 100% rename from docs/docs/resources/azure-ad/AzureDiagnosticSettingsCustomSecurityAttribute.md rename to docs/docs/resources/azure/AzureDiagnosticSettingsCustomSecurityAttribute.md diff --git a/docs/docs/resources/azure-ad/AzureSubscription.md b/docs/docs/resources/azure/AzureSubscription.md similarity index 100% rename from docs/docs/resources/azure-ad/AzureSubscription.md rename to docs/docs/resources/azure/AzureSubscription.md diff --git a/docs/docs/resources/azure-ad/AzureVerifiedIdFaceCheck.md b/docs/docs/resources/azure/AzureVerifiedIdFaceCheck.md similarity index 100% rename from docs/docs/resources/azure-ad/AzureVerifiedIdFaceCheck.md rename to docs/docs/resources/azure/AzureVerifiedIdFaceCheck.md diff --git a/docs/docs/resources/defender/DefenderDeviceAuthenticatedScanDefinition.md b/docs/docs/resources/defender/DefenderDeviceAuthenticatedScanDefinition.md new file mode 100644 index 0000000000..171bfa1f7f --- /dev/null +++ b/docs/docs/resources/defender/DefenderDeviceAuthenticatedScanDefinition.md @@ -0,0 +1,231 @@ +# DefenderDeviceAuthenticatedScanDefinition + +## Parameters + +| Parameter | Attribute | DataType | Description | Allowed Values | +| --- | --- | --- | --- | --- | +| **Name** | Key | String | Name of the scan definition. | | +| **Id** | Write | String | Unique identified for the scan definition. | | +| **IntervalInHours** | Write | UInt32 | Interval in hours to run the scan. | | +| **Target** | Write | String | Target of the scan definition. | | +| **IsActive** | Write | Boolean | Determines if the scan definition is active or not. | | +| **ScanType** | Write | String | Type of scan. | | +| **ScannerAgent** | Write | MSFT_DefenderDeviceAuthenticatedScanDefinitionScanAgent | Information about the associated scan agent. | | +| **ScanAuthenticationParams** | Write | MSFT_DefenderDeviceAuthenticatedScanDefinitionAuthenticationParams | Authentication parameters. | | +| **Ensure** | Write | String | Present ensures the instance exists, absent ensures it is removed. | `Absent`, `Present` | +| **Credential** | Write | PSCredential | Credentials of the workload's Admin | | +| **ApplicationId** | Write | String | Id of the Azure Active Directory application to authenticate with. | | +| **TenantId** | Write | String | Id of the Azure Active Directory tenant used for authentication. | | +| **CertificateThumbprint** | Write | String | Thumbprint of the Azure Active Directory application's authentication certificate to use for authentication. | | +| **ManagedIdentity** | Write | Boolean | Managed ID being used for authentication. | | +| **AccessTokens** | Write | StringArray[] | Access token used for authentication. | | + +### MSFT_DefenderDeviceAuthenticatedScanDefinitionAuthenticationParams + +#### Parameters + +| Parameter | Attribute | DataType | Description | Allowed Values | +| --- | --- | --- | --- | --- | +| **DataType** | Write | String | Odata type associated with the request. | | +| **Type** | Write | String | Type of scan. | | +| **KeyVaultUrl** | Write | String | An optional property that specifies from which KeyVault the scanner should retrieve credentials. If KeyVault is specified there's no need to specify username, password. | | +| **KeyVaultSecretName** | Write | String | An optional property that specifies KeyVault secret name from which the scanner should retrieve credentials. If KeyVault is specified there's no need to specify username, password. | | +| **Domain** | Write | String | Domain name when using WindowsAuthParams. | | +| **Username** | Write | String | Username when using WindowsAuthParams or the username when choosing SnmpAuthParams with any type other than CommunityString. | | +| **IsGMSAUser** | Write | Boolean | Must be set to true when choosing WindowsAuthParams. | | +| **CommunityString** | Write | String | Community string to use when choosing SnmpAuthParams with CommunityString. | | +| **AuthProtocol** | Write | String | Auth protocol to use with SnmpAuthParams and AuthNoPriv or AuthPriv. Possible values are MD5, SHA1. | | +| **AuthPassword** | Write | String | Auth password to use with SnmpAuthParams and AuthNoPriv or AuthPriv. | | +| **PrivProtocol** | Write | String | Priv protocol to use with SnmpAuthParams and AuthPriv. Possible values are DES, 3DES, AES. | | +| **PrivPassword** | Write | String | Priv password to use with SnmpAuthParams and AuthPriv. | | + +### MSFT_DefenderDeviceAuthenticatedScanDefinitionScanAgent + +#### Parameters + +| Parameter | Attribute | DataType | Description | Allowed Values | +| --- | --- | --- | --- | --- | +| **id** | Write | String | Unique identified for the scan agent. | | +| **machineId** | Write | String | Id of the machine associated with the agent. | | +| **machineName** | Write | String | Name of the machine associated with the agent. | | + + +## Description + +Configures device authenticated scan definitions in Defender. + +## Permissions + +### Microsoft Graph + +To authenticate with the Microsoft Graph API, this resource required the following permissions: + +#### Delegated permissions + +- **Read** + + - None + +- **Update** + + - None + +#### Application permissions + +- **Read** + + - None + +- **Update** + + - None + +## Examples + +### Example 1 + +This example is used to test new resources and showcase the usage of new resources being worked on. +It is not meant to use as a production baseline. + +```powershell +Configuration Example +{ + param( + [Parameter()] + [System.String] + $ApplicationId, + + [Parameter()] + [System.String] + $TenantId, + + [Parameter()] + [System.String] + $CertificateThumbprint + ) + Import-DscResource -ModuleName Microsoft365DSC + node localhost + { + DefenderDeviceAuthenticatedScanDefinition "DefenderDeviceAuthenticatedScanDefinition-MyScan" + { + ApplicationId = $ApplicationId; + CertificateThumbprint = $CertificateThumbprint; + Ensure = "Present"; + IntervalInHours = 1; + IsActive = $True; + Name = "MyScan"; + ScanAuthenticationParams = MSFT_DefenderDeviceAuthenticatedScanDefinitionAuthenticationParams{ + Type = 'NoAuthNoPriv' + DataType = '#microsoft.windowsDefenderATP.api.SnmpAuthParams' + }; + ScannerAgent = MSFT_DefenderDeviceAuthenticatedScanDefinitionScanAgent{ + machineId = '55c636a37ff1a21a3241437eb6ce15881xxxxxx' + machineName = 'WIN-XXXXXXXXXX' + id = 'c819dc6d-f9fe-4d05-8022-88a34766442d_55c636a37ff1a21a3241437eb6ce15881xxxxxxx' + }; + ScanType = "Network"; + Target = "172.1.12.1"; + TenantId = $TenantId; + } + } +} +``` + +### Example 2 + +This example is used to test new resources and showcase the usage of new resources being worked on. +It is not meant to use as a production baseline. + +```powershell +Configuration Example +{ + param( + [Parameter()] + [System.String] + $ApplicationId, + + [Parameter()] + [System.String] + $TenantId, + + [Parameter()] + [System.String] + $CertificateThumbprint + ) + Import-DscResource -ModuleName Microsoft365DSC + node localhost + { + DefenderDeviceAuthenticatedScanDefinition "DefenderDeviceAuthenticatedScanDefinition-MyScan" + { + ApplicationId = $ApplicationId; + CertificateThumbprint = $CertificateThumbprint; + Ensure = "Present"; + IntervalInHours = 24; # Drift + IsActive = $True; + Name = "MyScan"; + ScanAuthenticationParams = MSFT_DefenderDeviceAuthenticatedScanDefinitionAuthenticationParams{ + Type = 'NoAuthNoPriv' + DataType = '#microsoft.windowsDefenderATP.api.SnmpAuthParams' + }; + ScannerAgent = MSFT_DefenderDeviceAuthenticatedScanDefinitionScanAgent{ + machineId = '55c636a37ff1a21a3241437eb6ce15881xxxxxx' + machineName = 'WIN-XXXXXXXXXX' + id = 'c819dc6d-f9fe-4d05-8022-88a34766442d_55c636a37ff1a21a3241437eb6ce15881xxxxxxx' + }; + ScanType = "Network"; + Target = "172.1.12.1"; + TenantId = $TenantId; + } + } +} +``` + +### Example 3 + +This example is used to test new resources and showcase the usage of new resources being worked on. +It is not meant to use as a production baseline. + +```powershell +Configuration Example +{ + param( + [Parameter()] + [System.String] + $ApplicationId, + + [Parameter()] + [System.String] + $TenantId, + + [Parameter()] + [System.String] + $CertificateThumbprint + ) + Import-DscResource -ModuleName Microsoft365DSC + node localhost + { + DefenderDeviceAuthenticatedScanDefinition "DefenderDeviceAuthenticatedScanDefinition-MyScan" + { + ApplicationId = $ApplicationId; + CertificateThumbprint = $CertificateThumbprint; + Ensure = "Absent"; + IntervalInHours = 1; + IsActive = $True; + Name = "MyScan"; + ScanAuthenticationParams = MSFT_DefenderDeviceAuthenticatedScanDefinitionAuthenticationParams{ + Type = 'NoAuthNoPriv' + DataType = '#microsoft.windowsDefenderATP.api.SnmpAuthParams' + }; + ScannerAgent = MSFT_DefenderDeviceAuthenticatedScanDefinitionScanAgent{ + machineId = '55c636a37ff1a21a3241437eb6ce15881xxxxxx' + machineName = 'WIN-XXXXXXXXXX' + id = 'c819dc6d-f9fe-4d05-8022-88a34766442d_55c636a37ff1a21a3241437eb6ce15881xxxxxxx' + }; + ScanType = "Network"; + Target = "172.1.12.1"; + TenantId = $TenantId; + } + } +} +``` + diff --git a/docs/docs/resources/Defender b/docs/docs/resources/defender/DefenderSubscriptionPlan.md similarity index 100% rename from docs/docs/resources/Defender rename to docs/docs/resources/defender/DefenderSubscriptionPlan.md diff --git a/docs/docs/resources/exchange/FabricAdminTenantSettings.md b/docs/docs/resources/fabric/FabricAdminTenantSettings.md similarity index 100% rename from docs/docs/resources/exchange/FabricAdminTenantSettings.md rename to docs/docs/resources/fabric/FabricAdminTenantSettings.md diff --git a/docs/docs/resources/intune/M365DSCRuleEvaluation.md b/docs/docs/resources/general/M365DSCRuleEvaluation.md similarity index 100% rename from docs/docs/resources/intune/M365DSCRuleEvaluation.md rename to docs/docs/resources/general/M365DSCRuleEvaluation.md diff --git a/docs/docs/resources/intune/MdcSubscriptionDefenderPlan.md b/docs/docs/resources/intune/MdcSubscriptionDefenderPlan.md deleted file mode 100644 index aeca74d777..0000000000 --- a/docs/docs/resources/intune/MdcSubscriptionDefenderPlan.md +++ /dev/null @@ -1,98 +0,0 @@ -# MdcSubscriptionDefenderPlan - -## Parameters - -| Parameter | Attribute | DataType | Description | Allowed Values | -| --- | --- | --- | --- | --- | -| **SubscriptionName** | Key | String | The display name of the subscription. | | -| **PlanName** | Key | String | The Defender plan name, for the list all of possible Defender plans refer to Defender for Cloud documentation | | -| **SubscriptionId** | Write | String | The unique identifier of the Azure subscription. | | -| **PricingTier** | Write | String | The pricing tier ('Standard' or 'Free') | | -| **SubPlanName** | Write | String | The Defender sub plan name, for the list all of possible sub plans refer to Defender for Cloud documentation | | -| **Extensions** | Write | String | The extensions offered under the plan, for more information refer to Defender for Cloud documentation | | -| **Ensure** | Write | String | Present ensures the instance exists, absent ensures it is removed. | `Present` | -| **Credential** | Write | PSCredential | Credentials of the workload's Admin | | -| **ApplicationId** | Write | String | Id of the Azure Active Directory application to authenticate with. | | -| **TenantId** | Write | String | Id of the Azure Active Directory tenant used for authentication. | | -| **CertificateThumbprint** | Write | String | Thumbprint of the Azure Active Directory application's authentication certificate to use for authentication. | | -| **ManagedIdentity** | Write | Boolean | Managed ID being used for authentication. | | -| **AccessTokens** | Write | StringArray[] | Access token used for authentication. | | - - -## Description - -Enables or disables Microsoft Defender plans for a subscription in Microsoft Defender for Cloud. -For more information about the available Defender plans, sub plans and plan extensions refer to Defender for Cloud onboarding API documentation. -https://learn.microsoft.com/en-us/rest/api/defenderforcloud/pricings/update?view=rest-defenderforcloud-2024-01-01&tabs=HTTP - - -To have all security features enabled during plan enablement, make sure to assign the required Azure RBAC permissions to the application running this module. -For more information about the required permissions refer to the documentation https://learn.microsoft.com/en-us/azure/defender-for-cloud/permissions. - -## Permissions - -### Microsoft Graph - -To authenticate with the Microsoft Graph API, this resource required the following permissions: - -#### Delegated permissions - -- **Read** - - - None - -- **Update** - - - None - -#### Application permissions - -- **Read** - - - None - -- **Update** - - - None - -## Examples - -### Example 1 - -This example is used to test new resources and showcase the usage of new resources being worked on. -It is not meant to use as a production baseline. - -```powershell -Configuration Example -{ - param( - [Parameter()] - [System.String] - $ApplicationId, - - [Parameter()] - [System.String] - $TenantId, - - [Parameter()] - [System.String] - $CertificateThumbprint - ) - Import-DscResource -ModuleName Microsoft365DSC - node localhost - { - MdcSubscriptionDefenderPlan 'TestSubscription' - { - SubscriptionName = 'MyTestSubscription' - PlanName = 'VirtualMachines' - SubPlanName = 'P2' - PricingTier = 'Standard' - SubscriptionId = 'd620d94d-916d-4dd9-9de5-179292873e20' - ApplicationId = $ApplicationId - TenantId = $TenantId - CertificateThumbprint = $CertificateThumbprint - } - } -} -``` - diff --git a/docs/docs/resources/security-compliance/SentinelAlertRule.md b/docs/docs/resources/sentinel/SentinelAlertRule.md similarity index 100% rename from docs/docs/resources/security-compliance/SentinelAlertRule.md rename to docs/docs/resources/sentinel/SentinelAlertRule.md diff --git a/docs/docs/resources/security-compliance/SentinelSetting.md b/docs/docs/resources/sentinel/SentinelSetting.md similarity index 100% rename from docs/docs/resources/security-compliance/SentinelSetting.md rename to docs/docs/resources/sentinel/SentinelSetting.md diff --git a/docs/docs/resources/security-compliance/SentinelThreatIntelligenceIndicator.md b/docs/docs/resources/sentinel/SentinelThreatIntelligenceIndicator.md similarity index 100% rename from docs/docs/resources/security-compliance/SentinelThreatIntelligenceIndicator.md rename to docs/docs/resources/sentinel/SentinelThreatIntelligenceIndicator.md diff --git a/docs/docs/resources/security-compliance/SentinelWatchlist.md b/docs/docs/resources/sentinel/SentinelWatchlist.md similarity index 100% rename from docs/docs/resources/security-compliance/SentinelWatchlist.md rename to docs/docs/resources/sentinel/SentinelWatchlist.md diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 7c0b1bad20..a45a6f9a3d 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -66,14 +66,20 @@ nav: - 'Personas': 'concepts/personas.md' - Resources: - 'Overview': 'resources/overview.md' + - 'Azure': 'resources/azure' - 'Azure AD': 'resources/azure-ad' + - 'Azure DevOps': 'resources/azure-devops' + - 'Defender': 'resources/defender' - 'Exchange': 'resources/exchange' + - 'Fabric': 'resources/fabric' + - 'General': 'resources/general' - 'Intune': 'resources/intune' - 'Office365': 'resources/office365' - 'OneDrive': 'resources/onedrive' - 'Planner': 'resources/planner' - 'Power Platform': 'resources/power-platform' - 'Security & Compliance': 'resources/security-compliance' + - 'Sentinel': 'resources/sentinel' - 'SharePoint': 'resources/sharepoint' - 'Teams': 'resources/teams' - About: