YOUR CAPSTONE PROJECT · LESSON 17

Capstone: build a fleet assessment tool

Combine OS and hardware collection, port scanning, exposure review, and a safe maintenance preview.

45 min · learn at your pace

One tool, three professional perspectives

Build a repeatable assessment for the fictional fleet. The security reviewer needs expected and unexpected listeners, the sysadmin needs capacity and a reviewed maintenance plan, and the network admin needs complete endpoint observations. Your tool must preserve collection gaps for all three.

The supplied helpers are completed versions of earlier lessons: ScanPlan.ps1, PortScanner.ps1, Exposure.ps1, and Maintenance.ps1. Dot-source them and import LabFleet.psm1. Define Invoke-FleetAssessment with ScopePath and OutputDirectory parameters; do not execute an assessment when the script loads.

Validate the requested work before writing reports

A scope file contains Computers, Ports, AllowedComputers, Expected, MaintenanceRequests, and TimeoutMs. The first five fields are arrays; TimeoutMs is an integer in 1–5000. Deduplicate computer names case-insensitively. For a non-empty fleet, apply Get-ScanPlan's complete scope and size validation. Every expected endpoint must be in that plan, and each maintenance request must name a scoped computer, positive PID, and non-empty ExpectedStartTime.

An empty fleet with empty expectations and maintenance requests produces empty reports. Missing, malformed, or out-of-scope configuration must throw before writing output. Collection failures on valid requested computers instead become inventory rows with null measurements and their lab error code.

Produce five useful files

Write inventory.csv with ComputerName, Status, Build, InstalledGiB, FreeGiB, Cores, LogicalProcessors, and Detail. Ready hosts contain typed measurements; failures preserve Offline, AccessDenied, or UnknownComputer and a diagnostic. Probe the requested endpoints using Test-LabTcpPort and write ports.csv with all five probe fields. Compare expectations into exposure.csv, then invoke maintenance with WhatIf and write maintenance.csv. Never stop a process in this capstone.

Write summary.json and return the same summary: Simulation=true, Requested, Ready, Failed, Ports, Open, Unknown, MaintenancePlanned, and MaintenanceFailed. Unknown counts TimedOut plus Error. Always overwrite reports; empty CSVs retain their headers. Keep inputs and simulated process state unchanged.

Explore before you check

Try scope-a.json for duplicate inputs, offline and denied computers, uncertain probes, and a mixed maintenance preview. scope-b.json changes the hosts and listener policy. scope-empty.json tests a clean empty run. The checks also repeat a run and exercise invalid scope. Your saved files are virtual lab artifacts, not evidence collected from a real fleet.

Try an example.ps1
Import-Module '/home/user/LabFleet.psm1' -Force
Get-Content '/home/user/scope-a.json' -Raw
Get-LabComputer
YOUR TURN

Put it into practice.

Define Invoke-FleetAssessment(ScopePath, OutputDirectory) using the supplied helpers. Validate the scope, collect per-host OS/hardware outcomes, scan distinct endpoints with the configured timeout, compare expected listeners, and preview maintenance with WhatIf. Overwrite inventory.csv, ports.csv, exposure.csv, maintenance.csv, and summary.json using the schemas above; return the summary. Handle both supplied fleets, empty input, repeat runs, and invalid scope without changing inputs or process state.

