pktlib 0.2.0__py3-none-any.whl

pktlib/__init__.py

@@ -0,0 +1,104 @@
+"""pktlib: read, edit and write Cisco Packet Tracer .pkt files, in plain Python.
+
+import pktlib
+
+net = pktlib.new()
+r1 = net.router("R1", "1841+WIC-2T", at=(200, 380))
+sw = net.switch("SW0", at=(200, 260))
+pc = net.pc("PC0", at=(200, 150), ip="192.168.1.10/24", gateway="192.168.1.1")
+pc["fa0"].connect(sw["fa0/1"])
+sw["fa0/2"].connect(r1["fa0/0"])
+r1["fa0/0"].address = "192.168.1.1/24"
+net.save("lab.pkt")
+
+net = pktlib.load("lab.pkt")
+print(pktlib.to_python(net))   # any .pkt -> a script that rebuilds it
+
+Everything public is here, at the top level, and in pktlib.lab. Modules whose names
+start with an underscore are pktlib's own and may change in any release.
+"""
+
+import contextlib as _contextlib
+from importlib import metadata as _metadata
+
+from ._audit import Problem, audit
+from ._codec import decode, encode
+from ._editions import EDITIONS, LATEST
+from ._errors import FileFormatError, NotFound, PktError, PktWarning, TagMismatch
+from ._export import to_python
+from ._iosconfig import refused
+from ._model import (
+    Address,
+    Cable,
+    Device,
+    End,
+    Interface,
+    Link,
+    Network,
+    Pdu,
+    Port,
+    Ports,
+    Profile,
+    RsaKey,
+    load,
+    models,
+    new,
+)
+from ._modules import Slot, module_models
+from ._passwords import matches as password_matches
+from ._ports import canonical_port
+from ._shapes import Note, Shape
+from .lab import Fault, Lab, Result
+
+__all__ = [
+    "EDITIONS",
+    "LATEST",
+    "Address",
+    "Cable",
+    "Device",
+    "End",
+    "Fault",
+    "FileFormatError",
+    "Interface",
+    "Lab",
+    "Link",
+    "Network",
+    "NotFound",
+    "Note",
+    "Pdu",
+    "PktError",
+    "PktWarning",
+    "Port",
+    "Ports",
+    "Problem",
+    "Profile",
+    "Result",
+    "RsaKey",
+    "Shape",
+    "Slot",
+    "TagMismatch",
+    "audit",
+    "canonical_port",
+    "decode",
+    "encode",
+    "load",
+    "models",
+    "module_models",
+    "new",
+    "password_matches",
+    "refused",
+    "to_python",
+]
+
+# Public names say they're pktlib's, not a private module's: pktlib.NotFound in a
+# traceback, and help(pktlib.Network) names the right place.
+for _name in __all__:
+    _obj = globals()[_name]
+    if getattr(_obj, "__module__", "").startswith("pktlib."):
+        with _contextlib.suppress(AttributeError, TypeError):  # typing aliases (Cable, Address) can't be
+            _obj.__module__ = __name__
+
+try:
+    __version__ = _metadata.version("pktlib")
+except _metadata.PackageNotFoundError:  # running from a source tree that isn't installed
+    __version__ = "0+unknown"

pktlib/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from ._cli import main
+
+sys.exit(main())

pktlib/_audit.py

