feat(wireshark-dcquic): add wireshark plugin

.github/config/typos.toml

@@ -25,5 +25,5 @@ extend-exclude = [
     "*.der",
     "*.pem",
     "**/specs/**/*",
-    "common/duvet/www/public/script.js",
+    "**/wireshark_sys.rs",
 ]

.github/workflows/ci.yml

@@ -821,3 +821,43 @@ jobs:
           RUST_LOG: trace
         run: cargo +stable xtask ci
 
+  dc-wireshark:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macOS-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install rust toolchain
+        run: |
+          rustup toolchain install stable --profile minimal --component clippy,rustfmt
+          rustup override set stable
+
+      - uses: camshaft/install@v1
+        with:
+          crate: bindgen-cli
+          bins: bindgen
+
+      - uses: camshaft/rust-cache@v1
+
+      - name: Generate bindings
+        working-directory: dc/wireshark
+        run: ./generate-bindings.sh
+
+      - name: Run cargo fmt
+        working-directory: dc/wireshark
+        run: cargo fmt --all -- --check
+
+      - name: Run clippy
+        working-directory: dc/wireshark
+        run: cargo clippy --tests
+
+      - name: Run tests
+        working-directory: dc/wireshark
+        run: cargo test
+
+      - name: Run build
+        working-directory: dc/wireshark
+        run: cargo build --release

dc/wireshark/.clippy.toml

@@ -0,0 +1 @@
+msrv = "1.77.0"

dc/wireshark/.gitignore

@@ -0,0 +1,3 @@
+*.pcap
+*.pcapng
+src/wireshark_sys.rs

dc/wireshark/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "wireshark_dcquic"
+version = "0.0.0"
+edition = "2021"
+publish = false
+rust-version = "1.77"
+
+[lib]
+crate-type = ["rlib", "cdylib"]
+
+[dependencies]
+s2n-codec = { path = "../../common/s2n-codec" }
+s2n-quic-core = { path = "../../quic/s2n-quic-core" }
+s2n-quic-dc = { path = "../s2n-quic-dc" }
+
+[dev-dependencies]
+bolero = "0.11"
+s2n-quic-core = { path = "../../quic/s2n-quic-core", features = ["testing", "generator"] }
+s2n-quic-dc = { path = "../s2n-quic-dc", features = ["testing"] }
+
+[workspace]
+members = ["."]
+
+[profile.fuzz]
+inherits = "dev"
+opt-level = 3
+incremental = false
+codegen-units = 1

dc/wireshark/README.md

@@ -0,0 +1,72 @@
+# dcQUIC Wireshark integration
+
+This directory contains a Rust plugin for Wireshark, which supports dissecting
+dcQUIC Datagram, Stream, Control, and Secret Control packets over UDP, and
+Stream packets over TCP. (This is currently full support for what we send in
+current versions of dcQUIC).
+
+The plugin supports heuristic dissection, and will incrementally mark/record
+fields in Wireshark even if the full packet does not parse as we expect. The
+plugin does not currently support making use of any secret material to decrypt
+payloads or verify authentication tags.
+
+## Usage
+
+The plugin is built against Wireshark version 4.2.5 headers. It's likely that a
+new set of bindgen bindings are needed for other versions, and Wireshark will
+refuse to load the plugin outside of the 4.2.x series (without code changes to
+increment the supported minor version).
+
+Build the plugin, potentially cross-compiling to `x86_64-apple-darwin` to match where you will be using Wireshark:
+
+```
+S2N_QUIC_PLATFORM_FEATURES_OVERRIDE=socket_msg,pktinfo,tos cargo build --release --target x86_64-apple-darwin -p wireshark
+```
+
+Then copy the resulting file into Wireshark's plugin directory, for example:
+
+```
+sudo cp target/release/libwireshark_dcquic.so /Applications/Wireshark.app/Contents/PlugIns/wireshark/4-2/epan/wireshark_dcquic.so
+```
+
+Note that you may need to use Finder or grant your terminal application "Full
+Disk Access" in "Privacy & Security" in order for `sudo` to work.
+
+Once this is done, Wireshark should load the plugin successfully on startup.
+You can check (even without a pcap) by (a) not seeing an error message and (b)
+typing `dcquic` into the search bar, which should get auto-completed and
+highlighted green as a valid search.
+
+You can also use the plugin from the command line via `tshark`, for example:
+
+```
+tshark -r stream-request-response.pcap -O dcquic 'dcquic && not tcp'
+```
+
+## Contributing changes
+
+If you need access to more Wireshark APIs that currently don't have bindings in
+`src/wireshark_sys.rs`, you can re-generate that file with
+`./generate-bindings.sh`. Note that it currently has only been run and written
+against one particular environment and isn't run in CI, so it's likely you'll
+need to tweak it to get it working. But it's a good starting point.
+
+https://www.wireshark.org/docs/wsdg_html/#ChapterDissection is a good starting
+point for understanding the basics of the Wireshark interface.
+
+The tests are runnable without a Wireshark installation and are fairly good at
+catching bugs unrelated to the specifics of Wireshark FFI (e.g., parser bugs
+should be caught). We rely primarily on fuzz-style testing, both of valid
+packets (to test fields are properly decoded) and of random packets (to ensure
+lack of panics).
+
+### Why a Rust plugin?
+
+Wireshark supports Lua plugins, but they are comparatively much slower. In our
+testing, a native plugin is 3.3x faster at performing the same body of work as
+a Lua plugin. This cost adds up quickly, especially as we expect to frequently
+work with fairly coarse packet captures that may contain millions of packets.
+
+A Rust plugin also allows for direct interop with our existing code, both for
+help in parsing (e.g., VarInt decoding) and in testing. These are obviously
+possible to integrate into Lua, but would take extra dependencies and work.

