Troubleshooting
If you're having a problem with Brimcap, please browse the following sections before you open an issue.
There are two different broad categories of such problems, one involving the application configured to open packet capture files and the other involving the packet captures themselves. The sections below describe each category in detail.
To start debugging such problems, it helps to understand how Zui opens flows
extracted from pcaps. Once the 5-tuple, connection start time, and connection
duration are isolated from the Zeek conn record for the flow, Zui
invokes brimcap search to extract the packets for the target flow
into a temporary file. Once this temporary file has been written to the local
filesystem, the application on your operating system that's configured to
automatically open files ending in .pcap will be launched to open this file.
In typical environments, that application will be Wireshark. However, if no
such application is installed or configured to open .pcap files, clicking the
Packets button in Zui will have no effect. Windows presents a helpful
pop-up in this case to notify about the lack of an appropriate installed
program to handle the file. However, due to an open issue
(zui/1379) this failure is
currently "silent" on macOS and Linux, such that you will see a "Preparation
Complete" pop-up in Zui that indicates the extraction to the temporary file
was successful, but no application will open.
To fix this problem, ensure Wireshark or a similar utility is installed
and that you can open .pcap files outside of Zui by double-clicking them
in the general "files" utility for your operating system.
Note that it would be a misconfiguration to set Zui itself as your operating
system's default application for opening .pcap files, as this would make
Zui's Packets button "point at itself".
If you are able to open a pcap file in Wireshark but not extract flows from it in Zui, it's likely a problem unique to the packet capture itself.
Unfortunately, not all packet captures are created equal. The library that Brimcap invokes to extract flows from your pcap handles the most common variations we've encountered, but you may have come across a corner case that it wasn't prepared to handle.
Such problems are often due to file format variations that are unique to the
system that generated the capture. In such situations, the most expedient debug
path would be to send us the capture file so our developers can use it to
reproduce the problem, fix it, and create automated tests to ensure the problem
doesn't arise again in the future. We understand that concerns regarding
sensitive information
may make it difficult or impossible to share such data. If the specific
capture with which you first saw the problem cannot be shared, an alternative
approach would be to share a special debug capture generated by the same
system, but made up of traffic known to be innocuous (e.g., performing a
curl to a common public web site).
If you're able to reliably reproduce the problem, please open a bug report with as much detail as you can provide, attaching your original capture file, a special debug capture that reproduces the problem, or at minimum just a screenshot or cut & paste of any error message you saw in Zui.
I've clicked in Zui to extract a flow from my pcap into Wireshark, but the flow looks different than when I isolate it in the original pcap file in Wireshark
Brimcap uses Zeek to create summary logs from pcaps. Zeek and Wireshark for the most part treat flows similarly. But we're aware of some subtle differences that you may notice, and there may be other differences of which we're not yet aware.
In Wireshark, you can right-click on a TCP/UDP packet and select Follow TCP
Stream or Follow UDP Stream, which will apply a filter of the format
tcp.stream eq N or udp.stream eq N, where N is a number 0, 1, etc.
based on which flow within the pcap is being isolated. When this is done,
Wireshark appears to treat all packets as part of the same flow if they
share the same 5-tuple,
regardless of how long the flow lasts.
To similarly attempt to isolate flows, Zui relies on Zeek's conn event,
which includes the id and proto fields that capture the 5-tuple for a
flow, along with the fields for ts (time of first packet) and duration
(how long the connection lasted). Zui uses these values to construct a
brimcap search command line to extract the flow from the indexed pcap file.
However, this is where Zeek's occasionally different perception of flows may
come into play.
For starters, Zeek's conn documentation
discloses that the time span covered by the duration field "will not include the final ACK [...] for 3-way or 4-way [TCP] connection tear-downs". Therefore
a TCP flow extracted via Brimcap is likely to be missing such an ACK.
Separately, for UDP flows, Zeek has a udp_inactivity_timeout that defaults to
one minute. This means that UDP flows that don't send or receive traffic for
60 seconds will have their flow state "flushed" from Zeek into a completed
conn event. If the flow is actually still active in the capture such that
more packets for the 5-tuple reappear after the 60 second timeout, a new conn
record would be created by Zeek (and hence would appear separately in Zui, and
therefore be extracted from the original pcap as if it were a separate flow).
These represent what we expect may be the majority of observed differences in flow handling. However, through side-by-side study of Wireshark next to Zeek, we've uncovered the following additional corner cases that may also yield differences:
| Issue | Description |
|---|---|
| zeek/846 | "ts+duration" for TCP flow is missing more than just ACK |
| zeek/847 | Zeek creates many conn records for DNS despite udp_inactivity_timeout=0
|
| zeek/862 | Retransmissions of unsuccessful close attempt keep getting flagged as new connections |
| zeek/864 | Multi-section pcapng with overlapping timestamps creates excess conn events |
| zeek/1163 | Full precision of nanosecond timestamps is not preserved |
If you find yourself running into these issues or others of a similar nature, please reach out to us on our public Slack or open an issue and we'll try to help.
Before opening an issue, or while debugging a previously-opened issue, there's detail you can gather that may help us more quickly provide you with a resolution.
For all information described in this section, we understand that some of it may be of a sensitive nature such that you don't feel you can attach it directly to a public GitHub Issue. If you can crop, blur, or otherwise modify the information before attaching, please do. If you feel you could share such information only privately, please notify us on public Slack and we can arrange to receive it from you in a private 1-on-1 chat.
If you think you've encountered a bug that's specific to how Brimcap interacts with the Zui app, a screenshot or recorded desktop video of your Zui app that includes the error message or unexpected behavior may help us a lot. If you can annotate your media with arrows, text, or other detail, even better. The same is true if you're submitting a detailed feature request.
If your problem involves a pcap file, we'll likely be able to debug much quicker if you can attach a sample pcap file to your issue. If you are able to reproduce the issue using a small pcap that you're certain does not contain sensitive information, that would be ideal.
If you have a video or sample pcap that is too large to attach to a GitHub Issue, please upload it to the file-sharing service of your choosing and paste a link to it in your issue.
Before/when opening a new issue, you can help us out by doing the following:
- Browse the existing open issues. If you confirm you're hitting one of those, please add a comment to it rather than opening a new issue.
- Gather info that may help in reproducing the issue and testing a fix, and attach it to your issue.
- Feel free to chat with the team on the public Slack before/after opening an issue.
- When you open a new issue, its initial text will include a template with standard info that will almost always be needed. Please include detail for all areas of the template.
Thanks for helping us support the community!
Join our Public Slack workspace for announcements, Q&A, and to trade tips!