YOUR CAPSTONE PROJECT · LESSON 17

Capstone: build a network audit

Combine device scope, port policy, routes, DNS and telemetry into a reproducible assessment with explicit coverage limits.

60 min · learn at your pace

Your brief: a network change review

The network team has saved device inventory, interface snapshots, route records and DNS exports. Build one main.py script that turns them into a consistent review. The supplied policy defines which sites, ports and targets matter, plus an age limit and a utilization threshold.

Use the rules developed throughout the course. Validate addresses and identities before joining records; keep devices and VRFs separate; compare VLAN and DNS sets; preserve equal-cost route choices; calculate rates from continuous counters. Missing or stale interface exports must remain unavailable, not silently count as healthy.

Keep the evidence and the claim aligned

The output describes the supplied exports. It does not contact devices, query DNS or send probes. A routed target means the route export contains a matching entry under the declared policy. It does not establish live reachability.

The script writes interfaces.csv, routes.csv, dns_changes.csv, errors.csv and summary.json. Each output has a fixed schema and order. Collect rows and validation errors before writing so fatal policy errors do not replace a previous report. Successful reruns replace obsolete rows, including empty results.

The complete contract is below and in the supplied brief.txt. It specifies which errors stop the whole assessment, which become row-level errors, and how boundaries and duplicates behave. From the mobile lab, print that file to read the contract without leaving the practice tab. The bundled net_rules.py provides earlier functions so you can concentrate on composing the audit rather than rewriting every parser.

Complete task contract

Build audit_network(root="network",output="output",now="2026-11-17T12:00:00Z"), returning the summary object. The supplied net_rules.py contains the earlier route, DNS, rate, export and VLAN helpers. Equivalent implementations are accepted. No live networking is needed.

Validation and scope
- now must be timezone-aware. Output must be outside root (not root or a descendant). Preserve inputs. Finish input validation and assessment before writing any report. Missing required files raise FileNotFoundError; malformed JSON/root shapes, invalid policy or missing CSV headers raise ValueError. Unexpected I/O failures propagate. A multi-file transactional commit is not required.
- Normalize labels with strip().casefold(). Device names and target IDs must match [a-z0-9][a-z0-9-]*. Interface names must match [a-z0-9][a-z0-9/.-]*. Site and VRF labels are nonempty strings, including Unicode. State values are exact up/down.
- policy.json requires sites: nonempty list of nonempty strings; max_age_minutes: positive integer excluding bool; utilization_warn_percent: finite int/float 0..100 excluding bool; ports,targets,dns: lists (may be empty).
- Each policy port has device,interface,admin,vlans,speed_bps. Normalize identifiers; require unique device/interface pairs. VLAN lists contain integers 1..4094 excluding bool; deduplicate/sort them. speed_bps must be positive finite numeric, excluding bool. Each target has globally unique id,device,vrf,address; address is an unscoped IP string normalized with ipaddress. Policy DNS follows dns_record/compare_dns. Extra fields are ignored.
- devices.csv requires device,site,active. Active is case-insensitive true/false. Logical records start at 2. Invalid rows produce reason "invalid record". First valid normalized device wins, including inactive/out-of-site rows; later duplicates produce "duplicate device". Select only active devices in policy sites.
- routes.json is a required list. Each row includes device plus the select_routes fields id,vrf,prefix,metric,next_hop,interface. Validate all records; malformed rows become "invalid record" errors. First valid normalized (device,route ID) wins; later duplicates produce "duplicate route". Route IDs, VRFs and interfaces follow the helper's nonempty-string contract. Route queries run per selected target's device and VRF; longest prefix then lowest metric, preserving all equal-cost IDs.
- dns.json is a required list. Validate each record with dns_record; bad records become "invalid record" errors. Identical valid duplicates merge. DNS comparison is global, even when no device is selected. DNS/route exports are assessed as supplied; this task makes no live reachability or collection-freshness claim for those two files.
- Collect exports/<device>.json for every selected device using collect_device_exports. Missing/invalid/stale status produces one file error at record 0 with reason "missing export", "invalid export" or "stale export". A valid export at the exact maximum age is fresh; future/naive timestamps are invalid.
- For each fresh export, validate every interface row: normalized interface, admin up/down and valid VLAN list. Other fields (oper, previous/current samples) may be absent. Invalid rows become "invalid interface"; later valid duplicate names become "duplicate interface". Record positions start at 1. First valid wins. A desired port absent from a fresh export adds a record-0 error "missing interface: <name>".

