Document the SmartScreen prompt a downloaded installer raises - #224
Merged
Conversation
Starting the published 1.2.10 server setup showed the blue "Windows protected your PC" window, which no earlier build had ever produced. Nothing about the product or the signing changed: same certificate, same thumbprint, RFC3161 timestamp, and the diff of deploy/ between v1.2.7 and v1.2.10 does not touch the signing block. What changed is where the file came from. SmartScreen only evaluates files carrying a Mark of the Web, the downloaded copy has ZoneId=3 from release-assets.githubusercontent.com, and every installer run before it was built locally and carried no such stream. With a self-signed publisher there is no reputation to weigh, so the prompt is guaranteed from the first download onward. The repository half-explained this. SmartScreen appeared in seven places, always as "an UNSIGNED installer warns", which is misleading -- the signed one warns too. Mark of the Web, Zone.Identifier, Unblock-File and the Attachment Manager had no mention at all, so the one fact that resolves the surprise was missing: a downloaded release warns where the identical local build does not. deployment-guide.md gains the explanation and the order that matters -- compare the checksum and the publisher thumbprint FIRST, then dismiss the dialog -- plus the ZIP case, which nothing covered: Install-NodePilot.ps1 unpacks a downloaded archive and runs PowerShell out of it, and files extracted from a marked ZIP inherit the mark. README.md and the Build-Artifact parameter docs drop the "unsigned" framing. av-exclusions.md gets the boundary stated outright, because that was the actual question asked: it covers the virus scanner, SmartScreen is a separate reputation service and ignores exclusion lists. It also picks up np.exe and nodepilot-mcp.exe, shipped since 1.2.8 and never added -- with the note that neither client binary is Authenticode-signed, so the document's own "publisher before process before path" ranking cannot start at publisher here. The docs site carries the same content; its cross-reference anchors were verified against github-slugger rather than assumed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Was ausgelöst hat
Der manuelle Start des veröffentlichten
NodePilot-Server-Setup-1.2.10.exezeigte das blaue „Der Computer wurde durch Windows geschützt"-Fenster — bei keinem früheren Build je aufgetreten. Vermutet wurde ein Zusammenhang mit Defender-Ausnahmen oder eine Produktänderung. Beides trifft nicht zu:Zone.Identifierder geklickten Datei (~\Downloads\)ZoneId=3, Hostrelease-assets.githubusercontent.comout\unddeploy\server\out\SHA256SUMS.txt277EAB31…, RFC3161-Zeitstempel vorhandengit diff v1.2.7..v1.2.10 -- deploy/SmartScreen bewertet nur Dateien mit Mark of the Web. Es war der erste Start eines heruntergeladenen Releases; das selbstsignierte Zertifikat trägt keine Reputation, also ist der Dialog ab da garantiert.
Was die Doku bisher sagte — und was fehlte
„SmartScreen" kam an sieben Stellen vor, durchgehend als „ein unsigniertes Setup löst SmartScreen aus". Das ist irreführend: Das signierte warnt genauso. Mark of the Web,
Zone.Identifier,Unblock-File, Attachment Manager: repo-weit null Treffer. Damit fehlte genau die Information, die die Überraschung auflöst.Änderungen
docs/deployment-guide.md— neuer Abschnitt First run: the SmartScreen prompt: warum beim Download und nicht beim lokalen Build, der Nachweis überZone.Identifier, und die Reihenfolge, auf die es ankommt — erst Prüfsumme und Publisher-Thumbprint vergleichen, dann wegklicken. Dazu der bisher nirgends dokumentierte ZIP-Fall:Install-NodePilot.ps1entpackt ein heruntergeladenes Archiv und führt PowerShell daraus aus, und entpackte Dateien erben die Markierung.docs/av-exclusions.md— die Abgrenzung ausgesprochen, weil sie die eigentliche Frage war: Das Dokument adressiert den Virenscanner; SmartScreen ist ein getrennter Reputationsdienst und ignoriert Ausschlusslisten. Zusätzlichnp.exeundnodepilot-mcp.exenachgetragen — seit 1.2.8 ausgeliefert und nie eingepflegt, mit dem Hinweis, dass beide Client-Binaries nicht Authenticode-signiert sind und die dokumentierte Rangfolge „Publisher → Prozess → Pfad" dort deshalb nicht bei Publisher beginnen kann.README.md+Build-Artifact.ps1— „unsigned installer warns" ersetzt: Signieren beseitigt SmartScreen nicht.production.md,installation.md,desktop.md,av-exclusions.md) — derselbe Inhalt im kuratierten Korpus.deploy/README.md— Punkt in der Release-Anleitung: Der Absatz gehört in den Release-Body, damit er nicht bei jedem Release neu erfunden wird.Verifikation
deploy\Test-DeploymentTemplates.ps1→ Exit 0.npm run buildinsrc/nodepilot-docs-ui→ grün.github-sluggergeprüft statt geraten:Beim ersten Start: das blaue SmartScreen-Fenster→beim-ersten-start-das-blaue-smartscreen-fenster,First run: the SmartScreen prompt→first-run-the-smartscreen-prompt.Unblock-Fileentfernt den Stream, SHA-256 bleibt unverändert und deckt sich weiter mitSHA256SUMS.txt.Nicht Teil dieser Änderung
Kein OV/EV-Zertifikat — die einzige echte Abhilfe, aber eine Beschaffungsentscheidung. Am Signieren selbst nichts geändert;
/fd SHA256 /td SHA256 /trmit DigiCert-Zeitstempel vor der Prüfsummenbildung ist korrekt.