Skip to content

Commit

Permalink
Add docs about Windows Defender pop-up (#3057)
Browse files Browse the repository at this point in the history
  • Loading branch information
philrz authored Apr 29, 2024
1 parent 689d692 commit 59c4c4a
Show file tree
Hide file tree
Showing 3 changed files with 38 additions and 0 deletions.
1 change: 1 addition & 0 deletions apps/zui/docs/Installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ and we'll be happy to help.

* Download the Zui installer via the **Windows** link at the [Zui download](https://www.brimdata.io/download/) page
* Launch the downloaded `.exe` file to begin installation
* Respond to a Microsoft Defender SmartScreen warning, if shown ([learn more](./support/Troubleshooting.md#microsoft-defender-smartscreen-has-flagged-the-zui-installer-as-an-unrecognized-app))
* Choose between installing for only the current user (default) or a machine-wide install
* Click **Finish** and Zui will launch when installation completes
* Click the Zui icon on the Desktop or Start menu to relaunch in the future
Expand Down
37 changes: 37 additions & 0 deletions apps/zui/docs/support/Troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ also want to review the [current open issues](https:/brimdata/zui/is
* [Zui seems unable to restart normally, such as after a bad crash](#zui-seems-unable-to-restart-normally-such-as-after-a-bad-crash)
* [Zui shows an error: "The service could not be reached"](#zui-shows-an-error-the-service-could-not-be-reached)
* [My antivirus software has flagged Zui as potentially malicious](#my-antivirus-software-has-flagged-zui-as-potentially-malicious)
* [Microsoft Defender SmartScreen has flagged the Zui installer as an "unrecognized app"](#microsoft-defender-smartscreen-has-flagged-the-zui-installer-as-an-unrecognized-app)

#### I've clicked to open a packet capture in Zui, but it failed to open

Expand Down Expand Up @@ -291,6 +292,42 @@ matches our own that this is a "false positive", you can help others by
[flagging it as harmless in VirusTotal](https://support.virustotal.com/hc/en-us/articles/115002146769-Comments),
as multiple community members have already done.

#### Microsoft Defender SmartScreen has flagged the Zui installer as an "unrecognized app"

When launching the `.exe` to install Zui on Windows, you may be presented with
a warning screen like the one shown below. Per
[Microsoft's documentation](https://learn.microsoft.com/en-us/windows/security/operating-system-security/virus-and-threat-protection/microsoft-defender-smartscreen/),
this warning will be presented if Defender believes the Zui installer is not
"well known and downloaded frequently".

![Windows Defender Unrecognized App](media/Windows-Defender-Unrecognized-App.gif)

Based on our experience supporting Zui, it seems the appearance of this
warning is related to Zui's
[code signing certificate](https://learn.microsoft.com/en-us/windows/security/application-security/application-control/windows-defender-application-control/deployment/use-code-signing-for-better-control-and-protection).
Per industry best practices, all Zui releases are signed with such a
certificate to provide assurance that the installer came from Brim Data and
has not been tampered with since it was built. The current certificate details
can be viewed by right-clicking on the Zui `.exe` installer in Windows
Explorer and clicking to **Properties > Digital Signatures**, clicking the
entry in the signature list, then clicking **Details > View Certificate**. Each
certificate used to sign Zui each has a time span for which it is
"valid", and Zui's certificates have traditionally been acquired in 1-year
spans.

What we've observed is that the Defender warning temporarily resurfaces among
users after Zui starts being signed with a new certificate.
[Articles online](https://www.advancedinstaller.com/prevent-smartscreen-from-appearing.html)
describe the common phenomenon that favorable "reputation" with Defender
does not carry over from prior certificates to new ones, so this warning
is expected to appear on new Zui installers for a period of weeks/months after
a new certificate is put into use.

As shown in the video above, the warning can easily be bypassed so
installation may proceed. However, we understand the instinct to take such
warnings seriously. We encourage the use of anti-virus software and other
tools to make your own assessment of Zui's safety.

## Gathering Info

Before [opening an issue](#opening-an-issue), or while debugging a
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 59c4c4a

Please sign in to comment.