Run and resume a Zero Trust Assessment

Run all Zero Trust Assessment pillars or select a pillar and specific test IDs. You can also reuse an existing export to rerun assessment and report processing without collecting a fresh tenant snapshot. Before starting, connect to the services and choose a protected output directory.

The options and defaults in the following section describe the development source. Check your installed version's help when using a published package.

Prerequisites

  • Completion of Connect to assessment services, with the service connections available in the same PowerShell session.
  • A protected output directory with sufficient disk space.
  • Azure read access and subscription tags for Infrastructure scope, if applicable.

Run a fresh assessment

Invoke-ZtAssessment uses the connected tenant; it doesn't take a tenant parameter. Choose the output path and scope before running the command.

Warning

A non-resume run against a nonempty output directory prompts to delete its contents. In a detected continuous integration (CI) environment, the current implementation cleans the directory automatically. Don't point -Path at a directory containing unrelated files.

  1. Choose a new output directory. The default is .\ZeroTrustReport, relative to your current directory.

  2. Run one of these alternatives:

    • To assess all seven current pillars, use:

      Invoke-ZtAssessment
      
    • To assess only Devices and use a custom path, use:

      Invoke-ZtAssessment -Path C:\MyAssessment01 -Pillar Devices
      
  3. Follow the progress dashboard and review diagnostic files when you need to distinguish active work from a failure.

Runtime varies with tenant size, service response times, throttling, and selected tests. -NoBrowser disables both the progress dashboard server and automatic opening of the final report.

All includes Identity, Devices, Network, Data, Infrastructure, security operations (SecOps), and AI. The -Preview switch isn't required for these pillars. It enables preview-only features when present and is separate from installing a prerelease package.

Reuse an existing export

Use -Resume only when you intend to reuse the existing tenant snapshot and database, not collect current tenant data.

  1. Preserve the existing output directory, exports, and database.

  2. Use the original pillar, or an individual pillar if the original export used All. A single-pillar export can't be resumed as All or as a different pillar.

  3. Keep the necessary service connections available and rerun against the original path:

    Invoke-ZtAssessment -Path C:\MyAssessment01 -Pillar Devices -Resume
    

Resume skips export and database rebuild, but reruns assessment and report processing. It isn't a fresh collection or a guarantee of fully offline execution.

Infrastructure scope

Infrastructure findings use Microsoft Defender for Cloud recommendations. Prepare the intended subscriptions before assessing this pillar.

  1. Arrange Reader access, or equivalent read permissions, on each intended subscription/resource scope.
  2. Tag the intended accessible Azure subscriptions with ZeroTrustAssessment:Infrastructure.
  3. Run the Infrastructure pillar or All, then review any skipped checks.

Only accessible subscriptions with the required tag are included. No matching tagged subscriptions produces a skip, not a passed assessment.

Invoke-ZtAssessment parameters

Use this table to select run options. Explicit command-line values override supported configuration-file settings. Not every parameter is a configuration-file setting.

Parameter Behavior
-Path <string> Output folder; defaults to .\ZeroTrustReport relative to the current directory.
-Pillar <string> All by default, or Identity, Devices, Network, Data, Infrastructure, SecOps, or AI.
-Preview Enable preview-only features when present. Not needed for the seven current pillars.
-Resume Reuse exports and database at -Path; use the original pillar or a subset of an All export.
-Tests <id[,id...]> Exact test IDs, without wildcards. Otherwise, run the selected pillar's tests.
-Days <1-30> Sign-in log lookback; defaults to 30 days.
-MaximumSignInLogQueryTime <minutes> Sign-in collection time budget; defaults to 60. 0 removes the time limit, but the export size limit still applies.
-NoBrowser Don't start the progress dashboard server or open the final report.
-ShowLog Show a high-level console log summary.
-ExportLog Create a PSFramework support package under <Path>\log near the end of the run. Per-run diagnostic files don't require this switch.
-ConfigurationFile <path> JSON configuration for supported settings. Explicit command-line values take precedence.
-DisableTelemetry Disable the assessment telemetry event. See data handling and telemetry.
-Timeout <timespan> Overall wait for tests; defaults to 24 hours. Accepts values such as 12h or 3d.
-TestTimeout <minutes/timespan> Per-test timeout; defaults to 60 minutes. 0 disables it. The default measures idle time since activity, not total elapsed time. Interruption of external and remoting operations is best effort.
-ExportThrottleLimit <n>, -TestThrottleLimit <n> Parallel export collectors and tests, respectively; default to 5 each.

For the complete interface, use Get-Help Invoke-ZtAssessment -Full and review the command source. For configuration persistence and large-tenant settings, see Configure and tune assessments.

Next step