packet-tracer-skill 0.1.0

package/references/pkt-format.md

@@ -0,0 +1,57 @@
+# Packet Tracer 9.0 Format Notes
+
+This skill targets the modern Packet Tracer `.pkt` format described in the
+research notes supplied alongside the skill update request.
+
+## High-Level Pipeline
+
+1. Packet Tracer XML bytes
+2. qCompress wrapper
+3. Stage-2 XOR obfuscation
+4. Twofish/EAX encryption with a 16-byte authentication tag
+5. Stage-1 reverse/XOR obfuscation
+
+## qCompress Wrapper
+
+The qCompress-compatible wrapper used here is:
+
+- 4-byte big-endian uncompressed length
+- zlib-compressed payload
+
+## Modern Codec Constants
+
+- Twofish key: `0x89` repeated 16 times
+- EAX nonce seed: `0x10` repeated 16 times
+- Tag length: `16`
+
+## Stage-2 XOR
+
+Stage-2 XOR is symmetric:
+
+```text
+out[i] = in[i] XOR ((L - i) & 0xFF)
+```
+
+where `L` is the input length.
+
+## Stage-1 Obfuscation
+
+For output:
+
+```text
+out[L - 1 - i] = in[i] XOR ((L - i * L) & 0xFF)
+```
+
+For decode:
+
+```text
+clear[i] = obf[L - 1 - i] XOR ((L - i * L) & 0xFF)
+```
+
+## Compatibility Notes
+
+- The XML root should be `PACKETTRACER5`
+- The targeted version field is `9.0.0.0810`
+- Cross-version compatibility is not assumed
+- The template library in this skill is a controlled starter set, not a complete
+  reverse-engineered clone of all Packet Tracer internals

package/references/xml-skeleton-notes.md

@@ -0,0 +1,44 @@
+# XML Skeleton Notes
+
+The builder uses a `PACKETTRACER5` root and organizes generated content under a
+`NETWORK` node with `DEVICES`, `LINKS`, and `SHAPETESTS`.
+
+## Base Document Shape
+
+```xml
+<PACKETTRACER5>
+  <VERSION>9.0.0.0810</VERSION>
+  <PIXMAPBANK />
+  <MOVIEBANK />
+  <NETWORK>
+    <DEVICES />
+    <LINKS />
+    <SHAPETESTS />
+  </NETWORK>
+  <OPTIONS />
+  <PHYSICALWORKSPACE />
+</PACKETTRACER5>
+```
+
+## Template Strategy
+
+This skill does not attempt to synthesize the entire Cisco-internal XML schema from
+scratch. Instead, it uses:
+
+- a stable base XML document
+- per-device XML templates
+- targeted placeholder replacement for names, models, positions, ports, and configs
+
+## Current Supported Device Templates
+
+- `router.xml`
+- `switch.xml`
+- `pc.xml`
+
+Each template includes:
+
+- a generated device id
+- human-readable device name
+- type and model fields
+- layout coordinates
+- a config section appropriate for the device family

package/requirements-dev.txt

@@ -0,0 +1 @@
+pytest>=8,<9

package/requirements.txt

@@ -0,0 +1,6 @@
+# Runtime Python dependencies
+#
+# The main runtime is intentionally standard-library-first.
+# Packet Tracer encode/decode for modern 9.x files additionally needs a local
+# Twofish bridge binary configured via PKT_TWOFISH_LIBRARY or placed under
+# scripts/vendor/.

package/scripts/build_sample_catalog.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from pathlib import Path
+import xml.etree.ElementTree as ET
+
+from packet_tracer_env import require_packet_tracer_saves_root
+from pkt_codec import decode_pkt_modern
+from sample_catalog import write_catalog_outputs
+
+
+def summarize_pkt(path: Path) -> dict:
+    saves_root = require_packet_tracer_saves_root()
+    xml = decode_pkt_modern(path.read_bytes())
+    root = ET.fromstring(xml)
+    devices = []
+    for device in root.findall(".//DEVICES/DEVICE"):
+        type_node = device.find("./ENGINE/TYPE")
+        devices.append(
+            {
+                "name": device.findtext("./ENGINE/NAME", default=""),
+                "type": device.findtext("./ENGINE/TYPE", default=""),
+                "model": type_node.get("model", "") if type_node is not None else "",
+            }
+        )
+    links = []
+    for link in root.findall(".//LINKS/LINK"):
+        cable = link.find("./CABLE")
+        ports = cable.findall("PORT") if cable is not None else []
+        links.append(
+            {
+                "type": link.findtext("./TYPE", default=""),
+                "cable_type": cable.findtext("./TYPE", default="") if cable is not None else "",
+                "ports": [port.text or "" for port in ports[:2]],
+            }
+        )
+    return {
+        "relative_path": str(path.relative_to(saves_root)),
+        "version": root.findtext("./VERSION", default=""),
+        "device_count": len(devices),
+        "link_count": len(links),
+        "devices": devices,
+        "links": links,
+    }
+
+
+def build_catalog() -> list[dict]:
+    saves_root = require_packet_tracer_saves_root()
+    items = []
+    for path in sorted(saves_root.rglob("*.pkt")):
+        try:
+            items.append(summarize_pkt(path))
+        except Exception as exc:
+            items.append({"relative_path": str(path.relative_to(saves_root)), "error": f"{type(exc).__name__}: {exc}"})
+    return items
+
+
+def main() -> None:
+    require_packet_tracer_saves_root()
+    items = build_catalog()
+    write_catalog_outputs(items)
+    print(f"Wrote {len(items)} sample entries")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/donor_diagnostics.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Runtime diagnostics for Packet Tracer donor compatibility."""
+
+from __future__ import annotations
+
+import json
+from packet_tracer_env import inspect_packet_tracer_compatibility_donor
+
+
+def main() -> int:
+    details = inspect_packet_tracer_compatibility_donor()
+    result = {
+        "target_version": details.target_version,
+        "resolved_donor_path": str(details.resolved_path) if details.resolved_path else "",
+        "donor_path": str(details.resolved_path) if details.resolved_path else "",
+        "donor_version": details.donor_version or "",
+        "donor_source": details.donor_source or "",
+        "status": details.status,
+        "message": (
+            f"{details.resolved_path} (version {details.donor_version})"
+            if details.status == "ok" and details.resolved_path and details.donor_version
+            else details.blocking_reason or details.status
+        ),
+        "blocking_reason": details.blocking_reason,
+        "candidate_paths": [
+            {"source": source, "path": str(path)}
+            for source, path in details.candidate_paths[:10]
+        ],
+    }
+    print(json.dumps(result))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())