feat(wireshark-dcquic): add wireshark plugin (#2239)

.gitattributes

@@ -1,2 +1,3 @@
 corpus.tar.gz filter=lfs diff=lfs merge=lfs -text
 *.ebpf filter=lfs diff=lfs merge=lfs -text
+*.pcapng filter=lfs diff=lfs merge=lfs -text

.github/config/typos.toml

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

.github/workflows/ci.yml

@@ -821,3 +821,45 @@ 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
+        with:
+          lfs: true
+
+      - 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: cargo xtask bindings
+
+      - 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 xtask test
+
+      - name: Run build
+        working-directory: dc/wireshark
+        run: cargo xtask build

dc/wireshark/.cargo/config.toml

@@ -0,0 +1,2 @@
+[alias]
+xtask = "run --package xtask --"

dc/wireshark/.clippy.toml

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

dc/wireshark/.gitignore

@@ -0,0 +1,2 @@
+*.pcap
+*.pcapng

dc/wireshark/Cargo.toml

@@ -0,0 +1,32 @@
+[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 = [".", "xtask"]
+
+[profile.fuzz]
+inherits = "dev"
+opt-level = 3
+incremental = false
+codegen-units = 1
+
+# this is to avoid conflicts with already installed plugins
+[profile.release-test]
+inherits = "release"

dc/wireshark/README.md

@@ -0,0 +1,61 @@
+# 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).
+
+To install the plugin for the current machine, use the following command:
+
+```
+cargo xtask install
+```
+
+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`, you can re-generate that file with
+`./generate-bindings.sh`.
+
+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,30 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+fn main() {
+    let plugin_name = option_env("PLUGIN_NAME").unwrap_or_else(|| "dcQUIC".to_string());
+    println!("cargo:rustc-env=PLUGIN_NAME={plugin_name}");
+    println!(
+        "cargo:rustc-env=PLUGIN_NAME_LOWER={}",
+        plugin_name.to_lowercase()
+    );
+
+    // don't link any libraries and prefer pulling symbols from the wireshark/tshark binary
+    if env("TARGET").contains("darwin") {
+        println!("cargo:rustc-link-arg=-Wl,-undefined,dynamic_lookup");
+    } else {
+        println!("cargo:rustc-link-arg=-U");
+        println!("cargo:rustc-link-arg=-shared");
+    }
+}
+
+fn env<N: AsRef<str>>(name: N) -> String {
+    let name = name.as_ref();
+    option_env(name).unwrap_or_else(|| panic!("missing env {name}"))
+}
+
+fn option_env<N: AsRef<str>>(name: N) -> Option<String> {
+    let name = name.as_ref();
+    println!("cargo:rerun-if-env-changed={}", name);
+    std::env::var(name).ok()
+}

dc/wireshark/generate-bindings.sh

@@ -0,0 +1,113 @@
+#!/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 tshark -y
+fi
+
+INCLUDES=(
+  "$(PKG_CONFIG_PATH="$PKG_CONFIG_PATH" pkg-config --cflags-only-I glib-2.0 wireshark)"
+)
+
+OPTIONS=(
+  --allowlist-type 'gint'
+  --allowlist-type 'guint'
+  --allowlist-type 'guint16'
+  --allowlist-type 'guint32'
+  --allowlist-type 'gboolean'
+  --allowlist-type 'nstime_t'
+  --allowlist-type '_packet_info'
+  --allowlist-type '_header_field_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-var 'COL_PROTOCOL'
+  --allowlist-var 'ENC_BIG_ENDIAN'
+  --allowlist-var 'DESEGMENT_ONE_MORE_SEGMENT'
+  --allowlist-var 'DESEGMENT_UNTIL_FIN'
+)
+
+mkdir -p src/wireshark_sys/
+
+# 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 \
+  --raw-line '// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.' \
+  --raw-line '// SPDX-License-Identifier: Apache-2.0' \
+  ${OPTIONS[@]} \
+  wrapper.h \
+  -o src/wireshark_sys/minimal.rs \
+  -- ${INCLUDES[@]}
+
+bindgen \
+  --raw-line '// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.' \
+  --raw-line '// SPDX-License-Identifier: Apache-2.0' \
+  ${OPTIONS[@]} \
+  --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' \
+  wrapper.h \
+  -o src/wireshark_sys/full.rs \
+  -- ${INCLUDES[@]}

dc/wireshark/rust-toolchain

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