Capstone: build a fleet assessment tool
Combine OS and hardware collection, port scanning, exposure review, and a safe maintenance preview.
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.
Import-Module '/home/user/LabFleet.psm1' -Force
Get-Content '/home/user/scope-a.json' -Raw
Get-LabComputer
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
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.