Metadata-Version: 2.4
Name: pkt-core
Version: 0.2.0
Summary: Type-safe Python SDK and reverse-engineering codec for Cisco Packet Tracer .pkt and .pka files
Author: aacanadaa
License-Expression: GPL-3.0-or-later
Keywords: packet-tracer,pkt,pka,cisco,file-format,twofish,eax,reverse-engineering,networking,ccna
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Networking
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: hypothesis>=6.90; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"

# Packet Tracer labs, rebuilt offline

> **Made by Shamveel.** Create Packet Tracer `.pkt` labs and scored `.pka` activities entirely offline, without installing Packet Tracer.

This project reverse-engineers the Packet Tracer container format and provides a byte-exact codec plus a Python generator for devices, modules, cabling, IOS config, PC IPs, instructions, activity passwords, and scoring data.

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![No Packet Tracer needed](https://img.shields.io/badge/Packet_Tracer-not_required-32d74b.svg)](#quickstart)
[![Cisco Packet Tracer](https://img.shields.io/badge/Cisco_Packet_Tracer-1BA0D7?style=flat&logo=cisco&logoColor=white)](#overview)

## Overview

Packet Tracer files have no useful magic header and are fully encrypted, so `file`, `strings`, and hex dumps mostly show noise. This repository documents the format and ships tools that read, build, diff, and repack `.pkt` and `.pka` files.

## Highlights

* Build labs directly from Python.
* Generate scored, password-protected activities from the CLI.
* Decode and re-encode Packet Tracer containers byte-for-byte.
* Inspect device models, links, and configuration without opening Packet Tracer.

## Quick Start

```bash
pip install pkt-core
```

```python
from pkt_core import Lab

lab = Lab()

r1 = lab.add_device(
  model="2911",
  name="R1",
  x=200,
  y=250,
  install="HWIC-2T",
  ios_config=[
    "interface GigabitEthernet0/0",
    " ip address 192.168.1.1 255.255.255.0",
    " no shutdown",
    "end",
  ],
)

sw1 = lab.add_device("2960-24TT", "SW1", x=400, y=250)
pc1 = lab.add_device(
  model="PC-PT",
  name="PC1",
  x=600,
  y=250,
  pc_ip=("192.168.1.10", "255.255.255.0", "192.168.1.1"),
)

lab.link(r1, "GigabitEthernet0/0", sw1, "GigabitEthernet0/1")
lab.link(sw1, "FastEthernet0/1", pc1, "FastEthernet0")
lab.save("my_lab.pkt")
```

## What It Can Do

```console
$ python3 tools/make_scored_lab.py --out mylab.pka --spec topology.json --password hunter2
$ pkt info my_lab.pkt
$ pkt unpack my_lab.pkt -o out/
$ pkt pack out/ -o rebuilt.pkt
$ pkt diff before.pkt after.pkt
$ pkt export my_lab.pkt -f graphviz
```

## Library Snapshot

| Module | Responsibility |
| --- | --- |
| `pkt_core.crypto.primitives` | CMAC, CTR, and EAX helpers |
| `pkt_core.crypto.keys` | Per-format key schedule |
| `pkt_core.crypto.stream` | Positional XOR wrappers |
| `pkt_core.crypto.ciphers_pure` | Pure-Python cipher implementations |
| `pkt_core.codec.container` | Detect, decode, and encode containers |
| `pkt_core.xml` | Lossless XML layer |
| `pkt_core.models` | Typed views over labs, devices, ports, and links |
| `pkt_core.diff` | Semantic comparison of labs |
| `pkt_core.export` | Topology export helpers |

## Project Layout

* `src/pkt_core/` contains the reusable library.
* `pt9.py` is the single-file reference codec.
* `tools/` contains the CLI utilities and generators.
* `corpus/` tracks the verification corpus and sample files.

## Notes

* The model layer preserves untouched XML bytes when repacking.
* Format detection relies on container validation rather than a magic prefix.
* Sample containers generated by this project are committed so the tests run out of the box.

## Made by Shamveel

Rebranded by Shamveel.

## Status / scope

**Both container families are fully decoded, both directions.**
`encode(decode(f)) == f` **byte-for-byte on 1058 of 1058 real containers** — see
[`docs/CORPUS_VERIFICATION.md`](docs/CORPUS_VERIFICATION.md).

| Family | Written by | Transform | Files verified |
| --- | --- | --- | --- |
| **modern** | PT **5.3.3** → 9.0.1 | layer A → Crypto++ EAX (Twofish) → layer B → qCompress | 865 |
| **legacy** | PT **4.1** → 5.3.2 | layer B → qCompress *(no AEAD, no reversal)* | 193 |

* The AEAD authentication tag is reproduced exactly and verified on load.
* Verified against **Packet Tracer 9.0.1.0858** (Linux x86-64) and 1,058 real
  files spanning **PT 4.1 through PT 9.0.1**.
* **Neither family has a magic header.** Detection is verifier-based: the EAX tag
  for the modern family (false-positive rate 2⁻¹²⁸), a structural qCompress probe
  for the legacy one. The container switchover is exactly 5.3.2 → 5.3.3.
* Documents are **not always well-formed XML** — `<LINE>` config text carries raw
  control bytes (the Cisco `banner motd ^C…^C` delimiter is a literal `\x03`) and
  PT 4.1 documents end with a trailing NUL. Do not use a validating parser.
* Three root elements exist: `PACKETTRACER5`, `PACKETTRACER5_ACTIVITY` and
  `PACKETTRACER_ACTIVITY` (PT 4.x). Root element is **not** a container
  discriminator.
* `.pkt`/`.pka` are fully supported. The `.pta`/`.pkc` (Serpent) and internal
  `sm`/`userapp` (CAST-256) flavours are specified but need a crypto backend
  with Serpent/CAST-256 (stock `libgcrypt` has neither).

## How it was found

Static analysis of the fully-symbolized `PacketTracer` binary located
`CNetworkFile::openFile`, the `Util::encrypt*/decrypt*` family, the generic
`Util::cipher/decipher<Cipher>` templates, and Crypto++'s `EAX_Base` /
`AuthenticatedDecryptionFilter`.  Packet Tracer was then run headless under
`Xvfb` with `gdb` breakpoints to capture the exact ciphertext and plaintext,
which pinned the CTR counter and both obfuscation layers with byte-accurate
certainty.

## Generating files

Because encoding is byte-exact, the same codec **writes** `.pkt` files.  Tools in
[`tools/`](tools) and notes in [`docs/SCENE_GRAPH.md`](docs/SCENE_GRAPH.md):

* `tools/harvest_merge.py` — harvest one complete device of every model from a
  tree of existing `.pkt` files and merge them into one canvas, handling the
  physical-workspace remapping PT requires.
* `tools/build_wired_lab.py` — the same, **plus auto-wiring**: cables every
  ethernet-capable device to a backbone of core switches and chains the cores.
* `tools/build_configured_lab.py` — a full **working, configured** lab
  (`PC1－SW1－R1＝R2－SW2－PC2` with IPs, gateways, static routes, and an optional
  long running-config).  IOS config is written as `<RUNNINGCONFIG><LINE>…`
  commands and applied on load; PCs get `<IP>/<SUBNET>/<PORT_GATEWAY>`.  See
  [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md).
* `tools/activity.py` + `tools/scoring.py` — author **activity files (`.pka`)** with the Activity Wizard: instructions (HTML), the **activity-wizard password**, permissions, feedback, the **initial / answer networks**, and the **scoring tree**.  See [`docs/ACTIVITY.md`](docs/ACTIVITY.md).
* `tools/make_scored_lab.py` — **one-shot offline generator**: from a topology spec (`--spec`) it builds the initial + answer networks, derives scoring, and writes a scored `.pka`.  No Packet Tracer needed.  Ships with a library of **137 device templates, 75 module templates and 14 scoring shapes** (`tools/device_templates.json`, `tools/device_shapes.json`).
* `tools/harvest_library.py` — (re)build those libraries from your own `.pkt`/`.pka` files to extend model/shape coverage.
* `tools/lab_api.py` — a small library of the **verified authoring operations**
  (place device, power on/off, install a module, cable copper, write IOS
  `RUNNINGCONFIG`, set PC IP/DHCP).  Capability matrix + details in
  [`docs/CAPABILITIES.md`](docs/CAPABILITIES.md).
* Editing: decode → change device names/config/positions → encode → PT opens it.

Result of running the wired builder here: **147 devices, 140 distinct models,
71 cables** (routers, switches, ASAs, WLCs, APs, IP phones, PCs/laptops/tablets,
servers, and a large IoT/industrial set) in one file that Packet Tracer opens
and draws connected.

Key facts for anyone generating files (details in the scene-graph notes):

* Devices carry a *physical scene* placement that must be remapped when merging.
* A cable binds by `<FROM>`/`<TO>` ids and `<PORT>` names; the device needs an
  `<ENGINE>/<SAVE_REF_ID>` and the port must exist on that exact instance.  The
  `*_MEM_ADDR` fields are not validated — PT rebinds.

## Legal / ethical

* Interoperability research on a file format, using a locally installed copy of
  Packet Tracer and the author's own files.
* No DRM or licence protection is bypassed; there is no encryption password.
* Intended for reading *your own* files, format documentation, tooling and
  archival.
* **Do not** use this to obtain, alter, or submit assessment/competition answer
  keys.  That is cheating and is out of scope.

