Getting Started with Packetry
Follow these steps to start analyzing live USB traffic with Packetry and Cynthion. If you want to use Packetry only to view existing capture files, you can skip the Cynthion steps.
Install Cynthion
Before installing Packetry, follow the instructions to install Cynthion host software and then ensure that your Cynthion is up to date by running:
cynthion update
Install Packetry
Download packetry-x86_64.AppImage
from the latest release. Follow the AppImage Quickstart instructions to make the file executable.
Install Prerequisites
Install the Rust build tools, other essential build tools, and GTK 4 headers:
apt install rustc cargo build-essential libgtk-4-dev git
yum install rust cargo make gcc gcc-c++ gtk4-devel pango-devel git
Note that Packetry requires a minimum Rust version of 1.74. If your distribution’s packages are older than this, use rustup to get the latest Rust toolchain and manage your Rust installation.
Download Packetry Source Code
Clone the Packetry repository:
git clone https://github.com/greatscottgadgets/packetry.git
Build and Install Packetry
cd packetry
cargo build --release
sudo cp target/release/packetry /usr/local/bin
Hint: You can copy the packetry
executable to any directory in your PATH
instead of /usr/local/bin
. If you’ve used rustup
and have ~/.cargo/bin
in your PATH
, ~/.cargo/bin
is a great choice!
Note: Do not build with --all-features
. All the optional features currently in the package are for debug/test purposes only, and will prevent or degrade normal use of the application if enabled. See Cargo.toml
for details.
Use Homebrew to install Packetry:
brew install packetry
Install Prerequisites
Use rustup to install the latest Rust toolchain and manage your Rust installation.
Use Homebrew to install GTK 4:
brew install gtk4
Download Packetry Source Code
Clone the Packetry repository:
git clone https://github.com/greatscottgadgets/packetry.git
Build and Install Packetry
cd packetry
cargo build --release
cp target/release/packetry ~/.cargo/bin
Hint: You can copy the packetry
executable to any directory in your PATH
instead of ~/.cargo/bin
. If you’ve used rustup
, ~/.cargo/bin
should be in your PATH
. Otherwise /usr/local/bin
is a great choice!
Note: Do not build with --all-features
. All the optional features currently in the package are for debug/test purposes only, and will prevent or degrade normal use of the application if enabled. See Cargo.toml
for details.
Download and run the Windows installer from the latest release.
Install Prerequisites
Building Packetry requires that the GTK 4 libraries and header files are available and discoverable via the pkg-config
mechanism. There are several ways you can arrange this; if in doubt we suggest using vcpkg:
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
bootstrap-vcpkg.bat
This next step will take a while. It builds and installs GTK and all its dependencies from source:
vcpkg install gtk pkgconf
Set environment variables so that Packetry can find its dependencies:
set PKG_CONFIG=%CD%\installed\x64-windows\tools\pkgconf\pkgconf.exe
set PKG_CONFIG_PATH=%CD%\installed\x64-windows\lib\pkgconfig
set PATH=%PATH%;%CD%\installed\x64-windows\bin
cd ..
These environment variables will only persist for the lifetime of the current command window, so you may want to set them up elsewhere for future use.
Download Packetry Source Code
Clone the Packetry repository:
git clone https://github.com/greatscottgadgets/packetry.git
Build and Install Packetry
cd packetry
cargo build --release
set PATH=%PATH%;%CD%\target\release
This PATH
modification will only persist for the lifetime of the current command window, so you may want to set it up elsewhere for future use. Alternatively you can copy target\release\packetry
to a location already in your PATH
.
Note: Do not build with --all-features
. All the optional features currently in the package are for debug/test purposes only, and will prevent or degrade normal use of the application if enabled. See Cargo.toml
for details.
Connect Cynthion
Cynthion enables analysis of a USB connection between a target host and a target device. This connection passes through Cynthion’s TARGET A and TARGET C ports. Cynthion watches the traffic on this connection and sends the observed packet data over the CONTROL port for analysis in Packetry.
Connect Cynthion’s CONTROL port to your analysis host computer running Packetry. Connect TARGET C to your target host computer. If your target host and analysis host are the same computer, please be aware of this issue.
You can connect Cynthion’s TARGET A port to your target device at this time, but you may wish to delay this connection until after Packetry is capturing. This will ensure that Packetry can observe the entire device enumeration process and is able to provide detailed information in the Device Pane.
Launch Packetry
Run the Packetry executable. The Packetry window should appear.
Start Capturing USB Traffic
Make sure that “Cynthion” is selected in the Device Drop-down. If this list is empty, use the Scan Button to search for a capture device.
Select the target device speed from the Speed Drop-down. If you don’t know the target speed, try each speed until you find the one that works for your device. (Automatic speed detection coming soon!)
Click the Capture Button.
If the target device is not already connected to TARGET A, connect it now.