@@ -0,0 +1,178 @@
+"""Lint a network before you hand it in: what can be checked without running
+the simulation.
+
+    pktlib audit lab.pkt            # from a shell; exits 1 if it finds anything
+    problems = pktlib.audit(net)    # from Python
+
+Duplicate addresses (MAC, IPv4, IPv6 link-local), config Packet Tracer 8.2 is
+known to refuse, PC gateways nobody owns, the two ends of a link in different
+subnets, cabled ports left shut down, serial DCE ends with no clock rate,
+routers with more than one network and no routing at all, shared OSPF
+router-ids, router ports given their subnet's network or broadcast address.
+A clean audit doesn't prove a ping works: still test in Packet Tracer.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+from collections import defaultdict
+
+from ._iosconfig import blocks, refused
+from ._model import Device, Network
+
+GIGABIT_ONLY = {"PT-REPEATER-NM-1CGE": "PT-REPEATER-NM-1CFE"}  # card -> the FastEthernet one to use
+
+
+class Problem(str):
+    """One thing the audit found: the sentence it prints, plus `devices`,
+    the names of the devices involved (for a grader to point at)."""
+
+    devices: tuple[str, ...]
+
+    def __new__(cls, text: str, *devices: str) -> Problem:
+        p = super().__new__(cls, text)
+        p.devices = tuple(dict.fromkeys(devices))
+        return p
+
+
+def audit(net: Network) -> list[Problem]:
+    """Everything wrong that can be seen in the file, one Problem each."""
+    problems: list[Problem] = []
+    owners: dict[str, list[tuple[str, str]]] = defaultdict(list)  # ip -> [(device, port), ...]
+    router_ifaces: list[tuple[Device, str, ipaddress.IPv4Interface]] = []
+    gateways: set[str] = set()  # addresses a host may use as its gateway, HSRP virtual IPs included
+    for d in net.devices:
+        lan = d.engine.findtext("LAN_IP_ADDRESS")
+        if lan:  # a home router's LAN address, set in its GUI (192.168.0.1 out of the box)
+            gateways.add(lan)
+        if d.has_ios:  # every interface in the config, sub-interfaces and SVIs included
+            for name, (addr, _up) in d.interfaces.items():
+                if addr:
+                    try:
+                        iface = ipaddress.IPv4Interface(addr)
+                    except ValueError:
+                        problems.append(Problem(f"{d.name}.{name}: {addr} isn't an IPv4 address and mask", d.name))
+                        continue
+                    owners[str(iface.ip)].append((d.name, name))
+                    router_ifaces.append((d, name, iface))
+                    # Packet Tracer 8.2 drops either silently when it loads the file and the
+                    # port ends up with no address (checks 6 and 25, 27 Oct 2026)
+                    nw = iface.network
+                    if nw.prefixlen < 31 and iface.ip in (nw.network_address, nw.broadcast_address):
+                        which = "network" if iface.ip == nw.network_address else "broadcast"
+                        problems.append(
+                            Problem(
+                                f"{d.name}.{name}: {iface.ip} is the {which} address of {nw}; "
+                                "Packet Tracer drops it, so the port has no address",
+                                d.name,
+                            )
+                        )
+                    gateways.add(str(iface.ip))
+                for key, line in d.interface_config(name).items():
+                    if key.startswith("standby ") and key.endswith(" ip"):
+                        gateways.add(line.split()[-1])
+                    elif line.startswith("ip address ") and line.endswith(" secondary"):
+                        gateways.add(line.split()[2])  # a second subnet on the same port
+        else:
+            for p in d:
+                if p.address:
+                    owners[str(ipaddress.IPv4Interface(p.address).ip)].append((d.name, p.name))
+
+    for mac, who in net.duplicate_macs().items():
+        problems.append(
+            Problem(
+                f"MAC {mac} is used by more than one device: {', '.join(who)}",
+                *(w.split()[0].split(".")[0] for w in who),
+            )
+        )
+    for ll, who in net.duplicate_link_locals().items():
+        problems.append(
+            Problem(
+                f"IPv6 link-local {ll} is on more than one device: {', '.join(who)}", *(w.split(".")[0] for w in who)
+            )
+        )
+    # two routers with one OSPF router-id: PT left the link in EXSTART and no
+    # OSPF route anywhere (the solar system example, 26 Oct 2026)
+    rids: dict[str, list[str]] = defaultdict(list)
+    for d in net.devices:
+        for header, body in blocks(d.running_config) if d.has_ios else []:
+            if header.startswith("router ospf "):
+                for line in body:
+                    if line.startswith("router-id "):
+                        rids[line.split()[1]].append(d.name)
+    for rid, names in rids.items():
+        if len(names) > 1:
+            problems.append(Problem(f"OSPF router-id {rid} is on more than one router: {', '.join(names)}", *names))
+    for d in net.devices:
+        for line, why in refused(d.running_config) if d.has_ios else []:
+            problems.append(Problem(f"{d.name}: `{line.strip()}` {why}", d.name))
+
+    for ip, where in owners.items():
+        if len(where) > 1:
+            problems.append(
+                Problem(
+                    f"{ip} is on more than one port: {', '.join(f'{a}.{b}' for a, b in where)}", *(a for a, _ in where)
+                )
+            )
+
+    for d in net.devices:
+        if d.has_ios or d.dhcp or d.kind == "IpPhone":  # DHCP clients get theirs when the file opens
+            continue
+        for p in d:
+            if p.el.find("IP") is None or p.type in ("eCopperCoaxial", "eModem"):  # no IP over coax or phone line
+                continue
+            if not p.address:
+                if p.link:
+                    problems.append(Problem(f"{d.name}.{p.name} is cabled but has no IP", d.name))
+                continue
+            iface = ipaddress.IPv4Interface(p.address)
+            if not d.gateway:
+                # only a problem when there's a router address in its subnet to point at:
+                # a switch-only lab has no gateway to give (found by the CCNA examples)
+                if any(i.network == iface.network for _, _, i in router_ifaces):
+                    problems.append(Problem(f"{d.name} has no default gateway", d.name))
+            elif d.gateway not in gateways:
+                problems.append(Problem(f"{d.name}'s gateway {d.gateway} isn't any router's address", d.name))
+            elif ipaddress.IPv4Address(d.gateway) not in iface.network:
+                problems.append(Problem(f"{d.name}'s gateway {d.gateway} is outside {iface.network}", d.name))
+
+    for link in net.links:
+        pa, pb = link.ports
+        (a, ap), (b, bp) = link.ends
+        for p in (pa, pb):
+            if p.device.has_ios and p.device.kind == "Router" and not p.up:
+                problems.append(Problem(f"{p.device.name}.{p.name} is cabled but shut down", p.device.name))
+        if pa.address and pb.address:
+            na, nb = ipaddress.IPv4Interface(pa.address).network, ipaddress.IPv4Interface(pb.address).network
+            if na != nb:
+                problems.append(
+                    Problem(f"{a}.{ap} ({na}) and {b}.{bp} ({nb}) are cabled together but in different subnets", a, b)
+                )
+        for p, other in ((pa, pb), (pb, pa)):
+            # the AccessPoint-PT-AC's stock card won't step down to 100 Mb/s
+            # (seen in Packet Tracer 8.2: red to Fa0/1 and to a PC, green to Gi0/1)
+            if p.module in GIGABIT_ONLY and other.type != "eCopperGigabitEthernet":
+                problems.append(
+                    Problem(
+                        f"{p.device.name}.{p.name} ({p.module}) only links to gigabit ports, not "
+                        f"{other.device.name}.{other.name}; fit {GIGABIT_ONLY[p.module]} instead",
+                        p.device.name,
+                        other.device.name,
+                    )
+                )
+        if link.cable == "serial" and link.dce:
+            dce = net.device(link.dce.device)[link.dce.port]
+            if not dce.setting("clock rate"):
+                problems.append(
+                    Problem(f"{dce.device.name}.{dce.name} is the DCE end with no clock rate", dce.device.name)
+                )
+
+    routers = [d for d in net.devices if d.kind == "Router"]
+    for d in routers if len(routers) > 1 else []:  # one router routes between its own networks
+        nets = {str(i.network) for dev, _, i in router_ifaces if dev.name == d.name}
+        routing = any(line.startswith(("router ", "ip route ")) for line in d.running_config)
+        if len(nets) > 1 and not routing:
+            problems.append(
+                Problem(f"{d.name} has {len(nets)} networks but no routing protocol or static route", d.name)
+            )
+    return problems

pktlib/_cli.py

@@ -0,0 +1,125 @@
+"""pktlib command line.
+
+pktlib decode  in.pkt  [out.xml]     .pkt -> Packet Tracer XML
+pktlib encode  in.xml  out.pkt       XML -> .pkt
+pktlib info    in.pkt                devices, ports in use, links, addresses
+pktlib audit   in.pkt                what's wrong that can be seen in the file (exit 1 if anything)
+pktlib dump    in.pkt  [out.py]      .pkt -> a Python script that rebuilds it
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from ._audit import audit
+from ._codec import decode, encode
+from ._errors import PktError
+from ._export import to_python
+from ._model import Network, load
+
+
+def _out(path: str | None, data: bytes | str) -> None:
+    if path is None:
+        sys.stdout.write(data if isinstance(data, str) else data.decode("utf-8", "replace"))
+    elif isinstance(data, str):
+        Path(path).write_text(data, encoding="utf-8")
+    else:
+        Path(path).write_bytes(data)
+
+
+def _info(path: str) -> str:
+    net = load(path, strict=False)  # reading only: say what it is, whatever version
+    edition = f"edition {net.edition}" if net.edition else "an edition pktlib doesn't know"
+    lines = [f"Packet Tracer {net.version} ({edition})", ""]
+    for d in net.devices:
+        x, y = d.xy
+        lines.append(f"{d.name}  {d.kind} {d.model}  at {x:g},{y:g}")
+        for p in d.ports.values():
+            link = p.link
+            if link is None and not p.ip:
+                continue
+            addr = f" {p.address}" if p.address else ""
+            peer = ""
+            if link is not None:
+                other = link.other(p)
+                peer = f"  -> {other.device.name}.{other.name} ({link.cable})"
+            lines.append(f"  {p.name}{addr}{peer}")
+        if not d.has_ios and d.gateway:
+            lines.append(f"  gateway {d.gateway}")
+    return "\n".join(lines) + "\n"
+
+
+def _audit_files(paths: list[str]) -> int:
+    """Audit each file; exit 1 if any has a problem or can't be read."""
+    bad = 0
+    for path in paths:
+        try:
+            found = audit(load(path))
+        except PktError as e:
+            print(f"pktlib: {path}: {e}", file=sys.stderr)
+            bad += 1
+            continue
+        except OSError as e:
+            print(f"pktlib: {path}: {e.strerror or e}", file=sys.stderr)
+            bad += 1
+            continue
+        lines = "".join(f"  x {p}\n" for p in found)
+        _out(None, lines + (f"{len(found)} problem(s) in {path}\n" if found else f"{path}: nothing found\n"))
+        bad += bool(found)
+    if len(paths) > 1:
+        _out(None, f"{len(paths) - bad} of {len(paths)} files clean\n")
+    return 1 if bad else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the command line; returns the exit code."""
+    ap = argparse.ArgumentParser(prog="pktlib", description="Work with Cisco Packet Tracer .pkt files.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    for name, nargs in (("decode", "?"), ("dump", "?")):
+        p = sub.add_parser(name)
+        p.add_argument("src")
+        p.add_argument("dst", nargs=nargs)
+    p = sub.add_parser("encode")
+    p.add_argument("src")
+    p.add_argument("dst")
+    sub.add_parser("info").add_argument("src")
+    sub.add_parser("audit").add_argument("src", nargs="+")
+    args = ap.parse_args(argv)
+
+    try:
+        if args.cmd == "decode":
+            _out(args.dst, decode(Path(args.src).read_bytes()))
+        elif args.cmd == "encode":
+            xml = Path(args.src).read_bytes()
+            Network.from_xml(xml, strict=False)  # refuse XML Packet Tracer couldn't open
+            _out(args.dst, encode(xml))
+        elif args.cmd == "info":
+            _out(None, _info(args.src))
+        elif args.cmd == "audit":
+            return _audit_files(args.src)
+        elif args.cmd == "dump":
+            out = Path(args.dst).with_suffix(".pkt").name if args.dst else "out.pkt"
+            _out(args.dst, to_python(load(args.src), out))
+    except BrokenPipeError:  # `pktlib decode x.pkt | head`: the reader left, nothing to report
+        sys.stderr.close()
+        return 0
+    except PktError as e:
+        print(f"pktlib: {args.src}: {e}", file=sys.stderr)
+        return 1
+    except OSError as e:
+        print(f"pktlib: {e.filename or args.src}: {e.strerror or e}", file=sys.stderr)
+        return 1
+    except Exception as e:  # noqa: BLE001  a bug in pktlib: say so, without a wall of traceback
+        print(
+            f"pktlib: {args.src}: internal error ({type(e).__name__}: {e}). Please report it at "
+            f"https://github.com/conor-sometimes/pktlib/issues",
+            file=sys.stderr,
+        )
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pktlib/_codec.py

@@ -0,0 +1,64 @@
+"""Turn .pkt / .pka bytes into Packet Tracer's XML and back.
+
+The layers (Packet Tracer 6 onwards, worked out by the pka2xml project):
+
+1. the whole file is byte-reversed and XORed with (L - i*L) & 0xFF, L = file length
+2. Twofish-EAX, key sixteen 0x89 bytes, nonce sixteen 0x10 bytes, 16-byte tag at the end
+3. the plaintext is XORed with (n - i) & 0xFF, n = plaintext length
+4. what is left is Qt's qCompress: a 4-byte big-endian length, then a zlib stream
+"""
+
+from __future__ import annotations
+
+import zlib
+
+from ._errors import FileFormatError
+from ._twofish import eax_decrypt, eax_encrypt
+
+KEY = b"\x89" * 16
+NONCE = b"\x10" * 16
+
+
+def _unscramble_outer(data: bytes) -> bytes:
+    n = len(data)
+    return bytes(data[n - 1 - i] ^ ((n - i * n) & 0xFF) for i in range(n))
+
+
+def _scramble_outer(data: bytes) -> bytes:
+    n = len(data)
+    out = bytearray(n)
+    for i in range(n):
+        out[n - 1 - i] = data[i] ^ ((n - i * n) & 0xFF)
+    return bytes(out)
+
+
+def _xor_inner(data: bytes) -> bytes:
+    n = len(data)
+    return bytes(b ^ ((n - i) & 0xFF) for i, b in enumerate(data))
+
+
+def decode(data: bytes | bytearray, *, verify: bool = True) -> bytes:
+    """Encrypted .pkt bytes -> XML bytes."""
+    if not isinstance(data, (bytes, bytearray)):
+        raise TypeError("decode() wants bytes")
+    plain = eax_decrypt(KEY, NONCE, _unscramble_outer(bytes(data)), verify=verify)
+    packed = _xor_inner(plain)
+    if len(packed) < 4:
+        raise FileFormatError("too short to be a .pkt")
+    size = int.from_bytes(packed[:4], "big")
+    try:
+        xml = zlib.decompress(packed[4:])
+    except zlib.error as e:
+        raise FileFormatError(f"not a .pkt (zlib: {e})") from None
+    if len(xml) != size:
+        raise FileFormatError(f"header says {size} bytes, zlib gave {len(xml)}")
+    return xml
+
+
+def encode(xml: bytes, level: int = 9) -> bytes:
+    """XML bytes -> encrypted .pkt bytes Packet Tracer will open."""
+    if not isinstance(xml, (bytes, bytearray)):
+        raise TypeError("encode() wants bytes")
+    xml = bytes(xml)
+    packed = len(xml).to_bytes(4, "big") + zlib.compress(xml, level)
+    return _scramble_outer(eax_encrypt(KEY, NONCE, _xor_inner(packed)))

pktlib/_editions.py

@@ -0,0 +1,62 @@
+"""Editions: which Packet Tracer a file is for.
+
+A .pkt file carries one version stamp, PACKETTRACER5/VERSION, e.g. 8.2.0.0162
+(major.minor.patch.build). Packet Tracer 8.2.0 checks it on open (tried 25 Oct
+2026): a newer stamp, even 8.2.2, is refused ("This file requires Cisco Packet
+Tracer version ..."), an older one opens, and a stamp that isn't a version is
+refused.
+
+pktlib works like Rust editions: a network has an edition, and pktlib only
+writes editions it has device templates and tested quirks for. Asking for any
+other is an error, so pktlib can't produce a file stamped for a Packet Tracer
+nobody has checked it against.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ._errors import FileFormatError, PktError
+
+# edition -> the exact stamp Packet Tracer writes. One per release pktlib was
+# tested on; add one only with templates and a test run in that release.
+EDITIONS: dict[str, str] = {"8.2": "8.2.0.0162"}
+LATEST = "8.2"
+
+_VERSION_RE = re.compile(r"(\d+)\.(\d+)\.(\d+)\.(\d+)")
+
+
+def parse(version: str) -> tuple[int, int, int, int]:
+    """'8.2.0.0162' -> (8, 2, 0, 162). Anything else is an error, as it is to
+    Packet Tracer."""
+    m = _VERSION_RE.fullmatch((version or "").strip())
+    if not m:
+        raise FileFormatError(f"{version!r} isn't a Packet Tracer version (like 8.2.0.0162)")
+    major, minor, patch, build = (int(g) for g in m.groups())
+    return major, minor, patch, build
+
+
+def stamp(edition: str) -> str:
+    """The version stamp pktlib writes for an edition."""
+    if not isinstance(edition, str):
+        raise TypeError(f"an edition is a string like '8.2', got {edition!r}")
+    if edition not in EDITIONS:
+        raise PktError(
+            f"pktlib doesn't know Packet Tracer edition {edition!r} (it knows {', '.join(sorted(EDITIONS))})"
+        )
+    return EDITIONS[edition]
+
+
+def edition_of(version: str) -> str | None:
+    """The edition a stamp belongs to ('8.2.0.0162' -> '8.2'), or None if pktlib
+    doesn't have that release. A later patch of the same minor (8.2.2) isn't
+    the 8.2 edition: Packet Tracer 8.2.0 refuses those files."""
+    v = parse(version)
+    name = f"{v[0]}.{v[1]}"
+    return name if name in EDITIONS and v <= parse(EDITIONS[name]) else None
+
+
+def newer_than_known(version: str) -> bool:
+    """True for a file from a Packet Tracer newer than any edition pktlib knows."""
+    newest = max(parse(v) for v in EDITIONS.values())
+    return parse(version) > newest

pktlib/_errors.py

@@ -0,0 +1,38 @@
+"""pktlib's exceptions. Catch PktError for anything pktlib refuses.
+
+PktError (a ValueError)
+├── NotFound (also a KeyError): no such device, port, slot, VLAN, model...
+└── FileFormatError: the bytes or XML aren't a .pkt pktlib can read
+    └── TagMismatch: the file's checksum (its EAX tag) is wrong
+
+PktWarning (a UserWarning): done, but Packet Tracer may not take it
+"""
+
+from __future__ import annotations
+
+
+class PktError(ValueError):
+    """Something asked of pktlib doesn't fit the network or the file."""
+
+
+class NotFound(PktError, KeyError):
+    """A lookup found nothing: `net["R9"]`, `r1["fa9/9"]`, a VLAN, a slot, a
+    model name. It is a KeyError too, so code written for dicts catches it."""
+
+    def __str__(self) -> str:
+        # KeyError's own __str__ quotes the message as if it were a key
+        return str(self.args[0]) if self.args else ""
+
+
+class FileFormatError(PktError):
+    """The data isn't a .pkt pktlib can read: damaged, truncated, not Packet
+    Tracer's, or from a release pktlib refuses (see strict=False)."""
+
+
+class TagMismatch(FileFormatError):
+    """The EAX tag didn't verify: the file is damaged or isn't a .pkt."""
+
+
+class PktWarning(UserWarning):
+    """pktlib did what was asked, but Packet Tracer may not: a config line it
+    is known to drop, a VLAN still in use, and the like."""