Wireshark Lua Plugin Template

A complete development environment for building Wireshark protocol dissectors and GUI plugins in Lua, with automated snapshot testing using TShark.

Features

• 🔍 Protocol Dissector Development: Create custom protocol dissectors with full IDE support
• 💡 Type Hints: Full Wireshark Lua API type definitions for IntelliSense
• 🧪 Snapshot Testing: Automated testing using TShark output comparison
• 🔄 Live Development: Watch mode that auto-runs tests as you code
• 📦 Automated Releases: GitHub Actions workflow for version management

Quick Start

1. Fork and Clone

• Click "Use this template" on GitHub or fork this repository

• Clone your new repository:

  git clone https://github.com/your-username/your-plugin-name.git
  cd your-plugin-name

2. Install Dependencies

Install Node.js dependencies for the test infrastructure:

npm install

Prerequisites:

• Node.js (v14 or higher)
• Wireshark/TShark installed and in PATH (or at C:\Program Files\Wireshark\ on Windows)

3. Install Lua Language Server (Recommended)

For IDE support with autocomplete and type checking:

1. Install the Lua Lanugage Server (sumneko.lua) extension in VS Code
2. The project includes Wireshark Lua API type definitions in wireshark-lua-api/
3. Start coding with full IntelliSense support!

Creating Your First Dissector

Step 1: Create the Dissector File

Create a new file in the project root named after your protocol (e.g., xyz.lua if you are writing a dissector fot a protocol called "XYZ").

See myproto.lua for a complete example, as well as official Wireshark documentation at:

• Wireshark Lua API Reference
• Wireshark Lua Examples

Important Naming Convention:

• Dissector filename: myprotocol.lua (lowercase, no spaces)
• Protocol name in Proto(): "myprotocol" (must match filename without .lua)
• Test files prefix: myprotocol-*.pcap (use the dissector filename as prefix)

Step 2: Capture Test Traffic

Capture a set of sample packets for the protocol you are covering, and save them to test/samples, ideally 1 packet per file. This can be done from Wireshark using File / Export Specified Packets... / Selected.

Note: the filenames should follow the pattern of <protocol>-<scenario>.pcap. For example, protocol myproto has an Acknowledge command, that is captured in a file named myproto-ack.pcap.

Step 3: Watch Mode Development

Use watch mode to see live dissector output while you develop:

npm run watch-sample myprotocol-packetname.pcap

This will:

1. Run TShark with your dissector on the pcap file
2. Display the parsed output
3. Auto-reload whenever you save changes to any .lua file

Tips for watch mode:

• Keep captures small (1-5 packets) for faster iteration
• Use descriptive filenames: myprotocol-handshake.pcap, myprotocol-error-response.pcap
• The script auto-detects the dissector from the filename prefix

Step 4: Save Expected Output

When your dissector output looks correct, generate the expected output file:

npm run update-expected myprotocol-handshake.pcap

This creates tests/samples/myprotocol-test.expected containing the TShark output.

You can use globs:

npm run update-expected myprotocol-*.pcap   # All myprotocol captures
npm run update-expected *.pcap              # All captures

Step 5: Run Tests

Run the full test suite to verify all snapshots match:

npm test

The test runner automatically:

• Finds all .pcap files in tests/samples/
• Matches them to .expected files
• Extracts the protocol name from the filename (e.g., myprotocol-test.pcap → myprotocol.lua)
• Compares actual TShark output against expected output

Interactive Debugging with Wireshark

Launch Wireshark with your dissectors pre-loaded:

npm run wireshark

This automatically loads all .lua files from the project root.

Opening a specific capture:

npm run wireshark -- -r tests/samples/myprotocol-test.pcap

Live capture:

npm run wireshark
# Then: Capture → Options → select interface and start

What gets loaded:

• All .lua dissector files in the project root
• Your dissectors are active immediately - no manual plugin installation needed

Building Other Wireshark Plugins

Wireshark Lua plugins aren't limited to protocol dissectors. You can also create GUI extensions, listeners, etc.

The template includes a GUI plugin example in mywindow.lua.

See Lua Support in Wireshark for full documentation.

Naming Conventions Summary

