Automate and document release process for Rust, Python, Wireshark, and Zeek components (#248)

vlvkobal · web-flow · commit 79a297a60059 · 2025-09-03T14:18:43.000-04:00
* Separate release tags

* Add python app release

* Add checkout action before creating a release

* Fix prefix in release creation action

* Filter triggering paths

* Use conventional directory name in release archive

* Add release process section to documentation

* Update release asset names in documentation

* Add release instructions to component specific documentation
diff --git a/.github/workflows/python-release.yml b/.github/workflows/python-release.yml
@@ -0,0 +1,22 @@
+name: Python - Release
+
+on:
+  push:
+    tags:
+      - python-v[0-9]+.*
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      DISTDIR: ja4-${{ github.ref_name }}
+      DISTFILE: ja4-${{ github.ref_name }}.tar.gz
+    steps:
+    - name: checkout
+      uses: actions/checkout@v4
+    - name: create archive
+      run: tar -czf "$DISTFILE" --transform="s,^python,${DISTDIR}," python
+    - name: create release
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: gh release create ${{ github.ref_name }} $DISTFILE
diff --git a/.github/workflows/rust-check.yml b/.github/workflows/rust-check.yml
@@ -11,8 +11,12 @@ permissions:
 on:
   push:
     branches: [main]
+    paths:
+      - '.github/workflows/rust-check.yml'
+      - 'rust/**'
   pull_request:
     paths:
+      - '.github/workflows/rust-check.yml'
       - 'rust/**'
 
 concurrency:
diff --git a/.github/workflows/rust-release.yml b/.github/workflows/rust-release.yml
@@ -1,17 +1,15 @@
 name: Rust - Release
 
 on:
+  push:
+    tags:
+      - rust-v[0-9]+.*
   workflow_dispatch:
     inputs:
       tag:
         description: 'Tag to build release binaries for'
         required: true
         type: string
-  push:
-    tags:
-      - v[0-9]+.*
-  release:
-    types: [created]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
@@ -32,6 +30,7 @@ jobs:
           changelog: rust/CHANGELOG.md
           token: ${{ secrets.GITHUB_TOKEN }}
           allow-missing-changelog: true
+          prefix: rust-
 
   build-and-upload:
     name: ${{ matrix.job.target }}
@@ -58,7 +57,7 @@ jobs:
       shell: bash
       run: |
         is_release=false
-        if [[ $GITHUB_REF =~ ^refs/tags/v[0-9].* ]]; then
+        if [[ $GITHUB_REF =~ ^refs/tags/rust-v[0-9].* ]]; then
             is_release=true
         fi
         echo "is_release=$is_release" >> $GITHUB_OUTPUT
diff --git a/.github/workflows/rust-test.yml b/.github/workflows/rust-test.yml
@@ -11,7 +11,13 @@ permissions:
 on:
   push:
     branches: [main]
+    paths:
+      - '.github/workflows/rust-test.yml'
+      - 'rust/**'
   pull_request:
+    paths:
+      - '.github/workflows/rust-test.yml'
+      - 'rust/**'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
diff --git a/.github/workflows/wireshark-release.yml b/.github/workflows/wireshark-release.yml
@@ -1,9 +1,9 @@
 name: Wireshark - Release
+
 on:
   push:
-    branches: [main]
-    paths: [wireshark/*, wireshark/source/*, wireshark/build-scripts/*]
-  workflow_dispatch:
+    tags:
+      - wireshark-v[0-9]+.*
 
 jobs:
   wireshark-linux:
@@ -99,14 +99,16 @@ jobs:
     runs-on: ubuntu-latest
     needs: [ wireshark-linux, wireshark-macos, wireshark-windows ]
     steps:
-    - name: set env
-      run: echo "NOW=$(date +'%Y.%m.%d.%M')" >> $GITHUB_ENV
+    - uses: actions/checkout@v4
     - name: download-artifacts
       uses: actions/download-artifact@v4
+      with:
+        pattern: '*-ja4'
+        merge-multiple: true
+        path: ja4
     - name: list files
-      run: ls -al
+      run: ls -alR
     - name: release
       env:
         GH_TOKEN: ${{ github.token }}
-        GH_REPO: ${{ github.repository }}
-      run: gh release create ja4-wireshark-plugins-${{ env.NOW }} linux-ja4/ja4.so.linux macos-ja4/ja4.so.macos windows-ja4/ja4.dll
+      run: gh release create ${{ github.ref_name }} ja4/*
diff --git a/.github/workflows/wireshark-test.yml b/.github/workflows/wireshark-test.yml
@@ -2,13 +2,14 @@ name: Wireshark - Test
 
 on:
   push:
+    branches: [main]
     paths:
-      - .github/workflows/wireshark-test.yml
-      - wireshark/**
+      - '.github/workflows/wireshark-test.yml'
+      - 'wireshark/**'
   pull_request:
     paths:
-      - .github/workflows/wireshark-test.yml
-      - wireshark/**
+      - '.github/workflows/wireshark-test.yml'
+      - 'wireshark/**'
 
 jobs:
   run-wireshark-tests:
diff --git a/README.md b/README.md
@@ -32,6 +32,8 @@ If you love JA4+, consider getting a t-shirt or hoodie:
     - [Windows](#windows)
   - [Running JA4+](#running-ja4)
 - [Database](#database)
+- [Release Process](#release-process)
+  - [How to Create a Release](#how-to-create-a-release)
 - [JA4+ Details](#ja4-details)
 - [Licensing](#licensing)
 - [Q\&A](#qa)
@@ -154,13 +156,17 @@ JA4 binaries are built from the [Rust implementation](rust/README.md) of the sui
 
 ### Release Assets
 
-JA4 binaries are provided as compressed archives named according to the target platform, following a pattern like:
 
-```txt
-ja4-vX.Y.Z-<architecture>-<platform>.tar.gz
-```
+Release assets are named according to the component and platform:
+
+- **Rust:**
+  - `ja4-vX.Y.Z-<architecture>-<platform>.tar.gz` (e.g., `ja4-v0.18.5-x86_64-unknown-linux-musl.tar.gz`)
+- **Python:**
+  - `ja4-python-vX.Y.Z.tar.gz` (contains the full `python/` directory)
+- **Wireshark:**
+  - `ja4.so.linux`, `ja4.so.macos`, `ja4.dll` (attached to a release named like `wireshark-vX.Y.Z`)
 
-For example, `ja4-v0.18.5-x86_64-unknown-linux-musl.tar.gz` for Linux or `ja4-v0.18.5-aarch64-apple-darwin.tar.gz` for macOS ARM64. Choose the appropriate file for your system.
+Choose the appropriate file for your system and component.
 
 ### Installing tshark
 
@@ -209,6 +215,52 @@ This database is under very active development. Expect orders of magnitude more
 
 A sample [ja4plus-mapping.csv](./ja4plus-mapping.csv) is also available for quick reference.
 
+## Release Process
+
+
+JA4+ uses GitHub Actions to automate releases for its Rust, Python, Wireshark, and Zeek components. Releases are created by pushing a tag with a specific prefix to the repository, except for Zeek, which uses a pure semantic version (semver) tag. Release assets are named as follows:
+
+- **Rust:** `ja4-vX.Y.Z-<architecture>-<platform>.tar.gz`
+- **Python:** `ja4-python-vX.Y.Z.tar.gz`
+- **Wireshark:** `ja4.so.linux`, `ja4.so.macos`, `ja4.dll` (in a release named like `wireshark-vX.Y.Z`)
+
+The following workflows are available:
+
+- **Rust Release:**  
+  Push a tag starting with `rust-`, e.g., `rust-v0.18.5`, to trigger a release of the Rust binaries. The workflow will build and upload release assets automatically.
+
+- **Python Release:**  
+  Push a tag starting with `python-`, e.g., `python-v0.1.0`, to trigger a release of the Python implementation. The workflow will create a tarball of the `python/` directory and publish it as a release asset.
+
+- **Wireshark Plugin Release:**  
+  Push a tag starting with `wireshark-`, e.g., `wireshark-v2025.09.03`, to trigger a release of the Wireshark plugin binaries for all supported platforms.
+
+- **Zeek Release:**  
+  Push a tag that is a pure semantic version (e.g., `v1.2.3`), with no prefix, to trigger a Zeek release. This will automatically create a release on [packages.zeek.org](https://packages.zeek.org/).
+
+### How to Create a Release
+
+1. Ensure your changes are merged into the `main` branch.
+
+2. Create and push a tag for the component you want to release:
+   - For Rust, Python, or Wireshark, use the appropriate prefix (e.g., `rust-v0.18.5`, `python-v0.1.0`, `wireshark-v2025.09.03`).
+   - For Zeek, use a pure semver tag (e.g., `v1.2.3`).
+
+   Example:
+   ```sh
+   git tag v1.2.3
+   git push origin v1.2.3
+   ```
+   (For Zeek)
+
+   Or, for Rust:
+   ```sh
+   git tag rust-v0.18.5
+   git push origin rust-v0.18.5
+   ```
+
+3. The corresponding GitHub Actions workflow will run and publish the release assets automatically. For Zeek, the release will appear on [packages.zeek.org](https://packages.zeek.org/).
+
 ## JA4+ Details
 
 JA4+ is a set of simple yet powerful network fingerprints for multiple protocols that are both human and machine readable, facilitating improved threat-hunting and security analysis. If you are unfamiliar with network fingerprinting, I encourage you to read my blogs releasing JA3 [here](https://medium.com/salesforce-engineering/tls-fingerprinting-with-ja3-and-ja3s-247362855967), JARM [here](https://medium.com/salesforce-engineering/easily-identify-malicious-servers-on-the-internet-with-jarm-e095edac525a), and this excellent blog by Fastly on the [State of TLS Fingerprinting](https://www.fastly.com/blog/the-state-of-tls-fingerprinting-whats-working-what-isnt-and-whats-next) which outlines the history of the aforementioned along with their problems. JA4+ brings dedicated support, keeping the methods up-to-date as the industry changes.
diff --git a/python/README.md b/python/README.md
@@ -15,6 +15,7 @@ For more details on JA4+ and its implementations in other open-source tools (Rus
     - [Linux](#linux-1)
     - [macOS](#macos-1)
     - [Windows](#windows-1)
+- [Release Assets](#release-assets)
 - [Running JA4+](#running-ja4)
   - [Usage](#usage)
     - [Command-line Arguments](#command-line-arguments)
@@ -24,6 +25,7 @@ For more details on JA4+ and its implementations in other open-source tools (Rus
     - [JSON Output Format](#json-output-format)
   - [Using a Key File for TLS Decryption](#using-a-key-file-for-tls-decryption)
 - [Testing](#testing)
+- [Creating a Release](#creating-a-release)
 - [License](#license)
 
 ## Dependencies
@@ -73,6 +75,14 @@ sudo apt install python3
 
 [Download](https://www.python.org/downloads/windows/) and install Python 3 using the Windows installer.
 
+## Release Assets
+
+Release assets for the Python implementation are named as follows:
+
+- `ja4-python-vX.Y.Z.tar.gz`
+
+This archive contains the full `python/` directory and is attached to a release named like `python-vX.Y.Z`.
+
 ## Running JA4+
 
 Once `tshark` and Python 3 are installed, you can run `ja4.py` as follows:
@@ -222,6 +232,15 @@ For details on generating an SSL key log file, see:
 
 Sample PCAP files for testing `ja4.py` are available in the [`pcap`](../pcap/) directory. These files cover various network protocols and scenarios, including TLS, QUIC, HTTP, SSH, and edge cases. They can be used to verify expected output and assess fingerprinting accuracy.
 
+## Creating a Release
+
+To create a Python release, push a tag starting with `python-`, for example:
+
+```sh
+git tag python-v0.1.0
+git push origin python-v0.1.0
+```
+
 ## License
 
 See the [Licensing](../README.md#licensing) section in the repo root. We are committed to work with vendors and open source projects to help implement JA4+ into those tools. Please contact john@foxio.io with any questions.
diff --git a/rust/README.md b/rust/README.md
@@ -23,6 +23,7 @@ For more details on JA4+ and its implementations in other open-source tools (Pyt
     - [`ja4x` output](#ja4x-output)
   - [Using a Key File for TLS Decryption](#using-a-key-file-for-tls-decryption)
 - [Testing](#testing)
+- [Creating a Release](#creating-a-release)
 - [License](#license)
 
 ## Dependencies
@@ -60,13 +61,11 @@ Download the latest JA4 binaries from the [Releases](https://github.com/FoxIO-LL
 
 ### Release Assets
 
-JA4 binaries are provided as compressed archives named according to the target platform, following a pattern like:
+Release assets are named as follows:
 
-```txt
-ja4-vX.Y.Z-<architecture>-<platform>.tar.gz
-```
+- `ja4-vX.Y.Z-<architecture>-<platform>.tar.gz` (e.g., `ja4-v0.18.5-x86_64-unknown-linux-musl.tar.gz` for Linux, `ja4-v0.18.5-aarch64-apple-darwin.tar.gz` for macOS ARM64)
 
-For example, `ja4-v0.18.5-x86_64-unknown-linux-musl.tar.gz` for Linux or `ja4-v0.18.5-aarch64-apple-darwin.tar.gz` for macOS ARM64. Choose the appropriate file for your system.
+These files are attached to a release named like `rust-vX.Y.Z`. Choose the appropriate file for your system.
 
 ## Building
 
@@ -189,6 +188,15 @@ Run automated tests with:
 cargo test
 ```
 
+## Creating a Release
+
+To create a Rust release, push a tag starting with `rust-`, for example:
+
+```sh
+git tag rust-v0.18.5
+git push origin rust-v0.18.5
+```
+
 ## License
 
 See the [Licensing](../README.md#licensing) section in the repo root. We are committed to work with vendors and open source projects to help implement JA4+ into those tools. Please contact john@foxio.io with any questions.
diff --git a/wireshark/README.md b/wireshark/README.md
@@ -31,6 +31,7 @@ For more details on JA4+ and its implementations in other open-source tools (Pyt
     - [Usage in TShark](#usage-in-tshark)
 - [Using a Key File for TLS Decryption](#using-a-key-file-for-tls-decryption)
 - [Testing](#testing)
+- [Creating a Release](#creating-a-release)
 - [License](#license)
 
 ## Binaries
@@ -39,7 +40,13 @@ Download the latest JA4+ Wireshark plugin binaries from the [Releases](https://g
 
 ### Release Assets
 
-Plugin binaries are provided as dynamic libraries named according to the target platform. For example, `ja4.so.linux` for Linux or `ja4.dll` for Windows. Choose the appropriate file for your system.
+Release assets are named as follows:
+
+- `ja4.so.linux` (Linux)
+- `ja4.so.macos` (macOS)
+- `ja4.dll` (Windows)
+
+These files are attached to a release named like `wireshark-vX.Y.Z`. Choose the appropriate file for your system.
 
 ### Previous Wireshark Versions
 
@@ -261,6 +268,15 @@ cd wireshark/test
 pytest
 ```
 
+## Creating a Release
+
+To create a Wireshark plugin release, push a tag starting with `wireshark-`, for example:
+
+```sh
+git tag wireshark-v2025.09.03
+git push origin wireshark-v2025.09.03
+```
+
 ## License
 
 See the [Licensing](../README.md#licensing) section in the repo root. We are committed to work with vendors and open source projects to help implement JA4+ into those tools. Please contact john@foxio.io with any questions.
diff --git a/zeek/README.md b/zeek/README.md
@@ -20,6 +20,7 @@ See [JA4+ and implementations into other open source tools](../README.md) for mo
 - [Install](#install)
 - [Requirements](#requirements)
 - [Config](#config)
+- [Creating a Release](#creating-a-release)
 - [License](#license)
 
 ## Install
@@ -46,6 +47,15 @@ Zeek 6+ is required for QUIC support.
 Individual JA4+ methods can be enabled or disabled in config.zeek.  
 The raw output for JA4+ methods (non-hashed) can also be enabled in config.zeek
 
+## Creating a Release
+
+To create a Zeek release, push a tag that is a pure semantic version (e.g., `v1.2.3`), with no prefix:
+
+```sh
+git tag v1.2.3
+git push origin v1.2.3
+```
+
 ## License
 
 See [License FAQ](../License%20FAQ.md) for details.