See an explained solution
One way to solve it.ps1
Import-Module '/home/user/LabFleet.psm1' -Force
. '/home/user/ScanPlan.ps1'
. '/home/user/PortScanner.ps1'
. '/home/user/Exposure.ps1'
. '/home/user/Maintenance.ps1'
function Write-AssessmentCsv {
    param([object[]]$Rows,[string[]]$Columns,[string]$Path)
    if($Rows.Count -gt 0) { $Rows | Select-Object $Columns | Export-Csv $Path -NoTypeInformation }
    else { Set-Content $Path (($Columns | ForEach-Object { '"'+$_+'"' }) -join ',') }
}
function Invoke-FleetAssessment {
    param([string]$ScopePath,[string]$OutputDirectory)
    $scope=Get-Content -LiteralPath $ScopePath -Raw -ErrorAction Stop | ConvertFrom-Json -DateKind String -ErrorAction Stop
    foreach($field in 'Computers','Ports','AllowedComputers','Expected','MaintenanceRequests','TimeoutMs') {
        if($field -notin $scope.PSObject.Properties.Name) { throw "Missing scope field: $field" }
    }
    foreach($field in 'Computers','Ports','AllowedComputers','Expected','MaintenanceRequests') {
        if($scope.$field -isnot [array]) { throw "Expected an array: $field" }
    }
    if($scope.TimeoutMs -isnot [long] -and $scope.TimeoutMs -isnot [int]) { throw 'Timeout must be an integer' }
    if($scope.TimeoutMs -lt 1 -or $scope.TimeoutMs -gt 5000) { throw 'Invalid timeout' }
    $names=@($scope.Computers | ForEach-Object { $_.ToLowerInvariant() } | Sort-Object -Unique)
    $plan=if($names.Count) { @(Get-ScanPlan $names $scope.Ports $scope.AllowedComputers) } else { @() }
    foreach($e in $scope.Expected) {
        if(-not @($plan | Where-Object { $_.ComputerName -eq $e.ComputerName -and $_.Port -eq $e.Port }).Count) { throw 'Expected endpoint outside plan' }
    }
    foreach($q in $scope.MaintenanceRequests) {
        if($q.ComputerName -notin $names -or ($q.Id -isnot [int] -and $q.Id -isnot [long]) -or $q.Id -lt 1 -or $q.Id -gt [int]::MaxValue -or -not $q.ExpectedStartTime) { throw 'Invalid maintenance scope' }
    }
    $inventory=@(foreach($name in $names) {
        try {
            Invoke-LabCommand $name -ScriptBlock {
                param($Computer)
                [pscustomobject]@{ComputerName=$Computer.ComputerName;Status='Ready';Build=[int]$Computer.OS.BuildNumber;InstalledGiB=$Computer.Hardware.TotalPhysicalMemory/1GB;FreeGiB=$Computer.OS.FreePhysicalMemory/1MB;Cores=$Computer.Hardware.NumberOfCores;LogicalProcessors=$Computer.Hardware.NumberOfLogicalProcessors;Detail='Collected'}
            }
        } catch {
            [pscustomobject]@{ComputerName=$name;Status=($_.Exception.Message -split ':',2)[0];Build=$null;InstalledGiB=$null;FreeGiB=$null;Cores=$null;LogicalProcessors=$null;Detail=$_.Exception.Message}
        }
    })
    $ports=@(if($names.Count) {
        Invoke-PortScan $names $scope.Ports $scope.AllowedComputers -TimeoutMs $scope.TimeoutMs -Probe {
            param($name,$portNumber,$limit)
            Test-LabTcpPort $name -Port $portNumber -TimeoutMs $limit
        }
    })
    $exposure=@(Compare-ServiceExposure $ports $scope.Expected)
    $maintenance=@(Invoke-FleetMaintenance $scope.MaintenanceRequests -WhatIf)
    $summary=[pscustomobject]@{
        Simulation=$true;Requested=$names.Count;Ready=@($inventory | Where-Object Status -EQ Ready).Count
        Failed=@($inventory | Where-Object Status -NE Ready).Count;Ports=$ports.Count
        Open=@($ports | Where-Object Status -EQ Open).Count
        Unknown=@($ports | Where-Object { $_.Status -in @('TimedOut','Error') }).Count
        MaintenancePlanned=@($maintenance | Where-Object Status -EQ Planned).Count
        MaintenanceFailed=@($maintenance | Where-Object Status -EQ Failed).Count
    }
    New-Item -ItemType Directory -Path $OutputDirectory -Force | Out-Null
    Write-AssessmentCsv $inventory @('ComputerName','Status','Build','InstalledGiB','FreeGiB','Cores','LogicalProcessors','Detail') (Join-Path $OutputDirectory 'inventory.csv')
    Write-AssessmentCsv $ports @('ComputerName','Port','Status','ElapsedMs','Detail') (Join-Path $OutputDirectory 'ports.csv')
    Write-AssessmentCsv $exposure @('ComputerName','Port','Finding') (Join-Path $OutputDirectory 'exposure.csv')
    Write-AssessmentCsv $maintenance @('ComputerName','Id','Status','Detail') (Join-Path $OutputDirectory 'maintenance.csv')
    $summary | ConvertTo-Json | Set-Content (Join-Path $OutputDirectory 'summary.json')
    $summary
}

The assessment composes the earlier contracts into a read-only workflow. Validation happens before publication, collection errors stay visible, and maintenance remains a preview. Five repeatable files serve the three roles without claiming any real network or OS access.