Component	Example	Rule
Dissector file	myprotocol.lua	Lowercase, in project root
Protocol name	Proto("myprotocol", ...)	Must match filename (without .lua)
Capture files	myprotocol-handshake.pcap	Prefix must match dissector filename
Expected files	myprotocol-handshake.expected	Auto-generated, same name as .pcap
Test detection	myprotocol-*.pcap → myprotocol.lua	Automatically maps by prefix

Why this matters:

• The test framework splits filenames on - to find the dissector
• myprotocol-test.pcap → looks for myprotocol.lua
• foobar-error.pcap → looks for foobar.lua

Cleanup

You can delete all examples included with this template by running

npm run delete-examples

This will delete mywindow.lua, myproto.lua and tests/samples/myproto*.* files.

Automated Releases

The included GitHub Actions workflow automatically creates releases when you push version tags.

Creating a Release

1. Update your version (optional - workflow does this automatically):

   -- In your dissector file
   local release = "1.2.3"

2. Create and push a git tag:

   git tag v1.2.3
   git push origin v1.2.3

3. Workflow automatically:

   • Updates local release = "1.2.3" in all .lua files
   • Creates a GitHub release with tag v1.2.3
   • Attaches all .lua files as release assets
   • Generates release notes from commits

Note: The workflow only runs for repositories created from this template, not the template itself (checked via repository name).

Examples

This template includes a complete real-world example - myproto.lua.

Test samples: See tests/samples/myproto-*.pcap for examples of test coverage.

This template was created as a byproduct of my mitka/wireshark-scte project that has a bit more complex dissector than the one included with the template.

Project Structure

├── .github/
│   └── workflows/
│       └── release.yml          # Automated release workflow
├── tests/
│   ├── samples/                 # Packet captures and expected outputs
│   │   ├── myproto-test.pcap
│   │   └── myproto-test.expected
│   ├── helpers/                 # Test infrastructure
│   │   ├── runTShark.js         # TShark wrapper
│   │   └── compare.js           # Snapshot comparison
│   ├── test_samples.spec.js     # Main test runner
│   ├── update_expected.js       # Generates .expected files
│   ├── watch_sample.js          # Watch mode script
│   └── run_wireshark.js         # Wireshark launcher
├── wireshark-lua-api/           # Type definitions for IDE (not loaded at runtime)
├── .luarc.json                  # Lua Language Server configuration
├── myprotocol.lua               # Your dissector(s) / plugins
└── package.json                 # npm module manifest / scripts

NPM Scripts Reference

Command	Description
npm test	Run all snapshot tests
npm run watch-sample <name>	Watch mode for single capture
npm run update-expected <glob>	Generate/update .expected files
npm run wireshark	Launch Wireshark with all .lua files loaded
npm run wireshark -- -r file.pcap	Launch Wireshark with a specific capture
npm run clean-myproto	Delete example files (myproto.lua, mywindow.lua, samples)

Wireshark Lua Documentation

Official Documentation:

• Lua API Reference - Complete API documentation
• Lua Modules - GUI, Proto, Field modules

Tips and Best Practices

Dissector Development

1. Start small: Begin with a simple dissector for 1-2 fields
2. Use watch mode: Iterate quickly with npm run watch-sample
3. Keep captures minimal: 1-5 packets per test case
4. Test edge cases: Create separate captures for errors, malformed packets, etc.

Testing

1. Descriptive filenames: protocol-scenario.pcap (e.g., http-redirect.pcap)
2. One scenario per file: Don't mix multiple test cases
3. Commit both files: Always commit .pcap and .expected together
4. Review diffs: Check git diff on .expected files when making changes

Performance

1. Avoid repeated lookups: Cache field extractions
2. Limit tree depth: Don't create unnecessary subtrees
3. Use local variables: Minimize global access
4. Profile with large captures: Test with realistic traffic volumes

Troubleshooting

Tests failing after editing dissector?

• Delete the corresponding .expected file
• Run npm run update-expected <name>.pcap to regenerate expected output

Dissector not loading in Wireshark?

• Check for Lua syntax errors in the dissector file
• tshark and Wireshark will report Lua syntax / runtime errors as well
• Ensure protocol name matches filename

TShark not found?

• Install Wireshark ant tshark and add to PATH. On a Mac, there is an additional installation package in the .dpkg for this.

Test runner can't find .lua file?

• Ensure .pcap filename prefix matches .lua filename exactly

License

MIT License - see LICENSE file for details

Contributing

Contributions welcome! Please open an issue or submit a pull request.