mbehr1 / vsc-webshark

Visual Studio Code extension to open pcap / network capture files using wireshark/sharkd.

vsc-webshark README

This Visual Studio Code(tm) extension adds support to open pcap/network files. It allows as well to "filter" (create smaller) pcap/pcapng files with a freely-configurable, multi-steps assistant.

Note: The time-sync feature works well with extension and for DLT (diagnostic log and trace) files.

Note: It acts mainly as a UI to a local Wireshark™ installation. So Wireshark (incl sharkd) need to be locally installed.

Note: Wireshark changed the jsonrpc for sharkd with version 3.5. This version requires a wireshark installation >=v3.5! If you need an older wireshark version you need to use v1.7.1 of this extension!

Note: Currently I do find "sharkd" for Windows only as part of the Wireshark Portable packages win64/WiresharkPortable_latest. Extracting the wireshark folder into any local folder and pointing the sharkdFullPath setting to it seems to work (so keeping the regular installation untouched).

Note: Under Linux® the default Debian package doesn't install "sharkd". With Ubuntu 20.04-LTS installing package "tshark" seems to be sufficient.

If you install from source (git clone https://github.com/wireshark/wireshark; cd wireshark; mkdir build; cd build; cmake -DBUILD_wireshark=OFF .. ; make ; ./run/sharkd - <- should build sharkd and print a 'Hello from client'. The path to this binary should be sufficient. Caution might be needed on the plugin directory location. You can keep the default option -DBUILD_wireshark=ON as well but its not needed. Check the list of compile dependencies (e.g. glib-2.0-dev libpcap-dev libgcrypt20-dev lib-c-ares-dev liblua5.3-dev lua5.3 )

Features

• Open 'pcap'/'pcapng' network capture files. Use command "Open pcap file..." or with vscode >=1.46 directly open cap/pcap/pcapng files.
• Display filter with known syntax from wireshark
• Time sync feature.
  • Calculates time for each frame based on timestamp and broadcasts the time to the other Time sync extensions so that they reveal the fitting time ranges.
  • Automatic time-sync based on freely-configurable events that get broadcasted to other extensions so that time shifts between documents are adjusted automatically. (todo add example)
  • Manual offset for the time via context menu item adjust-time....
  • If a time was received already the adjust-time... will propose to adjust/sync the selected line to the received one.
• Tree-view with freely-configurable events based on display filter syntax allows to provide a kind of structure of the frames captured. Selecting an event reveals the frames close to that reception time (even the frames are not part of the current display filter).
• Filter pcap files assistant (mainly to reduce size and ease further analysis). Use command "Filter pcap file...". This generates and executes Wireshark-tshark based filter expressions and executes them to create a new pcap files with only the filter matching frames. The steps are fully configurable. The default settings provide filter on MAC addresses, udp dest ports, tcp dest ports and an additional filter expression.
• Extract DLT from pcap assistant that allows to extract DLT files directly from pcap files. Use command "Extract DLT from pcap file...". Multiple methods can be configured. By default two are available:
  • UDP DLT: select/confirm the UDP port and choose the devices/MAC addresses that sent the DLT data,
  • TECMP UART/RS232_RAW: converts serial DLT traces that are TECMP encapsulated (e.g. from Technica logger).
• Merge pcap files i.e. allow to use multiple input pcap files for Filter pcap and Extract DLT. The input files will be passed to mergecap tool first and merged based on frame timestamps.

The extension uses telemetry with two events (open file, errorcode as parameter or filter pcap) if telemetry is activated within your general configuration.

Planned features

• make it look nicer / more compliant to schema.
• indicate running background tasks

Requirements

sharkd (and tshark) binary from Wireshark >=v3.5 needs to be locally installed. If installed via 'brew' on OSX its installed by default. For Win32/64 and Linux see notes above.

Extension Settings

This extension contributes the following settings:

• vsc-webshark.sharkdFullPath: Specifies the absolute path incl filename to the sharkd binary. This needs to be set after installation.
• vsc-webshark.tsharkFullPath: Specifies the absolute path incl filename to the tshark binary. Defaults to 'tshark'. Needs to be set after installation if tshark is not reachable via search path.
• vsc-webshark.mergecapFullPath: Specifies the absolute path incl filename to the mergecap binary. Defaults to 'mergecap'. Needs to be set after installation if mergecap is not reachable via search path.
• vsc-webshark.wiresharkProfile: Specifies the name of an (installed) wireshark profile.
• vsc-webshark.columns: Defines the columns shown. Uses the format strings as defined e.g. here wireshark github (see readable strings a few lines below). If not provided default values are used.
• vsc-webshark.columnsWidths: Defines the width for the columns. If not provided default values are used.
• vsc-webshark.events: Defined events used for time-sync event detection.
  • Tree-view events need to have:
    • level > 0 and
    • label defined. The label can contain {0} for the %i info column or {1}, {2} ... replacements for the values.
    • displayFilter: any Wireshark display filter expression like "tcp" or "upd or http.request"
    • values: array of strings referring to Wireshark column/display filters like %t or http.request:0 (take care about the :0. It's not the slice operator but the occurrence if that expression is defined by multiple protocols in the proto tree). Values can be referred to from label via {1..n}.
• Time-sync events additionally have (level and label optional):
  • timeSyncId providing the id for the time-sync event
  • timeSyncPrio defining the prio of this event. Other documents use the lowest value (=highest prio) to define which events to use for time adjustment (so whether to use just broadcast their own defined ones or in case of a timeSyncId and timeSyncValue match to adjust the time).
  • conversionFunction can be used to modify the time-sync value calculated for that event. Needs to be a JS function returning a string. If not used the values are concated by ' ' and if no values defined by info column.
• vsc-webshark.filterSteps: defines the configurable steps of the "filter pcap file..." assistant. See the default/configuration for an example. (Todo: provide a full description). Please consider using "-C " in filterArgs and listProvider to use tshark with a minimal configuration (only the plugins activated that you do need for the used filters) to speed up processing significantly. The configuration allows to use multiple steps and chained/piped filters to start with a minimal config and use your default config with more complex plugins/filter expressions (e.g. someip/someipsd plugin) in later steps.
• vsc-webshark.extractDltMethods: Array with the different methods offered for extracting DLT from PCAP files. By default two methods are configured:
  • UDP DLT
  • TECMP UART/RS232_RAW encapsulated. Each method consists of:
  • name: a name to identify
  • steps: similar to filterSteps but for the "extract DLT from pcap file..." function.
  • tSharkArgs: arguments used for tshark to extract the DLT message payload from the pcap file.

Known Issues

• wireshark/sharkd versions before v4.0.5 fail with deprecated filters. See https://gitlab.com/wireshark/wireshark/-/issues/18886. Don't enter deprecated filter expression as this stops further processing for that file. Please update to >= v4.0.5.

Little testing done yet. Little documentation.

• layout not adapting height.
• Scheme colors/options only partially used. Might not be readable/useable in some settings. I used a dark scheme during development only.
• use getState/setState instead of retainContextWhenHidden
• selected frame, ... not persisted on reopen
• pcapng support in sharkd seems limited. Some files can be opened. Some can't (e.g. test102.pcapng from pcapng-test-generator). Consider converting them first.

Release Notes

See Changelog

Contributions

Any and all test, code or feedback contributions are welcome. Open an issue or create a pull request to make this extension work better for all.

Donations are welcome!

GitHub ♥︎ Sponsors are welcome!

Third-party Content

This project leverages the following third party content:

node-webshark

• Source: https://github.com/QXIP/node-webshark
• License: GPL-2.0 https://github.com/QXIP/node-webshark/blob/master/LICENSE

node-webshark is based on webshark by Jakub Zawadski:

• Source: https://bitbucket.org/jwzawadzki/webshark/src/master/
• License: GPL-2.0

Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.

vsc-webshark's Issues

Support Workspace Trust

Hello 👋 I'm from the VS Code team.

Recently, we have been exploring a security feature we refer to as Workspace Trust. This feature is intended to centralize and unify a security conscious decision required by a variety of VS Code features. With workspace trust, the user will be able to declare whether or not they trust the folder that is opened in VS Code before these features are executed.

Why you should care

We want to make sure that those users have a delightful experience with workspace trust and that includes extension authors deciding how much of their extension is supported in an untrusted workspace. Custom editors are special in that if they cannot at least render in an untrusted state then they will be replaced by a lightweight message telling the user to enable trust. This means that users of your extension will not be able to see their editors and there may even be cases of data loss.

Workspace Trust experience

You can enable the feature with the following setting security.workspace.trust.enabled. Once enabled, you will see the following dialog when opening folders in VS Code.

This dialog is important for allowing the user to make a decision early and understand the impact of their decision. Once you understand the feature, you may want to customize when to display the dialog using the setting security.workspace.trust.startupPrompt.

You can follow the development of Workspace Trust and provide feedback in issue #106488.

Workspace trust API

First off, all of what I am about to say can be found in issue #120251. That issue will include discussion of the feature and any updates to the feature.

The Workspace Trust extension API is now in stable. This allowed us to release the first cut of our guide for onboarding your extension to Workspace Trust. The API is small, so here is a quick look.

You can declare your extension to provide complete, partial or no support in untrusted workspaces using the untrustedWorkspaces capability in package.json.

The following example declares that the extension is supported completely in untrusted workspaces. In this case, the extension is enabled in untrusted workspaces.

"capabilities": {
  "untrustedWorkspaces": {
    "supported": true
  }
}

The next example declares that the extension is not supported in untrusted workspaces. In this case, the extension is disabled in untrusted workspaces.

"capabilities": {
  "untrustedWorkspaces": {
    "supported": false
  }
}

The third option is to declared limited support. There are three tools provided to you when you select the limited option.

First, if you have a setting that can be configured in the workspace but requires the workspace to be trusted in order to apply the workspace value, then you can include the setting using restrictedConfigurations array property in untrustedWorkspaces object. Doing so, VS Code will ignore the workspace value of these restricted settings when your extension reads these settings values using the VS Code Workspace Configuration API.

The following example declares the settings that are restricted in untrusted workspaces.

"capabilities": {
  "untrustedWorkspaces": {
    "supported": "limited",
    "restrictedConfigurations": [
      "markdown.styles"
    ]
  }
}

Next, you can also check and listen if the current workspace is trusted or not programmatically using the following API:

export namespace workspace {
  /**
   * When true, the user has explicitly trusted the contents of the workspace.
   */
  export const isTrusted: boolean;
  /**
   * Event that fires when the current workspace has been trusted.
   */
  export const onDidGrantWorkspaceTrust: Event<void>;
}

Lastly, you can hide commands or views declaratively with the isWorkspaceTrusted context key in your when clauses.

A far more detailed guide on how to onboard which will be updated as we receive feedback can be found in issue #120251.

Rollout plan

We are planning on enabling this by default in the near future (most likely next release). To prepare for that day, we want to work with you to allow your editor to work seamlessly alongside the trusted workspace experience

Our Asks

The main features that should work for custom editors in an untrusted folder is rendering, viewing, and saving (if applicable). After renewing your codebase, I believe that your extension does certain things that can be dangerous if the folder contents are malicious (for example, passing user's files to sharkd and making decisions based on responses) therefore I believe that limited is the best option.

Please let me know if you have any question or would like to meet up via voice chat as I would be happy to assist you in getting your extension ready for workspace trust!

about settings

I installed the wirehark in C:\Wireshark\wireshark. But it till has the problem: Assertion Failed: argument is undefined or null. I don't know how to do it.

Remove Telemetry

Looks like this extension emits a bunch of telemetry: https://github.com/mbehr1/vsc-webshark/blob/master/src/extension.ts

Please remove this telemetry if possible.

The automated release is failing 🚨

🚨 The automated release from the master branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you can benefit from your bug fixes and new features again.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can fix this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the master branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here are some links that can help you:

• Usage documentation
• Frequently Asked Questions
• Support channels

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

---

No vsce personal access token specified (set the VSCE_PAT environment variable).

Unfortunately this error doesn't have any additional information. Feel free to kindly ask the author of the semantic-release-vsce plugin to add more helpful information.

---

Good luck with your project ✨

Your semantic-release bot 📦🚀

Resolve IP addr to user-friendly names when extracting dlt logs from pcap

Hello,
As discussed, It will be great to have listed IP addresses from pcap file resolved to user-friendly name when extracting dlt from pcap
Thanks

Resolve IP addresses to user-friendly name

Hello,
As discussed, It will be great to have a configuration to resolve IP addresses to user-friendly name

Can not open pcap.gz

Failed to open pcap.gz file

sharkd sent unexpected stderr: 'sanity check(3a): [3] wrong type

Wireshark and tshark are OK with this.

shard path in windows11

Hi,
I am stuck in the setting because I cannot find sharkd in Wireshark program folder in windows11.
Please, can you explain how to complete the path settings.
Many thanks
Marco

Configurable column settings which can duplicate wireshark column settings

Hello, as discussed
is it possible to configure same column settings from wireshark in webshark plugin?
since im not using "length" and "no" columns and added "delta" column in wireshark column
hence the data is shifted right by 1 column when viewed in webshark plugin

Can't be used without sharkd on Ubuntu 18.04

tshark is installed and vsc-webshark.tsharkFullPath specifies the correct path however the plugin still asks for the sharkd binary

sharkd

Hi,

maybe not the right place, but I did not find anything else, where i could ask :) So I am using a mac, installed vsc-webshark, I do have the sharkd installed at:

/Applications/Wireshark.app/Contents/MacOS ❯ ll | grep sharkd 15:22:59
-rwxr-xr-x 1 aronkertesz admin 225456 Jul 27 20:50 sharkd*
drwxr-xr-x 3 aronkertesz admin 96 Jul 27 20:49 sharkd.dSYM/

But whatever I do, I get the following error message:

sharkdFullPath setting not pointing to a file. Please check setting. Currently used: '/Applications/Wireshark.app/Contents/MacOS/sharkd'

Any hints would be welcome. I am going mad :)

thanks,

aron

Time format options

Firstly, thank you for this extension!

Can I configure the "Time" column to display "Time-of-Day", instead of "Elapsed-Time"? This would allow me to match it up with other events occuring on the system.

By way of comparison, Wireshark supports a lot of time-display-format options:

Currently, I see vsc-webhark shows the "Time" column displayed as elapsed-time from "first-packet" or elapsed-time from a "reference-packet".