Merge pull request #2 from BNWEIN/Dev

Dev to Main

.gitignore

@@ -1,2 +1,3 @@
 /[Oo]utput
-/.vscode
+/.vscode
+/.localonly

CIPPAPIModule.psd1 → CIPPAPIModule/CIPPAPIModule.psd1

@@ -12,7 +12,7 @@
 RootModule = 'CIPPAPIModule.psm1'
 
 # Version number of this module.
-ModuleVersion = '1.0.9'
+ModuleVersion = '1.1.0'
 
 # Supported PSEditions
 # CompatiblePSEditions = @()
@@ -101,7 +101,7 @@ PrivateData = @{
         # LicenseUri = ''
 
         # A URL to the main website for this project.
-        # ProjectUri = ''
+         ProjectUri = 'https://github.com/BNWEIN/CIPPAPIModule/'
 
         # A URL to an icon representing this module.
         # IconUri = ''

CIPPAPIModule/private/Connect-CIPP.ps1

@@ -0,0 +1,46 @@
+<#
+.SYNOPSIS
+Connects to the CIPP API using the provided credentials.
+
+.DESCRIPTION
+The Connect-CIPP function establishes a connection to the CIPP API by obtaining an access token using the client credentials flow. It requires the CIPP API URL, client ID, client secret, and tenant ID as input parameters.
+
+.PARAMETER CIPPAPIUrl
+The URL of the CIPP API.
+
+.PARAMETER CIPPClientID
+The client ID used to authenticate with the CIPP API.
+
+.PARAMETER CIPPClientSecret
+The client secret used to authenticate with the CIPP API.
+
+.PARAMETER TenantID
+The ID of the tenant associated with the CIPP API.
+
+.EXAMPLE
+Connect-CIPP -CIPPAPIUrl "https://api.cipp.com" -CIPPClientID "12345678-1234-1234-1234-1234567890ab" -CIPPClientSecret "MyClientSecret" -TenantID "98765432-4321-4321-4321-0987654321ba"
+Connects to the CIPP API using the specified credentials.
+
+#>
+function Connect-CIPP {
+    [CmdletBinding()]
+    Param(
+        [string]$CIPPAPIUrl,
+        [string]$CIPPClientID,
+        [string]$CIPPClientSecret,
+        [string]$TenantID
+    )
+
+    $Script:AuthBody = @{
+        client_id     = $script:CIPPClientID
+        client_secret = $script:CIPPClientSecret
+        scope         = "api://$($script:CIPPClientID)/.default"
+        grant_type    = 'client_credentials'
+    }
+    $token = Invoke-RestMethod -Uri "https://login.microsoftonline.com/$script:TenantId/oauth2/v2.0/token" -Method POST -Body $AuthBody
+
+    $script:AuthHeader = @{ Authorization = "Bearer $($token.access_token)" }
+    $script:TokenAcquiredTime = Get-Date
+    $script:ExpiresIn = $token.expires_in
+
+}

CIPPAPIModule/private/Get-TokenExpiry.ps1

@@ -0,0 +1,34 @@
+<#
+.SYNOPSIS
+Calculates the expiry date and time for a token.
+
+.DESCRIPTION
+The Get-TokenExpiry function calculates the expiry date and time for a token based on the token's expiration time in seconds.
+
+.PARAMETER ExpiresIn
+Specifies the expiration time of the token in seconds. If not provided, the function uses the default expiration time stored in the $script:ExpiresIn variable.
+
+.OUTPUTS
+System.DateTime
+The calculated expiry date and time for the token.
+
+.EXAMPLE
+Get-TokenExpiry -ExpiresIn 3600
+Calculates the expiry date and time for a token that expires in 3600 seconds (1 hour).
+
+#>
+
+function Get-TokenExpiry {
+    [CmdletBinding()]
+    [OutputType([DateTime])]
+    param (
+        [Parameter(Mandatory = $false)]
+        [int64]$ExpiresIn = $script:ExpiresIn
+    )
+    if ($script:ExpiresIn -eq $null) {
+        return
+    } else {
+        $Script:ExpiryDateTime = $script:TokenAcquiredTime.AddSeconds($script:ExpiresIn)
+        Write-Verbose "Calculated token expiry as $Script:ExpiryDateTime"
+    }
+}

private/Invoke-CIPPPreFlightCheck.ps1 → CIPPAPIModule/private/Invoke-CIPPPreFlightCheck.ps1

@@ -1,3 +1,17 @@
+<#
+.SYNOPSIS
+    Invokes the pre-flight check before connecting to the CIPP API.
+
+.DESCRIPTION
+    This function performs a pre-flight check before connecting to the CIPP API. It checks if the required CIPP API information is available and if the token has expired. If the information is not found or the token has expired, it connects to the CIPP API using the provided credentials.
+
+.PARAMETER None
+    This function does not accept any parameters.
+
+.EXAMPLE
+    Invoke-CIPPPreFlightCheck
+
+#>
 function Invoke-CIPPPreFlightCheck {
     [CmdletBinding()]
     param ()

CIPPAPIModule/public/CIPP/Core/Get-CIPPAccessCheck.ps1

@@ -0,0 +1,33 @@
+<#
+.SYNOPSIS
+    Performs a tenant access check for the specified customer tenant ID.
+
+.DESCRIPTION
+    The Get-CIPPAccessCheck function performs a tenant access check for the specified customer tenant ID. It sends a POST request to the "/api/execaccesschecks" endpoint with the provided tenant ID.
+
+.PARAMETER CustomerTenantID
+    Specifies the customer tenant ID for which the access check needs to be performed.
+
+.EXAMPLE
+    Get-CIPPAccessCheck -CustomerTenantID "12345678"
+    Runs a tenant access check for the customer tenant ID "12345678".
+
+#>
+function Get-CIPPAccessCheck {
+    [CmdletBinding()]
+    Param(
+        [Parameter(Mandatory = $true)]
+        [string[]]$CustomerTenantID
+    )
+
+    Write-Verbose "Running tenant access check for $CustomerTenantID"
+    $Endpoint = "/api/execaccesschecks"
+
+    $params = @{
+        tenants = "true"
+    }
+    $body = @{
+        tenantid        = $CustomerTenantID
+    }
+    Invoke-CIPPRestMethod -Endpoint $Endpoint -Body $body -Params $params -Method POST
+}

CIPPAPIModule/public/CIPP/Core/Get-CIPPExecAPIPermissionsList.ps1

@@ -0,0 +1,26 @@
+<#
+.SYNOPSIS
+Retrieves the list of CIPP execution API permissions.
+
+.DESCRIPTION
+The Get-CIPPExecAPIPermissionsList function retrieves the list of CIPP execution API permissions by making a REST API call to the specified endpoint.
+
+.PARAMETER None
+This function does not accept any parameters.
+
+.EXAMPLE
+Get-CIPPExecAPIPermissionsList
+Retrieves the list of CIPP execution API permissions.
+
+#>
+
+function Get-CIPPExecAPIPermissionsList {
+    [CmdletBinding()]
+    Param()
+
+    Write-Verbose "Getting CIPP Logs"
+    $endpoint = "/api/ExecAPIPermissionList"
+
+    Invoke-CIPPRestMethod -Endpoint $endpoint
+}
+

CIPPAPIModule/public/CIPP/Core/Get-CIPPKnownIPDB.ps1

@@ -0,0 +1,40 @@
+<#
+.SYNOPSIS
+Retrieves the Known IP Database for a specific customer tenant.
+
+.DESCRIPTION
+The Get-CIPPKnownIPDB function retrieves the Known IP Database for a specific customer tenant by making a REST API call to the "/api/listknownipdb" endpoint.
+
+.PARAMETER CustomerTenantID
+Specifies the ID of the customer tenant for which to retrieve the Known IP Database.
+
+.EXAMPLE
+Get-CIPPKnownIPDB -CustomerTenantID "12345678"
+Retrieves the Known IP Database for the customer tenant with ID "12345678".
+
+.INPUTS
+None.
+
+.OUTPUTS
+System.Object
+
+.NOTES
+This function requires the Invoke-CIPPRestMethod function to be available.
+
+.LINK
+Invoke-CIPPRestMethod
+#>
+function Get-CIPPKnownIPDB {
+    [CmdletBinding()]
+    Param(
+        [Parameter(Mandatory = $false)]
+        [string]$CustomerTenantID
+    )
+
+    Write-Verbose "Getting Known IP Database for $CustomerTenantID"
+    $endpoint = "/api/listknownipdb"
+    $params = @{
+        tenantfilter = $CustomerTenantID
+    }
+    Invoke-CIPPRestMethod -Endpoint $endpoint -Params $params
+}

CIPPAPIModule/public/CIPP/Core/Get-CIPPLogs.ps1

@@ -0,0 +1,25 @@
+<#
+.SYNOPSIS
+Retrieves CIPP logs from the API.
+
+.DESCRIPTION
+The Get-CIPPLogs function retrieves logs from the CIPP API by invoking the "/api/ListLogs" endpoint.
+
+.PARAMETER None
+This function does not accept any parameters.
+
+.EXAMPLE
+Get-CIPPLogs
+Retrieves CIPP logs from the API.
+
+#>
+
+function Get-CIPPLogs {
+    [CmdletBinding()]
+    Param()
+
+    Write-Verbose "Getting CIPP Logs"
+    $endpoint = "/api/ListLogs"
+
+    Invoke-CIPPRestMethod -Endpoint $endpoint
+}

CIPPAPIModule/public/CIPP/Core/Get-CIPPPublicPhishingCheck.ps1

@@ -0,0 +1,29 @@
+<#
+.SYNOPSIS
+Retrieves public phishing check for a specific customer tenant.
+
+.DESCRIPTION
+The Get-CIPPPublicPhishingCheck function retrieves the public phishing check for a specific customer tenant. It makes an API call to the "/api/publicphishingcheck" endpoint with the provided tenant ID.
+
+.PARAMETER CustomerTenantID
+The ID of the customer tenant for which to retrieve the public phishing check.
+
+.EXAMPLE
+Get-CIPPPublicPhishingCheck -CustomerTenantID "12345"
+Retrieves the public phishing check for the customer tenant with the ID "12345".
+
+#>
+function Get-CIPPPublicPhishingCheck {
+    [CmdletBinding()]
+    Param(
+        [Parameter(Mandatory = $true)]
+        [string]$CustomerTenantID
+    )
+
+    Write-Verbose "Getting public phishing check $CustomerTenantID"
+    $endpoint = "/api/publicphishingcheck"
+    $params = @{
+        tenantfilter = $CustomerTenantID
+    }
+    Invoke-CIPPRestMethod -Endpoint $endpoint -Params $params
+}

CIPPAPIModule/public/CIPP/Core/Set-CIPPExecCPVPerms.ps1

@@ -0,0 +1,42 @@
+<#
+.SYNOPSIS
+Sets the CPV (Customer Provided Values) permissions for a specific customer tenant.
+
+.DESCRIPTION
+The Set-CIPPExecCPVPerms function is used to refresh the CPV permissions for a specified customer tenant. It calls the Invoke-CIPPRestMethod function internally to make the REST API call.
+
+.PARAMETER CustomerTenantID
+Specifies the ID of the customer tenant for which the CPV permissions need to be refreshed. This parameter is mandatory.
+
+.PARAMETER resetsp
+Specifies whether to reset the Stored Procedure (SP) associated with the CPV permissions. The valid values are "true" and "false". This parameter is optional and defaults to "false".
+
+.EXAMPLE
+Set-CIPPExecCPVPerms -CustomerTenantID "12345678-1234-1234-1234-1234567890AB" -resetsp "true"
+Refreshes the CPV permissions for the customer tenant with the ID "12345678-1234-1234-1234-1234567890AB" and resets the associated Stored Procedure.
+
+.EXAMPLE
+Set-CIPPExecCPVPerms -CustomerTenantID "87654321-4321-4321-4321-0987654321BA"
+Refreshes the CPV permissions for the customer tenant with the ID "87654321-4321-4321-4321-0987654321BA" without resetting the associated Stored Procedure.
+#>
+function Set-CIPPExecCPVPerms {
+    [CmdletBinding()]
+        Param(
+            [Parameter(Mandatory = $true)]
+            [guid]$CustomerTenantID,
+            [Parameter(Mandatory = $false)]
+            [ValidateSet(
+                "true",
+                "false" 
+                )]
+            [string]$resetsp = "false"
+        )
+
+    Write-Verbose "Refreshing CPV for $CustomerTenantID"
+    $endpoint = "/api/execcpvpermissions"
+    $params = @{
+        tenantfilter    = $CustomerTenantID
+        ResetSP         = $resetsp
+    }
+    Invoke-CIPPRestMethod -Endpoint $endpoint -Params $params
+}

CIPPAPIModule/public/CIPP/Settings/Get-CIPPVersion.ps1

@@ -0,0 +1,24 @@
+<#
+.SYNOPSIS
+    Retrieves the version of the CIPP application.
+
+.DESCRIPTION
+    The Get-CIPPVersion function retrieves the version of the CIPP application by making a REST API call to the "/api/Getversion" endpoint.
+
+.PARAMETER None
+    This function does not accept any parameters.
+
+.EXAMPLE
+    Get-CIPPVersion
+    Retrieves the version of the CIPP application.
+
+#>
+function Get-CIPPVersion {
+    [CmdletBinding()]
+    Param()
+
+    Write-Verbose "Getting CIPP Version"
+    $endpoint = "/api/Getversion"
+
+    Invoke-CIPPRestMethod -Endpoint $endpoint
+}

public/Email-Exchange/Add-CIPPContact.ps1 → CIPPAPIModule/public/Email-Exchange/Add-CIPPContact.ps1

@@ -1,3 +1,30 @@
+<#
+.SYNOPSIS
+Adds a contact to a customer's tenant.
+
+.DESCRIPTION
+The Add-CIPPContact function adds a contact to a customer's tenant using the CIPP API. It requires the customer's tenant ID, display name, external email address, first name, and last name as mandatory parameters.
+
+.PARAMETER CustomerTenantID
+The ID of the customer's tenant.
+
+.PARAMETER DisplayName
+The display name of the contact.
+
+.PARAMETER ExternalEmailAddress
+The external email address of the contact.
+
+.PARAMETER FirstName
+The first name of the contact.
+
+.PARAMETER LastName
+The last name of the contact.
+
+.EXAMPLE
+Add-CIPPContact -CustomerTenantID "7ced1621-b8f7-4231-868c-bc6b1a2f1778" -DisplayName "John Doe" -ExternalEmailAddress "john.doe@example.com" -FirstName "John" -LastName "Doe"
+Adds a contact with the specified details to the customer's tenant.
+
+#>
 function Add-CIPPContact {
     [CmdletBinding()]
         Param(