Keep missing and stale exports visible
Collect a device batch without turning unavailable evidence into a healthy result.
Coverage is part of the result
An audit should report every requested device, including the ones whose exports are unavailable. Otherwise a summary can look clean simply because the most troublesome systems were absent from the input.
Read one JSON file per normalized device identifier. Validate the full identifier list before opening files, because names are used to construct paths. This teaching format permits ASCII letters, digits and hyphens after normalization; parent traversal and path separators are invalid device names.
File presence does not establish freshness
A file must contain the expected device identity, an interfaces list and an aware observed_at timestamp. Future timestamps are invalid. A valid export exactly the maximum age is fresh; a strictly older export is stale. Compare times in UTC using one caller-supplied now value.
Return data only for fresh exports. Missing, malformed and stale observations have distinct statuses and None data, so later rules cannot accidentally assess stale counters as current evidence. Unexpected I/O errors remain exceptions rather than being hidden by a broad catch.
Deduplicate requested names, sort the batch and leave source files unchanged. This function reads supplied exports from the browser filesystem. It does not collect from devices or imply that a missing file proves an unreachable host. Collection and assessment remain separate operations.
from datetime import datetime, timedelta
now = datetime.fromisoformat("2026-11-17T12:00:00+00:00")
observed = datetime.fromisoformat("2026-11-17T11:00:00+00:00")
print(now - observed > timedelta(minutes=60))
Put it into practice.
Define collect_device_exports(root, devices, now, max_age_minutes). Validate aware now and positive integer maximum age excluding bool. Normalize/deduplicate device strings, requiring [a-z0-9][a-z0-9-]*; reject invalid names before any reads. Read root/<device>.json. Fresh data must be an object with exact normalized device, an interfaces list and aware observed_at <= now. Age strictly greater than maximum is stale; equality is fresh. Return sorted device, status, data rows: fresh plus the original object, or missing/invalid/stale plus None. Missing files => missing; JSON/UTF-8/shape/time errors => invalid; unexpected I/O errors propagate. Preserve inputs.
See an explained solution
from datetime import datetime, timezone
def parse_utc(value):
try:
moment = datetime.fromisoformat(value)
except (TypeError,ValueError) as error:
raise ValueError("Invalid timestamp") from error
if moment.tzinfo is None or moment.utcoffset() is None:
raise ValueError("Timestamp needs an offset")
return moment.astimezone(timezone.utc)
import json,re
from pathlib import Path
from datetime import timedelta
def collect_device_exports(root, devices, now, max_age_minutes):
current = parse_utc(now)
if type(max_age_minutes) is not int or max_age_minutes <= 0:
raise ValueError("Maximum age must be a positive integer")
names = set()
for value in devices:
if not isinstance(value,str) or not re.fullmatch(r"[a-z0-9][a-z0-9-]*",value.strip().casefold()):
raise ValueError("Invalid device identifier")
names.add(value.strip().casefold())
result = []
for name in sorted(names):
data = None
try:
data = json.loads((Path(root)/(name+".json")).read_text(encoding="utf-8"))
if not isinstance(data,dict) or data.get("device") != name or not isinstance(data.get("interfaces"),list):
raise ValueError("Invalid export shape")
collected = parse_utc(data.get("observed_at"))
if collected > current:
raise ValueError("Future export")
status = "stale" if current-collected > timedelta(minutes=max_age_minutes) else "fresh"
except FileNotFoundError:
status = "missing"
except (ValueError,UnicodeError):
status = "invalid"
result.append({"device":name,"status":status,"data":data if status == "fresh" else None})
return result
if __name__ == "__main__":
print(collect_device_exports("exports", ["edge-a"], "2026-11-17T12:00:00Z", 60))
The collector gives downstream rules a clear evidence contract. Missing and stale exports remain countable instead of disappearing from an apparently healthy audit.