Capstone: assess fleet readiness and exposure
Combine a scoped scanner, simulated fleet collection and maintenance previews into an honest assessment.
Bring the shared tools together
Cyber security, systems administration and network operations all need to distinguish observed facts from missing evidence. This capstone combines an explicit scan plan with fictional fleet collection, expected service policy and reviewed process identities. The output is an assessment, not an automated decision to change systems.
Use the supplied helper modules to compose the behaviors from earlier lessons. The scanner receives RecordedProbe; OS and process operations use LabFleet. Their names and the summary's simulation flag make the browser boundary explicit. A collection failure does not remove a host or its TCP endpoints from the assessment.
Validate before writing reports
Read the full brief below or open brief.txt in the supplied-files section beneath the lab. It defines input normalization, duplicate handling, count meanings and output ordering. Validate the requested scope, expectations and maintenance identities before assessment. Keep malformed inventory rows as rejection records, while malformed policy or missing required files fail clearly.
Maintenance always uses preview mode. Preserve every input byte, including an optional existing fleet-state.json. Expected services outside the chosen scan ports remain visible as not_scanned rather than disappearing. Unknown evidence should stay unknown even when a simpler report would look more reassuring.
Make the result repeatable
Produce hosts.csv, ports.csv, maintenance.csv, errors.csv and summary.json. Empty successful runs still replace stale reports with headers and zeros. Repeating the same case at the same assessment time should produce the same bytes. The state counts must reconcile with actual scanned endpoints, while unknown exposure also includes expected endpoints that were never scanned.
The optional local TCP download is useful for a learner's own environment, but it is not required for this project or course completion. Every required check runs here with supplied files.
Complete project contract
Build assess_fleet(root="case", output="output", now="2026-11-17T12:00:00Z") returning the summary. Use the supplied scan_rules, advanced_core, lab_probe and lab_fleet helpers, or equivalent behavior. All probes and systems are simulated. Maintenance is always preview-only.
Required input and validation
- Required files: policy.json, inventory.csv, fleet.json, tcp.json. Optional fleet-state.json contains already-saved simulation state. now is offset-aware ISO time; output must be outside root. Preserve every input byte and never create/change fleet-state.json. Missing required inputs raise FileNotFoundError. Malformed JSON, invalid policy, missing inventory headers and invalid adapter fixture structure fail before report writing. Unexpected I/O errors propagate. No multi-file transaction is required.
- Normalize hosts with strip().casefold(); require [a-z0-9][a-z0-9-]*. policy hosts is a list, normalized/deduplicated/sorted; it may be empty. ports, allowed and max_endpoints follow scan_plan. timeout_ms is integer 1..5000 excluding bool. min_free_percent is finite numeric 0..100 excluding bool. expected and maintenance are lists with at most 256 rows each. Extra fields are ignored.
- inventory.csv requires host,address,enabled. Addresses follow scan_plan's numeric unscoped target rules, independent of policy allowlist until selection. enabled is case-insensitive true/false. Logical CSV rows start at 2. Invalid records produce source inventory.csv and reason "invalid record". First valid normalized host AND canonical address wins globally (including disabled hosts); any later duplicate host or address produces "duplicate identity". Every requested host must exist and be enabled, otherwise ValueError.
- Build the complete selected scan plan with the policy allowlist and endpoint ceiling before probing. A host is not omitted merely because its fictional OS collection is unavailable.
- Expected services have canonicalizable address, valid integer port and nonempty service string (strip outer whitespace, preserve case/Unicode). Address must belong to a selected host; keys are unique. An expected port absent from the scan plan stays visible as not_scanned/unknown. Reject invalid or duplicate expectations before assessment.
- Maintenance requests contain selected host, positive integer non-bool pid and aware started_at normalized to UTC ending Z. Reject duplicate host/PID pairs and all invalid requests before assessment. Always call reviewed_stops with execute=False.
- fleet.json follows LabFleet's supplied structure. tcp.json is a list of unique canonical address/port keys with nonempty observations lists; each observation is a dictionary. Malformed returned observation fields become per-probe errors through scan. There is no retry in this capstone: use the first recorded observation once per planned endpoint. Recorded delay >= timeout yields timed_out at the requested timeout; absent observations yield error with detail "missing observation".
Outputs: replace on every successful run, UTF-8 and stable order
- hosts.csv columns host,address,status,os,logical_cpus,total_gib,free_percent,finding,error. One row per selected host, sorted by host. Use fleet_inventory values. finding is unavailable for unavailable collection, otherwise memory_pressure when free_percent < min_free_percent, otherwise healthy. Equality is healthy. Unavailable numeric values serialize as blank. Each unavailable host also adds errors.csv source fleet.json, record 0, reason "<host>: <exception class>".
- ports.csv columns host,address,port,service,state,finding,elapsed_ms,detail. Use exposure_report's union/order/classification, joined to the selected host. Add scanned elapsed/detail; absent observations have blank elapsed/detail. Open TCP never claims application health. Include not_scanned expectations.
- maintenance.csv columns host,pid,started_at,status. Use reviewed_stops preview results sorted by host/PID. Protected, denied, missing, identity_changed, already_stopped and would_stop stay distinct. An error:<class> also adds errors.csv source maintenance, record 0, reason "<host>: error:<class>". Never apply a stop.
- errors.csv columns source,record,reason. Include inventory rejections, unavailable host collection and maintenance errors as above, sorted by source, numeric record, reason. Probe errors/timeouts are preserved in ports.csv instead of duplicated here.
- summary.json keys simulation:true, assessed_at (now normalized to UTC ending Z), hosts,unavailable_hosts,memory_pressure,scanned,open,refused,timed_out,probe_errors,unexpected_open,unknown,maintenance,errors. All counts are integers including zero. open/refused/timed_out/probe_errors count actual scan results and sum to scanned; unknown includes missing expected ports. maintenance counts preview rows, not applied changes.
- Empty successful scope still writes all CSV headers and zero counts. Identical input and now produce identical output bytes. Successful reruns replace stale rows. No network traffic, host OS changes or remote commands occur.
import json
from pathlib import Path
policy=json.loads(Path("case/policy.json").read_text())
print("Requested hosts:", policy["hosts"])
print("Recorded TCP endpoints:", len(json.loads(Path("case/tcp.json").read_text())))
Put it into practice.
Build assess_fleet(root, output, now), defaulting to case, output and 2026-11-17T12:00:00Z. Combine the supplied policy, inventory, recorded TCP observations and simulated fleet into hosts.csv, ports.csv, maintenance.csv, errors.csv and summary.json. Return the summary. Follow the complete brief.txt contract in the supplied files below the lab. Preserve unknown evidence, validate scope before probing, preview every maintenance action and preserve all input files. Repeated successful runs replace reports, including an empty scope. Use the supplied helpers or equivalent behavior. All systems and TCP observations are simulated.
See an explained solution
import csv,json,math,re
from pathlib import Path
from datetime import datetime,timezone
from ipaddress import ip_address
from scan_rules import scan_plan,ProbeResult
from advanced_core import scan,exposure_report,fleet_inventory,reviewed_stops
from lab_probe import RecordedProbe
from lab_fleet import LabFleet
def assess_fleet(root="case",output="output",now="2026-11-17T12:00:00Z"):
source,destination=Path(root),Path(output)
if destination.resolve().is_relative_to(source.resolve()):raise ValueError("Output must be outside input")
current=datetime.fromisoformat(now)
if current.tzinfo is None:raise ValueError("Assessment time needs an offset")
def host_name(value):
if not isinstance(value,str):raise ValueError("Invalid host")
value=value.strip().casefold()
if not re.fullmatch(r"[a-z0-9][a-z0-9-]*",value):raise ValueError("Invalid host")
return value
policy=json.loads((source/"policy.json").read_text(encoding="utf-8"))
try:
if not isinstance(policy,dict) or not isinstance(policy["hosts"],list) or not isinstance(policy["expected"],list) or not isinstance(policy["maintenance"],list):raise ValueError("Invalid policy collections")
hosts=sorted({host_name(value) for value in policy["hosts"]})
timeout=policy["timeout_ms"];threshold=policy["min_free_percent"];maximum=policy["max_endpoints"]
if type(timeout) is not int or not 1<=timeout<=5000 or type(threshold) not in (int,float) or not math.isfinite(threshold) or not 0<=threshold<=100:raise ValueError("Invalid policy limits")
scan_plan([],policy["ports"],policy["allowed"],maximum)
if len(policy["expected"])>256 or len(policy["maintenance"])>256:raise ValueError("Policy row limit exceeded")
except (KeyError,TypeError,AttributeError,ValueError) as error:raise ValueError("Invalid assessment policy") from error
inventory={};addresses=set();errors=[]
with (source/"inventory.csv").open(encoding="utf-8",newline="") as handle:
reader=csv.DictReader(handle)
if not {"host","address","enabled"}.issubset(reader.fieldnames or []):raise ValueError("Inventory header is incomplete")
for number,row in enumerate(reader,2):
try:
host=host_name(row["host"])
address=scan_plan([row["address"]],[1],["0.0.0.0/0","::/0"])[0]["address"]
enabled=row["enabled"].strip().casefold()
if enabled not in ("true","false"):raise ValueError("Invalid enabled flag")
except (TypeError,ValueError,AttributeError):
errors.append({"source":"inventory.csv","record":number,"reason":"invalid record"});continue
if host in inventory or address in addresses:
errors.append({"source":"inventory.csv","record":number,"reason":"duplicate identity"});continue
inventory[host]={"address":address,"enabled":enabled=="true"};addresses.add(address)
if any(host not in inventory or not inventory[host]["enabled"] for host in hosts):raise ValueError("Requested host is missing or disabled")
by_address={inventory[host]["address"]:host for host in hosts}
plan=scan_plan(list(by_address),policy["ports"],policy["allowed"],maximum)
expected=[];expected_keys=set();maintenance=[];process_keys=set()
try:
for row in policy["expected"]:
endpoint=ProbeResult(row["address"],row["port"],"open",0)
service=row["service"]
if endpoint.address not in by_address or not isinstance(service,str) or not service.strip() or (endpoint.address,endpoint.port) in expected_keys:raise ValueError("Invalid service expectation")
expected_keys.add((endpoint.address,endpoint.port));expected.append({"address":endpoint.address,"port":endpoint.port,"service":service.strip()})
for row in policy["maintenance"]:
host=host_name(row["host"]);pid=row["pid"];stamp=datetime.fromisoformat(row["started_at"])
if host not in hosts or type(pid) is not int or pid<=0 or stamp.tzinfo is None or (host,pid) in process_keys:raise ValueError("Invalid maintenance identity")
process_keys.add((host,pid));maintenance.append({"host":host,"pid":pid,"started_at":stamp.astimezone(timezone.utc).isoformat().replace("+00:00","Z")})
except (KeyError,TypeError,AttributeError,ValueError) as error:raise ValueError("Invalid expected service or maintenance policy") from error
fleet=LabFleet(source/"fleet.json",source/"fleet-state.json")
probe=RecordedProbe(source/"tcp.json")
host_rows=[]
for row in fleet_inventory(fleet,hosts):
finding="unavailable" if row["status"]=="unavailable" else "memory_pressure" if row["free_percent"]<threshold else "healthy"
host_rows.append(dict(row,address=inventory[row["host"]]["address"],finding=finding))
if row["status"]=="unavailable":errors.append({"source":"fleet.json","record":0,"reason":row["host"]+": "+row["error"]})
scanned=scan(list(by_address),policy["ports"],policy["allowed"],probe,timeout,maximum)
observed={(row["address"],row["port"]):row for row in scanned}
port_rows=[]
for row in exposure_report(scanned,expected):
result=observed.get((row["address"],row["port"]))
port_rows.append(dict(row,host=by_address[row["address"]],elapsed_ms=result["elapsed_ms"] if result else None,detail=result["detail"] if result else ""))
maintenance_rows=reviewed_stops(fleet,maintenance,execute=False)
for row in maintenance_rows:
if row["status"].startswith("error:"):errors.append({"source":"maintenance","record":0,"reason":row["host"]+": "+row["status"]})
errors.sort(key=lambda row:(row["source"],row["record"],row["reason"]))
summary={"simulation":True,"assessed_at":current.astimezone(timezone.utc).isoformat().replace("+00:00","Z"),"hosts":len(host_rows),"unavailable_hosts":sum(row["status"]=="unavailable" for row in host_rows),"memory_pressure":sum(row["finding"]=="memory_pressure" for row in host_rows),"scanned":len(scanned),**{key:sum(row["state"]==state for row in scanned) for key,state in [("open","open"),("refused","refused"),("timed_out","timed_out"),("probe_errors","error")]},"unexpected_open":sum(row["finding"]=="unexpected_open" for row in port_rows),"unknown":sum(row["finding"]=="unknown" for row in port_rows),"maintenance":len(maintenance_rows),"errors":len(errors)}
destination.mkdir(parents=True,exist_ok=True)
for name,rows,columns in [
("hosts.csv",host_rows,["host","address","status","os","logical_cpus","total_gib","free_percent","finding","error"]),
("ports.csv",port_rows,["host","address","port","service","state","finding","elapsed_ms","detail"]),
("maintenance.csv",maintenance_rows,["host","pid","started_at","status"]),
("errors.csv",errors,["source","record","reason"])]:
with (destination/name).open("w",encoding="utf-8",newline="") as handle:
writer=csv.DictWriter(handle,fieldnames=columns);writer.writeheader();writer.writerows(rows)
(destination/"summary.json").write_text(json.dumps(summary,sort_keys=True,ensure_ascii=False)+"\n",encoding="utf-8")
return summary
if __name__ == "__main__":
print(assess_fleet())
The assessment composes tested boundaries while retaining missing evidence and review-only maintenance. Stable outputs and explicit simulation labels make the result useful without overstating what was observed or changed.