ptforge
Draw Cisco Packet Tracer topologies in code: build labs, configure devices, assert on them, collect report material.
pip install dsh-ptforge
ptforge demo -o office.pkt # generates a 3-device lab and prints a summary
Two lines and you have a .pkt that Packet Tracer 8.1 opens directly. From there you can describe a whole network as JSON, patch an existing file, run show commands in a real PT window, or turn the result into a report.
Why it exists
Packet Tracer ships no public API: PacketTracer.exe contains no PTAPI, plugins/ only loads Cisco-signed binaries, and extensions/*.pts are encrypted scripts. So an external program has exactly two paths:
| Path | Reality | What ptforge does with it |
|---|---|---|
| Click the canvas, type in the console | Works, but depends on window focus, drifts with zoom, and the terminal only accepts clipboard paste via the context menu | Kept only for the runtime facts that exist nowhere else |
Read and write .pkt directly |
The container is Twofish-EAX + zlib around a <PACKETTRACER5> XML document |
The main engine: topology, links, config, web pages, annotations |
In one sentence: anything provable offline never opens a window; only runtime state (routing tables, NAT translations, reachability, page content) goes through the GUI.
What it can do
| What you want | What to use |
|---|---|
Describe a network as JSON and generate a .pkt |
pt_build / ptforge build |
| Look up models, interface names, free ports | pt_models / ptforge models |
| Print a topology inventory, see which port each link lands on | pt_inspect |
| Change an IP, add a VLAN, rename a device, drop config | pt_patch / pt_apply |
| Read structured state (interfaces, static routes, NAT, ACLs) | pt_state |
Assert on a .pkt (works in offline CI too) |
pt_check |
| Label the canvas with IPs and port names | pt_note |
| Replace a Server-PT web page | pt_server_page |
Run show commands in a real PT window and read the output back |
pt_exec / pt_assert |
| ping / open a page / FTP | pt_ping / pt_http_get / pt_ftp |
| Produce "figure + caption + table" report material | pt_report |
18 tools in total: 12 offline, 6 runtime. Full parameter reference: docs/TOOLS.md.
Install
| Way | Good for | Command |
|---|---|---|
| pip | scripts, CI, containers | pip install dsh-ptforge |
| DSH bundle | calling the tools inside a DeepSeek Harness session | plugin_manager install_bundle target="…/packages/dsh-ptforge" |
| Docker | the offline half on Linux | docker build -t ptforge:0.1.0 . |
pip install "dsh-ptforge[gui]" # adds Pillow, needed by pt_exec / pt_ping / pt_http_get
- The core engine has zero third-party dependencies and only needs Python 3.10+.
- Runtime tools are Windows-only and require Packet Tracer 8.1.x plus an interactive desktop.
- The PyPI distribution is named
dsh-ptforge(ptforgewas already taken by an unrelated project); the import name and the command are stillptforge.
Quick start
1. Write a spec
{
"name": "branch",
"devices": [
{"model": "2911", "name": "R1",
"config": ["hostname R1", "interface GigabitEthernet0/0",
"ip address 10.10.0.254 255.255.255.0", "no shutdown"]},
{"model": "2960-24TT", "name": "SW1", "config": ["hostname SW1"]},
{"model": "PC-PT", "name": "PC1", "ipv4": "10.10.0.11/24,10.10.0.254"},
{"model": "PC-PT", "name": "PC2", "ipv4": "10.10.0.12/24,10.10.0.254"}
],
"links": [
{"from": "R1", "to": "SW1"},
{"from": "PC1", "to": "SW1"},
{"from": "PC2", "to": "SW1"}
]
}
Ports, cable types and coordinates are optional: free ports are picked automatically, same-kind devices get a crossover cable, different kinds get a straight-through cable, and layout is automatic.
2. Build and inspect
ptforge build branch.json -o branch.pkt
ptforge inspect branch.pkt
ptforge check branch.pkt --expect '[{"device":"PC1","interface":"FastEthernet0","ip":"10.10.0.11"}]'
3. Open it in Packet Tracer
ptforge open branch.pkt
Or double-click the .pkt. The file is 8.1.1 format, so you can keep editing it by hand and save it back.
4. Verify at runtime (optional)
In PT, double-click a device and open Desktop → Command Prompt, then:
ptforge-gui exec PC1 "ipconfig"
ptforge-gui ping PC1 10.10.0.12
ptforge-gui assert R1 --checks '[{"command":"show ip route","contains":"10.10.0.0/24"}]'
5. Produce a report
ptforge report branch.pkt -o report --title "Branch acceptance"
You get report/figures/, report/captions.json and report/report.md.
Three ways to call it
Command line (scripts, CI, containers)
ptforge build lab.json -o lab.pkt
ptforge state lab.pkt --device R1
ptforge patch lab.pkt --ops '[{"op":"set_ipv4","device":"PC1","port":"FastEthernet0","address":"10.10.0.21"}]'
Python API (embed it in your own tooling)
from ptforge import spec, state, report
spec.build_from_spec(data, "lab.pkt")
root = state.load("lab.pkt")
result = state.check(root, [{"device": "R1", "route": "10.10.0.0/24"}])
print(result["ok"], result["results"])
report.build_report("lab.pkt", "report")
Full signatures and return shapes: docs/API.md.
DSH tools (let an AI call it inside a DeepSeek Harness session)
pt_build(spec={...}, open=true)
pt_assert(device="R1", checks=[{"command": "show ip route", "contains": "O 10.10.0.0/24"}])
Examples
examples/ contains runnable scripts:
| Script | Shows |
|---|---|
01_build_and_check.py |
spec → .pkt → structured state → assertions |
02_patch_and_state.py |
incremental edit of IP / hostname, then read state back |
03_report.py |
generate report material and print a summary |
python examples/01_build_and_check.py
Documentation
| Doc | Content |
|---|---|
| docs/QUICKSTART.md | End-to-end walkthrough from zero to a verified lab |
| docs/API.md | Python API: signatures, return shapes, exceptions |
| docs/TOOLS.md | Cheat sheet for the 18 DSH tools |
| README.zh-CN.md | Chinese README |
Known limits
- No official API: runtime capabilities are built on window automation, so PT must be visible, interactive and brought to the foreground.
- The console can only copy what is visible: very long output scrolls away; long sessions keep the longest snapshot captured during the run.
- Same-name devices are ambiguous: if two PT instances each have a
PC0, close the duplicate or rename the device. - 8.1.x only: other versions may use different container parameters;
pt_doctorchecks the file version first. - UI coordinates vary between versions: relative coordinates inside a device window may need small adjustments for a different PT build or zoom level.
Development
python -m unittest discover -s tests # 22 tests, no Packet Tracer needed
powershell -File scripts\sync_engine.ps1 # after changing the engine, sync it into the DSH bundle
CI (ci.yml) runs the tests on Python 3.10/3.11/3.12, smokes the CLI and the examples, builds the wheel and checks the asset bank, then builds the container image. Publishing goes through publish.yml with Trusted Publishing — no PyPI token is stored in the repository.
License
The project code is MIT (see LICENSE). The Twofish/EAX implementation under ptforge/ptcrypto/ comes from strykey/pka-decipher; the upstream project has no LICENSE and that code is not covered by MIT — replace it or obtain permission before commercial distribution, see NOTICE.
Not affiliated with Cisco; Packet Tracer is their trademark. The .pkt container format and IOS command syntax are undocumented interfaces, used here only for interoperability in teaching and research.
Metadata
Release files for dsh-ptforge 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dsh_ptforge-0.1.1.tar.gz | 358.4 kB | With provenance | Details for dsh_ptforge-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dsh_ptforge-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for dsh_ptforge-0.1.1-py3-none-any.whl |
Total release size: 837.0 kB
Release files / dsh_ptforge-0.1.1.tar.gz
| Download URL | dsh_ptforge-0.1.1.tar.gz |
|---|---|
| Size | 358.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a4d3b2002d34ddd9ed2f102cb491fa5e063392298eae7a8975053c7de14d9b0d
|
|
BLAKE2b-256 checksum How to use checksums |
feee0d8f45cce9435151289c665d7bf577e9b507156ce69678a38b4c5ab7f818
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / dsh_ptforge-0.1.1-py3-none-any.whl
| Download URL | dsh_ptforge-0.1.1-py3-none-any.whl |
|---|---|
| Size | 478.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c9e6f8062f7680bd39be24ac6727398cea4ede95c28d5ab99772fad0aad68b0e
|
|
BLAKE2b-256 checksum How to use checksums |
ebd5fa4974220ef8d01cf5a0c51f17a617b7cca3f4f232f77caa8202d90d1020
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for dsh-ptforge 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for dsh_ptforge-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.