03 / BUILD A TCP PORT SCANNER · LESSON 09

Define an explicit scan scope

Validate and deduplicate a bounded host-and-port plan before any connection attempt.

16 min · learn at your pace

Start with the scope, not the socket

A scanner combines a list of targets with a list of ports. The product of those lists determines the number of attempts. Build and validate the entire plan before invoking a probe, so a late invalid item cannot leave a partially executed scan.

This course accepts explicit simple hostnames or IPv4-style names and an explicit allowlist. It does not expand subnets, discover targets, or scan arbitrary address ranges. The allowlist is an application policy, not proof of ownership or an authentication mechanism. Use a local adapter only with systems you are authorised to test.

Normalise once

Treat computer names case-insensitively and emit lowercase names. Remove duplicate computers and duplicate ports. Ports are integers from 1 through 65535. Reject empty scope, empty port lists, names outside the allowlist, and names containing URL syntax or whitespace.

Cap the deduplicated plan at 16 computers, 32 ports, and 256 pairs. Validate all three limits. A 16-by-32 request passes the first two but exceeds the total-attempt budget. This sequential course design favours understandable limits over high-throughput discovery.

Keep planning pure

Get-ScanPlan returns objects with ComputerName and Port and performs no probes. The next lessons supply a transport adapter. That separation lets Pester verify scope and cardinality without opening sockets or relying on a live service. Equivalent ordering is fine; the report's identity is the host/port pair.

Try an example.ps1
$names='app01','db01'; $ports=443,5985
foreach($name in $names) { foreach($portNumber in $ports) { [pscustomobject]@{ComputerName=$name;Port=$portNumber} } }
YOUR TURN

Put it into practice.

Define Get-ScanPlan(ComputerName string[], Port int[], AllowedComputer string[]). Reject empty inputs, names outside the allowlist or the simple-name pattern shown in the solution hints, and ports outside 1–65535. Emit distinct lowercase computer/port pairs. Reject more than 16 unique computers, 32 unique ports, or 256 pairs before emitting any rows.

See an explained solution
One way to solve it.ps1
function Get-ScanPlan {
    param([string[]]$ComputerName,[int[]]$Port,[string[]]$AllowedComputer)
    if(-not $ComputerName -or -not $Port -or -not $AllowedComputer) { throw 'Explicit scope is required' }
    foreach($name in $ComputerName) {
        if($name -notmatch '^[a-zA-Z0-9][a-zA-Z0-9.-]{0,252}$' -or $name -notin $AllowedComputer) { throw "Outside scope: $name" }
    }
    foreach($number in $Port) { if($number -lt 1 -or $number -gt 65535) { throw 'Invalid port' } }
    $names=@($ComputerName | ForEach-Object { $_.ToLowerInvariant() } | Sort-Object -Unique)
    $ports=@($Port | Sort-Object -Unique)
    if($names.Count -gt 16 -or $ports.Count -gt 32 -or $names.Count*$ports.Count -gt 256) { throw 'Scan plan is too large' }
    foreach($name in $names) { foreach($number in $ports) { [pscustomobject]@{ComputerName=$name;Port=$number} } }
}

Pure planning catches invalid scope before any effect. Deduplication and three independent limits give the scanner a predictable maximum number of attempts.