Outputs: UTF-8, stable order, overwrite on every successful run
- interfaces.csv columns device,interface,site,evidence,status,issues,desired_vlans,rx_bps,tx_bps,utilization_percent. Include only desired ports whose device is selected, sorted by device/interface. evidence is fresh/missing/invalid/stale or missing-interface. Nonfresh/missing-interface rows have status unavailable, no issues and blank measurements. desired_vlans is sorted integers joined with |.
- For an observed port, differing admin adds admin_drift; differing VLAN set adds vlan_drift. Only when desired and observed admin are both up, classify oper: down adds link_down; absent/unrecognized adds link_unknown; up adds neither. In that same case use interface_rate on previous/current and policy speed: unknown adds rate_unknown; valid utilization >= warning threshold adds high_utilization (compare before rounding). In all other admin cases measurements stay blank. status is attention if any issue, otherwise disabled for desired down, otherwise healthy. Join unique issue codes alphabetically with semicolons.
- routes.csv columns id,device,vrf,address,status,route_ids. Include selected-device targets sorted by normalized target ID. status routed/unrouted describes matching exported routes only. Join all selected normalized route IDs with | in sorted ID order.
- dns_changes.csv columns change,name,type,value. change is missing or unexpected; order by change,name,type,value. Normalize/deduplicate as compare_dns specifies.
- errors.csv columns source,record,reason. Source is devices.csv, routes.json, dns.json or exports/<device>.json. Use logical CSV or one-based list positions as described; whole-export/missing-interface errors use 0. Sort source, numeric record, reason.
- summary.json keys assessed_at (now in UTC ISO ending Z), devices,ports,healthy,attention,disabled,unavailable,unrouted,dns_changes,errors. Counts are integers including zeros; the four status counts describe ports and sum to ports. devices counts selected inventory, including devices with no desired ports.
- Empty successful runs still write all CSV headers and zero relevant counts. Successful reruns replace old rows. Identical input and now produce identical output. This is a report and change review, never a device-configuration or reachability tool.
Try an example.py
import json
from pathlib import Path
print(json.loads(Path("network/policy.json").read_text(encoding="utf-8"))["sites"])
print(Path("brief.txt").read_text(encoding="utf-8"))
YOUR TURN

Put it into practice.

Build audit_network(root, output, now), using network and output as the default folders and 2026-11-17T12:00:00Z as the default assessment time. Return the summary object. Combine supplied devices, policy, interface exports, routes and DNS into interfaces.csv, routes.csv, dns_changes.csv, errors.csv and summary.json. Follow the exact schemas, error reasons and boundaries in brief.txt, available under the supplied files below the lab. Preserve inputs, expose unavailable observations, retain equal-cost routes and overwrite reports on successful reruns. Use the supplied net_rules.py helpers if useful. Send no network traffic or configuration commands.

See an explained solution
One way to solve it.py
import csv,json,re,math
from pathlib import Path
from ipaddress import ip_address
from net_rules import select_routes,dns_record,compare_dns,interface_rate,collect_device_exports,parse_utc,vlan_drift

