Verify downloads
Every njMule release comes with what you need to check a download before you install it: a list of SHA-256 checksums, a signature of that list, an attestation of where each file was built, and a software bill of materials. Checking takes a minute and tells you that the file is complete and is the one the njMule project built.
What a release holds
Besides the packages, each release has these files; those of njMule 0.3.1 are:
| File (njMule 0.3.1) | What it is |
|---|---|
SHA256SUMS | SHA-256 checksums of every file |
SHA256SUMS.minisig | minisign signature of the checksums |
njmule-0.3.1-sbom.cdx.json | Software bill of materials (CycloneDX) |
All of them, with what each is for:
| File | What it is |
|---|---|
SHA256SUMS | the SHA-256 checksum of every package and of the files below, but the signatures |
SHA256SUMS.minisig | the minisign signature of SHA256SUMS |
njmule-<version>-sbom.cdx.json | the software bill of materials, in CycloneDX format |
njmule-update.json, njmule-update.json.minisig | what njMule's update check reads, signed with the same key |
The packages and these files are built by the project's release workflow on GitHub, which also attests where each of them was built.
1. Check the checksum
Put SHA256SUMS in the folder of your download, then:
- Windows
- macOS
- Linux
In PowerShell, for the file you downloaded:
$file = "njmule-<version>-windows-x64.msi"
$line = Select-String -Path SHA256SUMS -SimpleMatch $file
$expected = $line.Line.Split(" ")[0]
(Get-FileHash $file -Algorithm SHA256).Hash -eq $expected
True means the file is intact.
grep njmule-<version>-macos-arm64.dmg SHA256SUMS | shasum -a 256 -c -
OK after the file name means the file is intact.
sha256sum --check --ignore-missing SHA256SUMS
OK after each file you downloaded means it is intact; the files you did not download are skipped.
A checksum alone shows that the file is complete. The signature below shows that the list of checksums comes from the njMule project.
2. Check the signature
SHA256SUMS is signed with minisign, which runs on
Windows, macOS and Linux. Download SHA256SUMS.minisig into the same folder, then:
minisign -Vm SHA256SUMS -P RWQqpSb9M7CwntTJXDrwmcHlrGiA5i1y3EWMX7N2N9yWQMrO+BEz0i38
minisign says that the signature is verified and prints its trusted comment, which names the
version: njmule <version> SHA256SUMS. Any other answer means the list was changed or signed with
another key: do not install the files.
The key is the one njMule's own update check trusts. It is the first key in
keys.pub,
which every njMule carries:
| Key | Id | Use |
|---|---|---|
RWQqpSb9M7CwntTJXDrwmcHlrGiA5i1y3EWMX7N2N9yWQMrO+BEz0i38 | 9EB0B033FD26A52A | signs the releases |
RWRQGbT669VRjvKAg5AZBvXzoQ0/80MkM2vc+0T2i/7IG56OCtkgYis5 | 8E51D5EBFAB41950 | standby key |
Should the signing key ever be lost or leaked, releases are signed with the standby key that
follows it in keys.pub; njMule's update check already trusts both.
3. Check where it was built
GitHub attests, for every file of a release, that the project's release workflow built it from the repository. Check it with the GitHub CLI, signed in to GitHub:
gh attestation verify njmule-<version>-windows-x64.msi --repo njMule/njMule
To require the release workflow itself, add
--signer-workflow njMule/njMule/.github/workflows/release.yml.
VirusTotal
The release workflow sends every package to VirusTotal, where dozens
of antivirus engines scan it, and the notes of the release link each report. VirusTotal finds a
file by its SHA-256, the same as in SHA256SUMS, so you can also look your download up there by its
checksum.
An engine or two that judge by heuristics may flag a new program that is not code-signed yet, as njMule's executables are not. The checks above tell you whether the file is the one the project built.
The Docker image
The image ghcr.io/njmule/njmule is not one of the release files: it is built by the same release
workflow and pushed to the GitHub Container Registry with a provenance attestation and an SBOM of
its own, which Docker can show:
docker buildx imagetools inspect ghcr.io/njmule/njmule:<version> --format "{{ json .Provenance }}"
The software bill of materials
njmule-<version>-sbom.cdx.json lists the libraries njMule is built from, with their versions, in
the CycloneDX format. Tools that read it, such as OWASP Dependency-Track,
can check them against the known vulnerabilities.
If a check fails
Do not install the file. Download it again from the releases page and check it once more. If it still fails, tell the project as described in Security.