Skip to content

Commit 1a449cd

Browse files
committed
Merge branch 'main' into dev
2 parents cb8fd8e + 34afdb7 commit 1a449cd

67 files changed

Lines changed: 337 additions & 589 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

.github/workflows/publish-psmodule-preview.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ name: Build and Publish PowerShell Module (Preview)
33
on:
44
push:
55
branches:
6-
- main
6+
- dev
77
paths:
88
- 'src/powershell/**'
99
workflow_dispatch:
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Build and Publish PowerShell Module (Production)
2+
3+
on:
4+
workflow_dispatch:
5+
6+
jobs:
7+
build-and-publish:
8+
runs-on: windows-latest
9+
10+
steps:
11+
- name: Checkout repository
12+
uses: actions/checkout@v4
13+
14+
- name: Install Prerequisites
15+
run: .\build\powershell\Install-Prerequisites.ps1
16+
shell: pwsh
17+
18+
- name: Build PowerShell Module (Production)
19+
run: |
20+
.\build\powershell\Build-PSModule.ps1 -BaseDirectory $PWD -ProductionBuild
21+
shell: pwsh
22+
23+
- name: Publish PowerShell Module (Production)
24+
run: |
25+
$secureApiKey = ConvertTo-SecureString -String $env:NUGET_API_KEY -AsPlainText -Force
26+
.\build\powershell\Publish-PSModule.ps1 -NuGetApiKey $secureApiKey
27+
shell: pwsh
28+
env:
29+
NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }}

