Skip to content

detection

napt.detection

Detection script generation for Intune Win32 apps.

This module generates PowerShell detection scripts for Intune Win32 app deployments. Scripts check Windows uninstall registry keys for installed software and version information using CMTrace-formatted logging.

Detection Logic
  • Checks HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall (always)
  • Checks HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall (always)
  • Checks HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall (only on 64-bit OS with 64-bit PowerShell process)
  • Checks HKCU:\SOFTWARE\Wow6432Node\Microsoft\Windows\CurrentVersion\Uninstall (only on 64-bit OS with 64-bit PowerShell process)
  • Matches by DisplayName (using AppName from recipe or MSI ProductName)
  • Compares version (exact or minimum version match based on config)
  • Provides verbose logging with detailed detection results, registry paths, installed vs expected versions, and match type information
Installer Type Filtering

Scripts filter registry entries based on installer type to prevent false matches when both MSI and EXE versions of software exist:

  • MSI installers (strict): Only matches registry entries with WindowsInstaller=1. Prevents false matches with EXE versions.
  • Non-MSI installers (permissive): Matches ANY registry entry. Handles EXE installers that run embedded MSIs internally.
Logging
  • Primary (System): C:\ProgramData\Microsoft\IntuneManagementExtension\Logs\NAPTDetections.log
  • Primary (User): C:\ProgramData\Microsoft\IntuneManagementExtension\Logs\NAPTDetectionsUser.log
  • Fallback (System): C:\ProgramData\NAPT\NAPTDetections.log
  • Fallback (User): %LOCALAPPDATA%\NAPT\NAPTDetectionsUser.log
  • Log rotation: 2-file rotation (.log and .log.old), configurable max size (default: 3MB)
  • Format: CMTrace format for compatibility with Intune diagnostics
  • Features: Write permission testing with automatic fallback to alternate locations, verbose component-based logging with dynamic component names based on app name and version, detailed detection workflow logging
Example

Generate detection script: 

from pathlib import Path
from napt.detection import DetectionConfig, generate_detection_script

config = DetectionConfig(
    app_name="Google Chrome",
    version="131.0.6778.86",
    log_format="cmtrace",
    log_level="INFO",
)
script_path = generate_detection_script(
    config=config,
    output_path=Path("builds/chrome/131.0.6778.86/Google-Chrome-131.0.6778.86-Detection.ps1"),
)

Note

Detection scripts are saved as siblings to the packagefiles directory to prevent them from being included in the .intunewin package. They should be uploaded separately to Intune alongside the package.

DetectionConfig dataclass

Configuration for detection script generation.

Attributes:

Name Type Description
app_name str

Application name to search for in registry DisplayName.
version str

Expected version string to match.
log_format LogFormat

Log format (currently only "cmtrace" supported).
log_level LogLevel

Minimum log level (INFO, WARNING, ERROR, DEBUG).
log_rotation_mb int

Maximum log file size in MB before rotation.
exact_match bool

If True, version must match exactly. If False, minimum version comparison (remote >= expected).
app_id str

Application ID (used for fallback if app_name sanitization results in empty string).
is_msi_installer bool

If True, only match MSI-based registry entries. If False, only match non-MSI entries. This prevents false matches when both MSI and EXE versions of software exist with the same DisplayName.
expected_architecture ArchitectureMode

Architecture filter for registry view selection. - "x86": Check only 32-bit registry view - "x64": Check only 64-bit registry view - "arm64": Check only 64-bit registry view (ARM64 uses 64-bit registry) - "any": Check both 32-bit and 64-bit views (permissive)
use_wildcard bool

If True, use PowerShell -like operator for DisplayName matching (supports * and ? wildcards). If False, use exact -eq match.
Source code in napt/detection.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
@dataclass(frozen=True)
class DetectionConfig:
    """Configuration for detection script generation.

    Attributes:
        app_name: Application name to search for in registry DisplayName.
        version: Expected version string to match.
        log_format: Log format (currently only "cmtrace" supported).
        log_level: Minimum log level (INFO, WARNING, ERROR, DEBUG).
        log_rotation_mb: Maximum log file size in MB before rotation.
        exact_match: If True, version must match exactly. If False, minimum
            version comparison (remote >= expected).
        app_id: Application ID (used for fallback if app_name sanitization
            results in empty string).
        is_msi_installer: If True, only match MSI-based registry entries.
            If False, only match non-MSI entries. This prevents false matches
            when both MSI and EXE versions of software exist with the same
            DisplayName.
        expected_architecture: Architecture filter for registry view selection.
            - "x86": Check only 32-bit registry view
            - "x64": Check only 64-bit registry view
            - "arm64": Check only 64-bit registry view (ARM64 uses 64-bit registry)
            - "any": Check both 32-bit and 64-bit views (permissive)
        use_wildcard: If True, use PowerShell -like operator for DisplayName
            matching (supports * and ? wildcards). If False, use exact -eq match.

    """

    app_name: str
    version: str
    log_format: LogFormat = "cmtrace"
    log_level: LogLevel = "INFO"
    log_rotation_mb: int = 3
    exact_match: bool = False
    app_id: str = ""
    is_msi_installer: bool = False
    expected_architecture: ArchitectureMode = "any"
    use_wildcard: bool = False

sanitize_filename 

sanitize_filename(name: str, app_id: str = '') -> str

Sanitize string for use in Windows filename.