def audit_network(root="network",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=parse_utc(now)
    def label(value):
        if not isinstance(value,str) or not value.strip():
            raise ValueError("Invalid label")
        return value.strip().casefold()
    def device(value):
        value=label(value)
        if not re.fullmatch(r"[a-z0-9][a-z0-9-]*",value):
            raise ValueError("Invalid device or ID")
        return value
    def port(value):
        value=label(value)
        if not re.fullmatch(r"[a-z0-9][a-z0-9/.-]*",value):
            raise ValueError("Invalid interface")
        return value
    policy=json.loads((source/"policy.json").read_text(encoding="utf-8"))
    try:
        if not isinstance(policy,dict) or not isinstance(policy["sites"],list) or not policy["sites"]:
            raise ValueError("Policy needs sites")
        sites={label(value) for value in policy["sites"]}
        age,threshold=policy["max_age_minutes"],policy["utilization_warn_percent"]
        if type(age) is not int or age<=0 or type(threshold) not in (int,float) or not math.isfinite(threshold) or not 0<=threshold<=100:
            raise ValueError("Invalid age or threshold")
        if any(not isinstance(policy[key],list) for key in ("ports","targets","dns")):
            raise ValueError("Policy collections must be lists")
        ports,targets,seen_ports,seen_targets=[],[],set(),set()
        for row in policy["ports"]:
            host,name=device(row["device"]),port(row["interface"])
            if (host,name) in seen_ports or row["admin"] not in ("up","down"):
                raise ValueError("Invalid port policy")
            vlan_drift([dict(row,device=host,interface=name)],[])
            interface_rate(None,None,row["speed_bps"])
            seen_ports.add((host,name));ports.append(dict(row,device=host,interface=name,vlans=sorted(set(row["vlans"]))))
        for row in policy["targets"]:
            identifier=device(row["id"]);host=device(row["device"]);vrf=label(row["vrf"])
            if identifier in seen_targets or not isinstance(row["address"],str) or "%" in row["address"]:
                raise ValueError("Invalid target")
            address=str(ip_address(row["address"].strip()))
            seen_targets.add(identifier);targets.append({"id":identifier,"device":host,"vrf":vrf,"address":address})
        expected_dns=[dns_record(row) for row in policy["dns"]]
    except (KeyError,TypeError,AttributeError,ValueError) as error:
        raise ValueError("Invalid network policy") from error
    raw_routes=json.loads((source/"routes.json").read_text(encoding="utf-8"))
    raw_dns=json.loads((source/"dns.json").read_text(encoding="utf-8"))
    if not isinstance(raw_routes,list) or not isinstance(raw_dns,list):
        raise ValueError("Route and DNS exports must be lists")
    errors,devices,seen=[],{},set()
    with (source/"devices.csv").open(encoding="utf-8",newline="") as handle:
        reader=csv.DictReader(handle)
        if not {"device","site","active"}.issubset(reader.fieldnames or []):
            raise ValueError("Device inventory header is incomplete")
        for number,row in enumerate(reader,2):
            try:
                host,site,active=device(row["device"]),label(row["site"]),label(row["active"])
                if active not in ("true","false"):
                    raise ValueError("Invalid active flag")
            except (ValueError,TypeError,AttributeError):
                errors.append({"source":"devices.csv","record":number,"reason":"invalid record"});continue
            if host in seen:
                errors.append({"source":"devices.csv","record":number,"reason":"duplicate device"});continue
            seen.add(host)
            if active=="true" and site in sites:
                devices[host]=site
    routes,route_ids=[],set()
    for number,row in enumerate(raw_routes,1):
        try:
            host,identifier=device(row["device"]),label(row["id"])
            select_routes("0.0.0.0",[row],row["vrf"])
        except (KeyError,TypeError,AttributeError,ValueError):
            errors.append({"source":"routes.json","record":number,"reason":"invalid record"});continue
        if (host,identifier) in route_ids:
            errors.append({"source":"routes.json","record":number,"reason":"duplicate route"});continue
        route_ids.add((host,identifier));routes.append(dict(row,device=host))
    actual_dns=[]
    for number,row in enumerate(raw_dns,1):
        try:
            actual_dns.append(dns_record(row))
        except (KeyError,TypeError,AttributeError,ValueError):
            errors.append({"source":"dns.json","record":number,"reason":"invalid record"})
    exports=collect_device_exports(source/"exports",list(devices),now,age)
    observations,states={},{}
    for export in exports:
        host=export["device"];states[host]=export["status"];relative="exports/"+host+".json"
        if export["status"]!="fresh":
            errors.append({"source":relative,"record":0,"reason":export["status"]+" export"});continue
        for number,row in enumerate(export["data"]["interfaces"],1):
            try:
                name=port(row["interface"])
                if row["admin"] not in ("up","down"):
                    raise ValueError("Invalid admin state")
                vlan_drift([dict(row,device=host,interface=name)],[])
            except (KeyError,TypeError,AttributeError,ValueError):
                errors.append({"source":relative,"record":number,"reason":"invalid interface"});continue
            if (host,name) in observations:
                errors.append({"source":relative,"record":number,"reason":"duplicate interface"});continue
            observations[(host,name)]=row
    interface_rows=[]
    for wanted in sorted(ports,key=lambda row:(row["device"],row["interface"])):
        host,name=wanted["device"],wanted["interface"]
        if host not in devices:continue
        actual=observations.get((host,name));evidence=states[host]
        issues=[];rate={"rx_bps":None,"tx_bps":None,"utilization_percent":None}
        if evidence!="fresh" or actual is None:
            status="unavailable"
            if evidence=="fresh":
                evidence="missing-interface"
                errors.append({"source":"exports/"+host+".json","record":0,"reason":"missing interface: "+name})
        else:
            if actual["admin"]!=wanted["admin"]:issues.append("admin_drift")
            if set(actual["vlans"])!=set(wanted["vlans"]):issues.append("vlan_drift")
            if wanted["admin"]==actual["admin"]=="up":
                if actual.get("oper")!="up":issues.append("link_down" if actual.get("oper")=="down" else "link_unknown")
                rate=interface_rate(actual.get("previous"),actual.get("current"),wanted["speed_bps"])
                if rate["status"]=="unknown":issues.append("rate_unknown")
                elif rate["utilization_percent"]>=threshold:issues.append("high_utilization")
            status="attention" if issues else "disabled" if wanted["admin"]=="down" else "healthy"
        interface_rows.append({"device":host,"interface":name,"site":devices[host],"evidence":evidence,"status":status,"issues":";".join(sorted(issues)),"desired_vlans":"|".join(str(v) for v in wanted["vlans"]),**{key:rate[key] for key in ("rx_bps","tx_bps","utilization_percent")}})
    route_rows=[]
    for target in sorted(targets,key=lambda row:row["id"]):
        if target["device"] not in devices:continue
        matches=select_routes(target["address"],[row for row in routes if row["device"]==target["device"]],target["vrf"])
        route_rows.append(dict(target,status="routed" if matches else "unrouted",route_ids="|".join(row["id"] for row in matches)))
    differences=compare_dns(expected_dns,actual_dns)
    dns_rows=[dict(row,change=kind) for kind in ("missing","unexpected") for row in differences[kind]]
    errors.sort(key=lambda row:(row["source"],row["record"],row["reason"]))
    summary={"assessed_at":current.isoformat().replace("+00:00","Z"),"devices":len(devices),"ports":len(interface_rows),**{status:sum(row["status"]==status for row in interface_rows) for status in ("healthy","attention","disabled","unavailable")},"unrouted":sum(row["status"]=="unrouted" for row in route_rows),"dns_changes":len(dns_rows),"errors":len(errors)}
    destination.mkdir(parents=True,exist_ok=True)
    for name,rows,columns in [
        ("interfaces.csv",interface_rows,["device","interface","site","evidence","status","issues","desired_vlans","rx_bps","tx_bps","utilization_percent"]),
        ("routes.csv",route_rows,["id","device","vrf","address","status","route_ids"]),
        ("dns_changes.csv",dns_rows,["change","name","type","value"]),
        ("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(audit_network())

The audit composes the earlier rules while preserving evidence gaps and scope. Its reports separate configuration drift, unavailable observations, route evidence and DNS differences without executing changes or claiming live reachability.