Pular para o conteúdo principal
C

dsh-ptforge (dsh-ptforge)

chiyan11/dsh-ptforge/packages/dsh-ptforge

Cisco Packet Tracer automation for DeepSeek Harness: builds, patches and asserts on .pkt lab files, and ships 18 pt_* tools for offline editing plus live console checks on a Windows Packet Tracer.

Instalar

dsh plugin --profile web add github:chiyan11/dsh-ptforge

Este plugin está no subdiretório packages/dsh-ptforge do repositório.

README

ptforge

Draw Cisco Packet Tracer topologies in code: build labs, configure devices, assert on them, collect report material.

ci pypi python license

中文

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:

PathRealityWhat ptforge does with it
Click the canvas, type in the consoleWorks, but depends on window focus, drifts with zoom, and the terminal only accepts clipboard paste via the context menuKept only for the runtime facts that exist nowhere else
Read and write .pkt directlyThe container is Twofish-EAX + zlib around a <PACKETTRACER5> XML documentThe 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 wantWhat to use
Describe a network as JSON and generate a .pktpt_build / ptforge build
Look up models, interface names, free portspt_models / ptforge models
Print a topology inventory, see which port each link lands onpt_inspect
Change an IP, add a VLAN, rename a device, drop configpt_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 namespt_note
Replace a Server-PT web pagept_server_page
Run show commands in a real PT window and read the output backpt_exec / pt_assert
ping / open a page / FTPpt_ping / pt_http_get / pt_ftp
Produce "figure + caption + table" report materialpt_report

18 tools in total: 12 offline, 6 runtime. Full parameter reference: docs/TOOLS.md.

Install

WayGood forCommand
pipscripts, CI, containerspip install dsh-ptforge
DSH bundlecalling the tools inside a DeepSeek Harness sessionplugin_manager install_bundle target="…/packages/dsh-ptforge"
Dockerthe offline half on Linuxdocker 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 (ptforge was already taken by an unrelated project); the import name and the command are still ptforge.

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:

ScriptShows
01_build_and_check.pyspec → .pkt → structured state → assertions
02_patch_and_state.pyincremental edit of IP / hostname, then read state back
03_report.pygenerate report material and print a summary
python examples/01_build_and_check.py

Documentation

DocContent
docs/QUICKSTART.mdEnd-to-end walkthrough from zero to a verified lab
docs/API.mdPython API: signatures, return shapes, exceptions
docs/TOOLS.mdCheat sheet for the 18 DSH tools
README.zh-CN.mdChinese README

Known limits

  1. No official API: runtime capabilities are built on window automation, so PT must be visible, interactive and brought to the foreground.
  2. The console can only copy what is visible: very long output scrolls away; long sessions keep the longest snapshot captured during the run.
  3. Same-name devices are ambiguous: if two PT instances each have a PC0, close the duplicate or rename the device.
  4. 8.1.x only: other versions may use different container parameters; pt_doctor checks the file version first.
  5. 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.

Disclaimer

  • Not affiliated with Cisco. This is an independent project. Cisco, Cisco Packet Tracer, IOS and related marks are trademarks of Cisco Systems, Inc. Nothing here is endorsed, sponsored or supported by Cisco.
  • Bring your own Packet Tracer. The runtime tools drive a locally installed, legitimately licensed copy of Cisco Packet Tracer. You are responsible for complying with Cisco's licence terms, your institution's rules and local law. The project does not bypass licensing, authentication or access controls, and it does not redistribute Cisco software or course content.
  • Use at your own risk. The code is provided under the MIT Licence, without warranty of any kind. Offline operations rewrite .pkt files; runtime operations send synthetic mouse and keyboard input to the foreground window. Back up your labs, work on copies, and prefer a disposable VM or snapshot. Do not run the runtime tools unattended on a shared machine.
  • Interoperability, not endorsement. .pkt is an undocumented container and IOS syntax is a de facto interface; both are handled here purely for interoperability in teaching and research. Generated files may be rejected by a different Packet Tracer version or build.
  • No network abuse. pt_ping, pt_http_get and pt_ftp operate only inside your own Packet Tracer simulation. Do not point them at real infrastructure you are not authorised to test.
  • Third-party code. The vendored Twofish/EAX implementation has its own provenance and licensing caveat; see NOTICE.

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.

Plugins relacionados