Rules
  • Replace spaces with hyphens
  • Remove invalid Windows filename characters (< > : " | ? * \ /)
  • Normalize multiple consecutive hyphens to single hyphen
  • Remove leading/trailing hyphens and dots
  • If result is empty, fallback to app_id (or "app" if app_id is empty)

Parameters:

Name Type Description Default
name str

String to sanitize (e.g., "Google Chrome").

 required
app_id str

Fallback identifier if name becomes empty after sanitization.

 ''

Returns:

Type Description
str

Sanitized filename-safe string (e.g., "Google-Chrome").
Example

Basic sanitization: 

sanitize_filename("Google Chrome")  # Returns: "Google-Chrome"
sanitize_filename("My App v2.0")    # Returns: "My-App-v2.0"
sanitize_filename("Test<>App")      # Returns: "TestApp"

Fallback behavior: 

sanitize_filename("  ", "my-app")   # Returns: "my-app"
sanitize_filename("", "test")       # Returns: "test"

Source code in napt/detection.py 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
def sanitize_filename(name: str, app_id: str = "") -> str:
    """Sanitize string for use in Windows filename.

    Rules:
        - Replace spaces with hyphens
        - Remove invalid Windows filename characters (< > : " | ? * \\ /)
        - Normalize multiple consecutive hyphens to single hyphen
        - Remove leading/trailing hyphens and dots
        - If result is empty, fallback to app_id (or "app" if app_id is empty)

    Args:
        name: String to sanitize (e.g., "Google Chrome").
        app_id: Fallback identifier if name becomes empty after sanitization.

    Returns:
        Sanitized filename-safe string (e.g., "Google-Chrome").

    Example:
        Basic sanitization:
            ```python
            sanitize_filename("Google Chrome")  # Returns: "Google-Chrome"
            sanitize_filename("My App v2.0")    # Returns: "My-App-v2.0"
            sanitize_filename("Test<>App")      # Returns: "TestApp"
            ```

        Fallback behavior:
            ```python
            sanitize_filename("  ", "my-app")   # Returns: "my-app"
            sanitize_filename("", "test")       # Returns: "test"
            ```

    """
    # Replace spaces with hyphens
    sanitized = name.replace(" ", "-")

    # Remove invalid Windows filename characters: < > : " | ? * \ /
    invalid_chars = '<>:"|?*\\/'
    for char in invalid_chars:
        sanitized = sanitized.replace(char, "")

    # Normalize multiple consecutive hyphens to single hyphen
    sanitized = re.sub(r"-+", "-", sanitized)

    # Remove leading/trailing hyphens and dots
    sanitized = sanitized.strip(".-")

    # Fallback to app_id if empty
    if not sanitized:
        sanitized = app_id if app_id else "app"

    return sanitized

generate_detection_script 

generate_detection_script(config: DetectionConfig, output_path: Path) -> Path

Generate PowerShell detection script for Intune Win32 app.

Creates a PowerShell script that checks Windows uninstall registry keys for software installation and version. The script uses CMTrace-formatted logging with verbose output, includes log rotation logic, and performs write permission testing with automatic fallback to alternate log locations if primary locations are unavailable.

Parameters:

Name Type Description Default
config DetectionConfig

Detection configuration (app name, version, logging settings).

 required
output_path Path

Path where the detection script will be saved.

 required

Returns:

Type Description
Path

Path to the generated detection script.

Raises:

Type Description
OSError

If the script file cannot be written.
Example

Generate script with default settings: 

from pathlib import Path
from napt.detection import DetectionConfig, generate_detection_script

config = DetectionConfig(
    app_name="Google Chrome",
    version="131.0.6778.86",
)
script_path = generate_detection_script(
    config,
    Path("detection.ps1")
)

Source code in napt/detection.py 
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
def generate_detection_script(config: DetectionConfig, output_path: Path) -> Path:
    """Generate PowerShell detection script for Intune Win32 app.

    Creates a PowerShell script that checks Windows uninstall registry keys
    for software installation and version. The script uses CMTrace-formatted
    logging with verbose output, includes log rotation logic, and performs
    write permission testing with automatic fallback to alternate log locations
    if primary locations are unavailable.

    Args:
        config: Detection configuration (app name, version, logging settings).
        output_path: Path where the detection script will be saved.

    Returns:
        Path to the generated detection script.

    Raises:
        OSError: If the script file cannot be written.

    Example:
        Generate script with default settings:
            ```python
            from pathlib import Path
            from napt.detection import DetectionConfig, generate_detection_script

            config = DetectionConfig(
                app_name="Google Chrome",
                version="131.0.6778.86",
            )
            script_path = generate_detection_script(
                config,
                Path("detection.ps1")
            )
            ```

    """
    from napt.logging import get_global_logger

    logger = get_global_logger()

    logger.verbose("DETECTION", f"Generating detection script: {output_path.name}")

    # Generate script content from template
    # Use safe_substitute() so PowerShell variables ($$Variable) are preserved
    # as $Variable without raising KeyError for missing placeholders
    script_content = string.Template(_DETECTION_SCRIPT_TEMPLATE).safe_substitute(
        app_name=config.app_name,
        version=config.version,
        exact_match="$True" if config.exact_match else "$False",
        log_rotation_mb=config.log_rotation_mb,
        is_msi_installer="$True" if config.is_msi_installer else "$False",
        expected_architecture=config.expected_architecture,
        display_name_operator="-like" if config.use_wildcard else "-eq",
    )

    # Ensure output directory exists
    output_path.parent.mkdir(parents=True, exist_ok=True)

    try:
        script_bytes = script_content.encode("utf-8")
        output_path.write_bytes(script_bytes)
        logger.verbose("DETECTION", f"Detection script written to: {output_path}")
    except OSError as err:
        raise OSError(
            f"Failed to write detection script to {output_path}: {err}"
        ) from err

    return output_path