build/Update-Recommendations.ps1

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -405,7 +405,7 @@ foreach ($file in $testFiles) {
405405
# Create a hashtable to store the testid and docsTitle
406406
Write-Host "Checking $($file.BaseName)"
407407

408-
$content = Get-Content -Path $file.FullName -Raw
408+
$content = (Get-Content -Path $file.FullName -Raw) -replace '\r\n', "`n"
409409

410410
$docRawContent = $recommendations[$testId].Content # Includes front matter and markdown content
411411
$frontMatter = Get-FrontMatterList -content $docRawContent
@@ -443,16 +443,16 @@ foreach ($file in $testFiles) {
443443
if ($testData.SfiPillar -ne $frontMatter['# sfipillar']) {
444444
$update.SfiPillar = $frontMatter['# sfipillar']
445445
}
446-
# Process minimumlicense - split by comma and trim spaces
447-
if ($frontMatter['# minimumlicense']) {
448-
$minimumLicenseArray = $frontMatter['# minimumlicense'] -split ',' | ForEach-Object { $_.Trim() }
449-
# Compare arrays - convert both to sorted strings for comparison
450-
$currentLicenses = ($testData.MinimumLicense | Sort-Object) -join ','
451-
$newLicenses = ($minimumLicenseArray | Sort-Object) -join ','
452-
if ($currentLicenses -ne $newLicenses) {
453-
$update.CompatibleLicense = $minimumLicenseArray
454-
}
455-
}
446+
# # Process minimumlicense - split by comma and trim spaces MF: We don't use doc metadata for minimum license in the current implementation, so skipping for now.
447+
# if ($frontMatter['# minimumlicense']) {
448+
# $minimumLicenseArray = $frontMatter['# minimumlicense'] -split ',' | ForEach-Object { $_.Trim() }
449+
# # Compare arrays - convert both to sorted strings for comparison
450+
# $currentLicenses = ($testData.MinimumLicense | Sort-Object) -join ','
451+
# $newLicenses = ($minimumLicenseArray | Sort-Object) -join ','
452+
# if ($currentLicenses -ne $newLicenses) {
453+
# $update.CompatibleLicense = $minimumLicenseArray
454+
# }
455+
# }
456456
#$frontMatter['# pillar'] #Code to identity for now until we get the front-matter in
457457
if (-not $testData.Pillar) {
458458
$update.Pillar = 'Identity'
@@ -474,8 +474,8 @@ foreach ($file in $testFiles) {
474474

475475
Write-Host "$testId Title: $docsTitle"
476476
# Find everything before <!--- Results ---> and replace it with the recommendations from the docs
477-
# Ensure docsContent ends with exactly one newline so the separator starts at column 0
478-
$docsContent = $docsContent.TrimEnd() + "`n"
477+
# Normalize line endings to LF and ensure content ends with exactly one newline
478+
$docsContent = ($docsContent -replace '\r\n', "`n").TrimEnd() + "`n"
479479

480480
$seperator = $content.IndexOf('<!--- Results --->')
481481
if ($seperator -gt 0) {

build/commands/Set-TestMetadata.ps1

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,9 @@ function Set-TestMetadata {
7171
[string[]]
7272
$CompatibleLicense,
7373

74+
[string[]]
75+
$Service,
76+
7477
[string]
7578
$Pillar,
7679

@@ -120,7 +123,10 @@ function Set-TestMetadata {
120123

121124
$text = [System.Text.StringBuilder]::new()
122125
$null = $text.AppendLine('[ZtTest(')
126+
$activeKeys = $Definition.Keys | Where-Object { $null -ne $data[$_] }
123127
foreach ($pair in $Definition.GetEnumerator()) {
128+
# Skip null values entirely — don't write them to the attribute
129+
if ($null -eq $data[$pair.Key]) { continue }
124130
switch ($pair.Value) {
125131
'string[]' {
126132
$entries = foreach ($item in $data[$pair.Key]) {
@@ -140,7 +146,7 @@ function Set-TestMetadata {
140146
}
141147
}
142148
$line = "`t$($pair.Key) = $($valueText),"
143-
if ($pair.Key -eq $($Definition.Keys)[-1]) {
149+
if ($pair.Key -eq $activeKeys[-1]) {
144150
$line = $line.TrimEnd(',')
145151
}
146152
$null = $text.AppendLine($line)
@@ -218,6 +224,7 @@ function Set-TestMetadata {
218224
ImplementationCost = 'string'
219225
MinimumLicense = 'string[]'
220226
CompatibleLicense = 'string[]'
227+
Service = 'string[]'
221228
Pillar = 'string'
222229
RiskLevel = 'string'
223230
SfiPillar = 'string'
Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1-
When the Global Secure Access client is not deployed to managed endpoints, those devices operate outside the organization's Security Service Edge controls. Threat actors can exploit unprotected endpoints to establish initial access through phishing or drive-by downloads, then move laterally or exfiltrate data without triggering network-level security policies.
1+
Comprehensive deployment of the Global Secure Access client is foundational to achieving Zero Trust network security. If you don't deploy the Global Secure Access client to managed endpoints, those devices operate outside the organization's Security Service Edge controls. Threat actors can exploit unprotected endpoints to establish initial access, move laterally, or exfiltrate data without triggering network-level security policies.
22

3-
Devices lacking the Global Secure Access client cannot benefit from compliant network checks in Conditional Access policies, source IP restoration for accurate sign-in logging, or tenant restrictions that prevent unauthorized access to external organizations. Credential theft and token replay attacks become more difficult to detect when traffic from these endpoints bypasses the security perimeter. Organizations with incomplete client deployment create a fragmented security posture where protected and unprotected devices coexist, allowing threat actors to identify and target the weakest links.
3+
Without the Global Secure Access client:
44

5-
The gap between managed device counts (Entra ID joined and Hybrid joined devices) and Global Secure Access active device counts represents the attack surface that remains unmonitored. Managed endpoints that lack the client also cannot access private applications through Microsoft Entra Private Access, potentially driving users to insecure workarounds. Ensuring comprehensive client deployment is foundational to achieving Zero Trust network security—without the client, the security controls cannot be enforced regardless of how well policies are configured.
5+
- Devices can't benefit from compliant network checks in Conditional Access policies, source IP restoration, or tenant restrictions.
6+
- Credential theft and token replay attacks are more difficult to detect when traffic bypasses the security perimeter.
7+
- Managed endpoints can't access private applications through Microsoft Entra Private Access.
68

79
**Remediation action**
810
- Install the Global Secure Access client:
@@ -13,3 +15,4 @@ The gap between managed device counts (Entra ID joined and Hybrid joined devices
1315
- Monitor the Global Secure Access client health and connection status by using the [Global Secure Access dashboard](https://learn.microsoft.com/entra/global-secure-access/concept-traffic-dashboard?wt.mc_id=zerotrustrecommendations_automation_content_cnl_csasci).
1416
<!--- Results --->
1517
%TestResult%
18+
Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
1-
When TLS inspection is enabled in Global Secure Access, traffic passing through the Security Service Edge undergoes decryption to enable deep packet inspection, URL categorization, and threat detection. Bypass rules are sometimes necessary for traffic that cannot be inspected due to technical constraints (certificate pinning) or compliance requirements. However, without regular review, bypass rules accumulate over time as temporary exceptions become permanent, applications are decommissioned while their bypass rules remain, or initial justifications become obsolete. Threat actors specifically target uninspected traffic channels, knowing that malware command-and-control communications, data exfiltration, and credential theft over HTTPS will evade detection when traffic bypasses TLS inspection. A policy that has not been modified in over 90 days may contain stale bypass rules that no longer serve a valid business purpose, effectively creating blind spots in the organization's network security posture. Organizations should maintain a review cadence where TLS inspection policies are audited quarterly at minimum, validating that each bypass rule remains necessary and appropriately scoped.
1+
Transport Layer Security (TLS) inspection bypass rules create exceptions where encrypted traffic skips deep packet inspection. Without regular review, bypass rules accumulate as temporary exceptions become permanent, applications are decommissioned while their rules remain, or initial justifications become obsolete. Threat actors target uninspected traffic channels. They know that malware command-and-control communications, data exfiltration, and credential theft over HTTPS evade detection when traffic bypasses TLS inspection. Policies not modified in over 90 days might contain stale bypass rules that create blind spots in your network security posture.
22

33
**Remediation action**
44

5-
1. [Review and manage TLS inspection policies in the Microsoft Entra admin center under Global Secure Access > Secure > TLS inspection](https://learn.microsoft.com/en-us/graph/api/resources/networkaccess-tlsinspectionpolicy)
6-
2. [Understand TLS inspection rule configuration and bypass actions](https://learn.microsoft.com/en-us/graph/api/resources/networkaccess-tlsinspectionrule)
7-
3. Establish a quarterly review process for TLS inspection bypass rules, documenting business justification for each bypass rule and removing rules that are no longer necessary
8-
4. Required role: Global Secure Access Administrator or Security Administrator
9-
5+
- Establish a quarterly review process for TLS inspection bypass rules, document a business justification for each bypass rule, and remove rules that are no longer necessary.
6+
- [Review and manage TLS inspection policies](https://learn.microsoft.com/graph/api/resources/networkaccess-tlsinspectionpolicy?wt.mc_id=zerotrustrecommendations_automation_content_cnl_csasci) in the Microsoft Entra admin center under **Global Secure Access** > **Secure** > **TLS inspection**.
7+
- Review the steps in [Configure Transport Layer Security inspection policies](https://learn.microsoft.com/entra/global-secure-access/how-to-transport-layer-security?wt.mc_id=zerotrustrecommendations_automation_content_cnl_csasci) to understand how to modify or remove bypass rules as part of the review process.
108
<!--- Results --->
119
%TestResult%
10+

src/powershell/tests/Test-Assessment.27001.ps1

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<#
1+
<#
22
.SYNOPSIS
33
Validates that TLS inspection bypass policies are regularly reviewed to prevent security protection gaps.
44
@@ -15,17 +15,17 @@
1515

1616
function Test-Assessment-27001 {
1717
[ZtTest(
18-
Category = 'Global Secure Access',
19-
ImplementationCost = 'Medium',
20-
MinimumLicense = 'Entra_Premium_Internet_Access',
21-
CompatibleLicense = ('Entra_Premium_Internet_Access'),
22-
Pillar = 'Network',
23-
RiskLevel = 'Medium',
24-
SfiPillar = 'Protect networks',
25-
TenantType = ('Workforce'),
26-
TestId = 27001,
27-
Title = 'TLS inspection bypass policies are regularly reviewed to prevent security protection gaps',
28-
UserImpact = 'Low'
18+
Category = 'Global Secure Access',
19+
ImplementationCost = 'Medium',
20+
MinimumLicense = ('Entra_Premium_Internet_Access'),
21+
CompatibleLicense = ('Entra_Premium_Internet_Access'),
22+
Pillar = 'Network',
23+
RiskLevel = 'Medium',
24+
SfiPillar = 'Protect networks',
25+
TenantType = ('Workforce'),
26+
TestId = 27001,
27+
Title = 'TLS inspection bypass rules are regularly reviewed',
28+
UserImpact = 'Low'
2929
)]
3030
[CmdletBinding()]
3131
param()
Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
1-
TLS inspection enables Global Secure Access to decrypt and analyze encrypted HTTPS traffic for threats, malicious content, and policy violations. When TLS inspection fails for a connection, that traffic bypasses security controls entirely, allowing potential malware delivery, command-and-control communications, or data exfiltration to proceed undetected. Failure rates above 1% indicate systemic issues such as certificate trust problems on endpoints, incompatible applications using certificate pinning without proper bypass rules, or certificate authority configuration errors. Threat actors may intentionally craft connections designed to cause TLS inspection failures, knowing the resulting traffic will evade detection. A sustained high failure rate represents an expanding blind spot in the organization's security posture, as each failed inspection is a missed opportunity to detect and block malicious activity. Organizations should monitor TLS inspection success rates and investigate the root causes of failures to maintain comprehensive visibility into encrypted traffic.
1+
By using Transport Layer Security (TLS) inspection, Global Secure Access can decrypt encrypted HTTPS traffic and check it for threats, malicious content, and policy violations. If TLS inspection fails for a connection, that traffic bypasses security controls. Inspection failures can let potential malware delivery, command-and-control communications, or data exfiltration go undetected.
22

3-
**Remediation action**
3+
Failure rates above 1% point to systemic problems. These problems include certificate trust issues on endpoints, incompatible applications that use certificate pinning without proper bypass rules, or certificate authority configuration errors. Threat actors can also intentionally create connections that cause TLS inspection failures.
44

5-
- [Configure diagnostic settings to export traffic logs to Log Analytics](https://learn.microsoft.com/en-us/entra/global-secure-access/how-to-view-traffic-logs#configure-diagnostic-settings-to-export-logs)
6-
- [Review TLS inspection concepts and troubleshooting](https://learn.microsoft.com/en-us/entra/global-secure-access/concept-transport-layer-security)
7-
- [For destinations with certificate pinning, add TLS bypass rules](https://learn.microsoft.com/en-us/entra/global-secure-access/how-to-transport-layer-security)
5+
**Remediation action**
86

7+
- [Configure diagnostic settings to export traffic logs](https://learn.microsoft.com/entra/global-secure-access/how-to-view-traffic-logs?wt.mc_id=zerotrustrecommendations_automation_content_cnl_csasci#configure-diagnostic-settings-to-export-logs) to a Log Analytics workspace. Use these logs to monitor TLS inspection success rates and investigate the root causes of failures.
8+
- Follow the steps in [Troubleshoot Global Secure Access Transport Layer Security inspection errors](https://learn.microsoft.com/entra/global-secure-access/troubleshoot-transport-layer-security?wt.mc_id=zerotrustrecommendations_automation_content_cnl_csasci) to resolve common inspection failures.
9+
- For destinations with certificate pinning, [add TLS bypass rules](https://learn.microsoft.com/entra/global-secure-access/how-to-transport-layer-security?wt.mc_id=zerotrustrecommendations_automation_content_cnl_csasci) to reduce failure rates while keeping inspection for other traffic.
910
<!--- Results --->
1011
%TestResult%
12+

src/powershell/tests/Test-Assessment.27003.ps1

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<#
1+
<#
22
.SYNOPSIS
33
TLS inspection failure rate remains below 1% to ensure consistent traffic visibility.
44
.DESCRIPTION
@@ -17,17 +17,17 @@
1717

1818
function Test-Assessment-27003 {
1919
[ZtTest(
20-
Category = 'Global Secure Access',
21-
ImplementationCost = 'Medium',
22-
MinimumLicense = ('Entra_Premium_Internet_Access'),
23-
CompatibleLicense = ('Entra_Premium_Internet_Access'),
24-
Pillar = 'Network',
25-
RiskLevel = 'High',
26-
SfiPillar = 'Protect networks',
27-
TenantType = ('Workforce'),
28-
TestId = 27003,
29-
Title = 'TLS inspection failure rate remains below 1% to ensure consistent traffic visibility',
30-
UserImpact = 'Medium'
20+
Category = 'Global Secure Access',
21+
ImplementationCost = 'Medium',
22+
MinimumLicense = ('Entra_Premium_Internet_Access'),
23+
CompatibleLicense = ('Entra_Premium_Internet_Access'),
24+
Pillar = 'Network',
25+
RiskLevel = 'High',
26+
SfiPillar = 'Protect networks',
27+
TenantType = ('Workforce'),
28+
TestId = 27003,
29+
Title = 'TLS inspection failure rate is below 1%',
30+
UserImpact = 'Medium'
3131
)]
3232
[CmdletBinding()]
3333
param()
Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
Global Secure Access maintains a system bypass list of destinations that are automatically excluded from TLS inspection due to known incompatibilities such as certificate pinning, mutual TLS requirements, or other technical constraints. When administrators create custom bypass rules that duplicate destinations already covered by the system bypass list, these rules are redundant and serve no functional purpose. Redundant rules consume policy capacity (TLS inspection supports up to 1,000 rules and 8,000 destinations per tenant), create administrative overhead during policy reviews, and may cause confusion about which rules are actually necessary for the organization's specific requirements versus which are duplicating built-in protections. Maintaining a clean policy configuration with only necessary custom bypass rules improves manageability, makes security audits more straightforward, and ensures that policy capacity is available for legitimate business requirements rather than duplicated system functionality.
1+
Global Secure Access maintains a system bypass list of destinations that are automatically excluded from Transport Layer Security (TLS) inspection. These bypass destinations represent known incompatibilities such as certificate pinning, mutual TLS requirements, or other technical constraints. Custom bypass rules that duplicate destinations in the system bypass list are redundant and serve no functional purpose.
22

3-
**Remediation action**
4-
5-
Review and remove redundant custom bypass rules in the Microsoft Entra admin center under Global Secure Access > Secure > TLS inspection policies
3+
Redundant rules consume policy capacity, create administrative overhead, and can cause confusion about which rules are necessary. TLS inspection supports up to 1,000 rules and 8,000 destinations per tenant. Maintaining a clean policy configuration with only necessary custom bypass rules improves manageability, simplifies security audits, and ensures that policy capacity is available for legitimate business requirements.
64

7-
Reference the current system bypass list:
8-
- [FAQ: What destinations are included in the system bypass?](https://learn.microsoft.com/en-us/entra/global-secure-access/faq-transport-layer-security#what-destinations-are-included-in-the-system-bypass)
5+
**Remediation action**
96

7+
- Review and remove redundant custom TLS inspection bypass rules in the Microsoft Entra admin center. Navigate to **Global Secure Access** > **Secure** > **TLS inspection policies**.
8+
- Review [the destinations included in the system bypass list](https://learn.microsoft.com/entra/global-secure-access/faq-transport-layer-security?wt.mc_id=zerotrustrecommendations_automation_content_cnl_csasci#what-destinations-are-included-in-the-system-bypass).
109
<!--- Results --->
1110
%TestResult%
11+

0 commit comments

Comments
 (0)