dc/wireshark/build.rs

@@ -0,0 +1,21 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+use std::process::Command;
+
+fn main() {
+    let flags = Command::new("pkg-config")
+        .arg("--libs")
+        .arg("glib-2.0")
+        .arg("wireshark")
+        .output()
+        .unwrap();
+
+    for flag in core::str::from_utf8(&flags.stdout)
+        .unwrap()
+        .split(' ')
+        .filter(|f| !f.is_empty())
+    {
+        println!("cargo:rustc-link-arg={flag}");
+    }
+}

dc/wireshark/generate-bindings.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+
+set -xeuo pipefail
+
+VERSION="4.2.5"
+BRANCH="wireshark-$VERSION"
+PKG_CONFIG_PATH="${PKG_CONFIG_PATH:-}"
+
+# Install bindgen...
+if ! command -v bindgen &> /dev/null; then
+    cargo +stable install bindgen-cli
+fi
+
+INCLUDES=()
+
+nixpath() {
+    nix-shell --packages $1 --run 'echo -n $buildInputs'
+}
+
+# add nix-specific paths
+if command -v nix-shell &> /dev/null; then
+  PKG_CONFIG_PATH="$(nixpath wireshark.dev)/lib/pkgconfig:$(nixpath glib.dev)/lib/pkgconfig:$PKG_CONFIG_PATH"
+elif command -v brew &> /dev/null; then
+  brew install pkg-config wireshark
+elif command -v apt-get &> /dev/null; then
+  sudo add-apt-repository ppa:wireshark-dev/stable
+  sudo apt-get update
+  sudo apt-get install pkg-config wireshark-dev -y
+fi
+
+INCLUDES=(
+  "$(PKG_CONFIG_PATH="$PKG_CONFIG_PATH" pkg-config --cflags-only-I glib-2.0 wireshark)"
+)
+
+# This list is filtered to roughly what our current usage requires.
+# It's possible there's a better way to do this -- some of the Wireshark
+# headers end up pulling in C++ so we do need some filtering.
+bindgen \
+  --allowlist-type 'gint' \
+  --allowlist-type 'guint' \
+  --allowlist-type 'guint16' \
+  --allowlist-type 'guint32' \
+  --allowlist-type 'gboolean' \
+  --allowlist-type 'nstime_t' \
+  --allowlist-type '_packet_info' \
+  --opaque-type 'frame_data' \
+  --opaque-type '_proto_node' \
+  --allowlist-type 'frame_data' \
+  --allowlist-type '_proto_node' \
+  --allowlist-type 'proto_plugin' \
+  --opaque-type 'epan_column_info' \
+  --allowlist-type 'epan_column_info' \
+  --opaque-type 'tvbuff' \
+  --allowlist-type 'tvbuff' \
+  --opaque-type 'tvbuff_t' \
+  --allowlist-type 'tvbuff_t' \
+  --opaque-type 'address' \
+  --allowlist-type 'address' \
+  --opaque-type 'port_type' \
+  --allowlist-type 'port_type' \
+  --opaque-type 'GSList' \
+  --allowlist-type 'GSList' \
+  --opaque-type 'GHashTable' \
+  --allowlist-type 'GHashTable' \
+  --opaque-type 'wtap_pseudo_header' \
+  --allowlist-type 'wtap_pseudo_header' \
+  --opaque-type 'wtap_rec' \
+  --allowlist-type 'wtap_rec' \
+  --opaque-type 'conversation_addr_port_endpoints' \
+  --allowlist-type 'conversation_addr_port_endpoints' \
+  --opaque-type 'conversation_element' \
+  --allowlist-type 'conversation_element' \
+  --allowlist-type 'dissector_handle_t' \
+  --allowlist-type 'ftenum_t' \
+  --allowlist-type 'field_display_e' \
+  --allowlist-function 'proto_register_.*' \
+  --allowlist-function 'proto_tree_.*' \
+  --allowlist-function 'proto_item_.*' \
+  --allowlist-function 'tvb_memcpy' \
+  --allowlist-function 'tvb_reported_length' \
+  --allowlist-function 'tvb_reported_length' \
+  --allowlist-function 'heuristic_.*' \
+  --allowlist-function 'heur.*' \
+  --allowlist-function 'create_dissector_handle_with_name_and_description' \
+  --allowlist-function 'col_set_str' \
+  --allowlist-function 'col_append_str' \
+  --allowlist-function 'col_clear' \
+  --allowlist-function 'find_or_create_conversation' \
+  --allowlist-function 'conversation_set_dissector' \
+  --allowlist-var 'COL_PROTOCOL' \
+  --allowlist-var 'ENC_BIG_ENDIAN' \
+  --allowlist-var 'DESEGMENT_ONE_MORE_SEGMENT' \
+  --allowlist-var 'DESEGMENT_UNTIL_FIN' \
+  wrapper.h \
+  -o src/wireshark_sys.rs \
+  -- ${INCLUDES[@]}

dc/wireshark/rust-toolchain

@@ -0,0 +1,3 @@
+[toolchain]
+channel = "1.77.0"
+components = [ "rustc", "clippy", "rustfmt" ]