Skip to content

Commit 59c4c4a

Browse files
authored
Add docs about Windows Defender pop-up (#3057)
1 parent 689d692 commit 59c4c4a

File tree

3 files changed

+38
-0
lines changed

3 files changed

+38
-0
lines changed

apps/zui/docs/Installation.md

+1
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ and we'll be happy to help.
3232

3333
* Download the Zui installer via the **Windows** link at the [Zui download](https://www.brimdata.io/download/) page
3434
* Launch the downloaded `.exe` file to begin installation
35+
* 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))
3536
* Choose between installing for only the current user (default) or a machine-wide install
3637
* Click **Finish** and Zui will launch when installation completes
3738
* Click the Zui icon on the Desktop or Start menu to relaunch in the future

apps/zui/docs/support/Troubleshooting.md

+37
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ also want to review the [current open issues](https://github.com/brimdata/zui/is
1717
* [Zui seems unable to restart normally, such as after a bad crash](#zui-seems-unable-to-restart-normally-such-as-after-a-bad-crash)
1818
* [Zui shows an error: "The service could not be reached"](#zui-shows-an-error-the-service-could-not-be-reached)
1919
* [My antivirus software has flagged Zui as potentially malicious](#my-antivirus-software-has-flagged-zui-as-potentially-malicious)
20+
* [Microsoft Defender SmartScreen has flagged the Zui installer as an "unrecognized app"](#microsoft-defender-smartscreen-has-flagged-the-zui-installer-as-an-unrecognized-app)
2021

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

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

295+
#### Microsoft Defender SmartScreen has flagged the Zui installer as an "unrecognized app"
296+
297+
When launching the `.exe` to install Zui on Windows, you may be presented with
298+
a warning screen like the one shown below. Per
299+
[Microsoft's documentation](https://learn.microsoft.com/en-us/windows/security/operating-system-security/virus-and-threat-protection/microsoft-defender-smartscreen/),
300+
this warning will be presented if Defender believes the Zui installer is not
301+
"well known and downloaded frequently".
302+
303+
![Windows Defender Unrecognized App](media/Windows-Defender-Unrecognized-App.gif)
304+
305+
Based on our experience supporting Zui, it seems the appearance of this
306+
warning is related to Zui's
307+
[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).
308+
Per industry best practices, all Zui releases are signed with such a
309+
certificate to provide assurance that the installer came from Brim Data and
310+
has not been tampered with since it was built. The current certificate details
311+
can be viewed by right-clicking on the Zui `.exe` installer in Windows
312+
Explorer and clicking to **Properties > Digital Signatures**, clicking the
313+
entry in the signature list, then clicking **Details > View Certificate**. Each
314+
certificate used to sign Zui each has a time span for which it is
315+
"valid", and Zui's certificates have traditionally been acquired in 1-year
316+
spans.
317+
318+
What we've observed is that the Defender warning temporarily resurfaces among
319+
users after Zui starts being signed with a new certificate.
320+
[Articles online](https://www.advancedinstaller.com/prevent-smartscreen-from-appearing.html)
321+
describe the common phenomenon that favorable "reputation" with Defender
322+
does not carry over from prior certificates to new ones, so this warning
323+
is expected to appear on new Zui installers for a period of weeks/months after
324+
a new certificate is put into use.
325+
326+
As shown in the video above, the warning can easily be bypassed so
327+
installation may proceed. However, we understand the instinct to take such
328+
warnings seriously. We encourage the use of anti-virus software and other
329+
tools to make your own assessment of Zui's safety.
330+
294331
## Gathering Info
295332

296333
Before [opening an issue](#opening-an-issue), or while debugging a
Loading

0 commit comments

Comments
 (0)