Windows: add reproducible security diagnostics for storytold/pdfcraft#747 (#769)

Add packaging/windows/security-audit.ps1, a read-only maintainer helper that records a
release file's SHA-256, Authenticode status and, with an external YARA binary and rule,
every matched string identifier and offset. Document the procedure in docs/releasing.md
("Scanner detections").

No application, dependency, installer or network behaviour changes: the diff touches only
the helper and the release documentation.

Co-authored-by: Claude Haiku 5.5 <noreply@anthropic.com>
This commit is contained in:
cyfung1031
2026-10-10 15:39:44 -04:00
committed by GitHub
co-authored by Claude Haiku 5.5
parent d258764abc
commit ef63ba3680
2 changed files with 131 additions and 0 deletions
+41
View File
@@ -204,3 +204,44 @@ unsigned and the run shows a warning.
a PowerShell parse, xmllint (WiX, plist, MIME), `desktop-file-validate`, `appstreamcli validate`, and
the MSI icon-id check. The FreeBSD and Windows ARM64 workflows also exercise their packaging before a
release does.
## Scanner detections
Antivirus and reputation scanners sometimes flag a released file. Check the facts before you change
code or answer publicly. The first report was [issue #747](https://github.com/storytold/pdfcraft/issues/747),
a match of the `CobaltStrikeBeacon` family rule.
1. **Confirm the file is the release.** Compare its SHA-256 with `SHA256SUMS.txt` on the GitHub
Release. Only a file whose hash matches the release says anything about that release.
2. **Record the signature.** `packaging/windows/security-audit.ps1` prints the Authenticode status:
- `Valid`: the signature verifies.
- `NotSigned`: no signature, as in developer and test builds. Not evidence of compromise by itself.
- `HashMismatch`: the file changed after it was signed. Investigate.
- `NotTrusted` or `UnknownError`: a signature exists but did not validate on this machine. Compare
the signer and the hash with the release.
3. **Extract the payloads without running them.** Scan the executables inside the MSI and the
portable zip, not only the outer installer. `7z x -oDIR pdfcraft-<version>-windows-x64.msi`
extracts them. The payload names are WiX-internal, so tell the executables apart by their file
type. Don't install or run the MSI or the extracted files.
4. **Scan with YARA and keep every match.** Use your own copies of YARA and the rule. PdfCraft
bundles neither, and the helper never runs in the app, the installer or CI:
```powershell
pwsh packaging/windows/security-audit.ps1 -Path .\pdfcraft.exe, .\pdfcraft-cli.exe -YaraExe C:\tools\yara64.exe -YaraRule C:\rules\CobaltStrikeBeacon.yar
```
The output lists each matched identifier with its offset, and the SHA-256 of the rule file.
Record where the rule came from and its revision. For CAPEv2's `CobaltStrikeBeacon` rule, that is
the commit that last changed `data/yara/CAPE/CobaltStrikeBeacon.yar`.
5. **Find the condition branch.** Family rules usually have alternative branches, such as
`all of ($x*) or 2 of ($a*) or ...`. Copy the rule, make one rule per branch with only the strings
it uses, and scan again to see which branch fired.
6. **Interpret with care.** A match on generic repeated-byte patterns says much less than a match on
distinctive code or strings, and it does not show that the software belongs to the family. Rules
change too: CAPEv2 commit `9b599185` (2024-12-05) lengthened this rule's two repeated-byte patterns
from 4 to 16 bytes to reduce false positives, so an older rule revision can match files that the
current one does not. Don't alter PdfCraft's binaries to change a scanner's result. That changes
nothing about the software.
7. **Report.** To the scanner, send the file's SHA-256, the release URL, the rule name and revision,
and the matched identifiers and offsets. Report PdfCraft problems at
<https://github.com/storytold/pdfcraft/issues> with the same facts.