Linux port - #14
Open
jo3rg wants to merge 4 commits into
Open
Conversation
added 4 commits
June 4, 2026 13:57
Platform-specific changes:
* electron/main.js: gate macOS-only BrowserWindow options
(titleBarStyle: hiddenInset, trafficLightPosition, vibrancy) behind
process.platform === 'darwin'. Non-mac builds get a clean window with
the platform's standard chrome.
* electron/menu.js: split the App menu (services/hide/hideOthers/unhide)
per platform. On macOS the first menu is the application menu; on
Linux/Windows, About/Quit surface inside the File menu. Window > 'front'
(macOS-only behaviour) is also gated.
* electron/analyzers/sigma/evtx-scanner/binary-manager.js: the TLS error
message now reports the user-data path via app.getPath('userData')
instead of hard-coding '~/Library/Application Support/...', so analysts
on Linux aren't told to look in a Mac folder.
* electron/updater.js: reword the 'not configured' message so it doesn't
read as macOS-only.
* electron-builder.config.cjs: add a linux target — AppImage + deb for
x64/arm64. electron-builder's linux.icon must be a single PNG whose
filename encodes the size (WxH), so we ship 512x512.png and 256x256.png
generated from the existing icon.svg.
* build.sh: rewrite as a host-aware wrapper — the install hints, the
prerequisite check, and the menu choices now match whatever OS the
script is running on (Darwin/Linux/MINGW). The original was macOS-only.
* README.md: add Linux build commands and prerequisites; description no
longer says 'macOS' exclusively.
* assets/256x256.png, assets/512x512.png: Linux/Deb AppImage icons
generated from assets/icon.svg via rsvg-convert. Existing icon.icns
still drives the mac target.
Two toolchain changes required to get npm install / @electron/rebuild
working on Node 26 (CachyOS / Arch and other 2025+ distros ship Node 24+
by default):
1. better-sqlite3 ^11.7.0 -> ^12.4.1
11.7.0 uses V8 APIs that were removed in V8 13.x (GetPrototype was
renamed GetPrototypeV2, PropertyCallbackInfo lost the 'This' member,
v8::Context no longer exposes GetIsolate). 12.x supports V8 13+ and
builds cleanly against the V8 headers shipped with Node 24+ and
Electron 33+. The override forces the new version into the nested
@ts-evtx/messages dep tree (where 11.7.0 was previously broken too).
2. yargs pinned to 17.5.1 (overrides), plus patches/yargs+17.5.1.patch
17.5.1 and 17.7.2 both declare 'type': 'module' in package.json while
shipping a CJS entry file (yargs/yargs) with no .cjs extension. Under
Node 26's strict ESM detection the entry is loaded as ESM and the
top-level require('./build/index.cjs') throws. The patch removes
'type': 'module' from yargs' package.json; the rest of yargs' dual
ESM/CJS export map already prefers CJS for require(), so the entry
file is loaded correctly. Affects @electron/rebuild's CLI startup.
3. package.json author -> { name, email }
electron-builder's deb target needs a maintainer email; the
plain-string form ('DFIR Community') is rejected.
The macOS-only marketing copy was misleading after the Linux port.
This pass rewrites the user-visible strings and the now-inaccurate
documentation without touching the historical changelog.
UI strings (App.jsx, InlineModals.jsx, irflow-hero-graphic.jsx):
'DFIR Timeline Analysis for macOS' -> 'DFIR Timeline Analysis'
(the home-screen subtitle no longer claims a single platform)
Site metadata (config.mjs, index.md):
'High-performance DFIR timeline analysis tool for macOS' ->
'High-performance DFIR timeline analysis for macOS, Linux, and Windows'
operatingSystem: 'macOS' -> 'macOS, Linux, Windows'
Installation page (docs/getting-started/installation.md):
Full rewrite as a multi-OS page with a per-platform section for
macOS DMG, Linux AppImage + deb, and a 'Windows (planned)' stub.
Adds the FUSE 2 note for AppImages on modern distros.
Build-from-source commands now match the cross-platform fork
(dist:linux / dist:appimage / dist:deb in addition to dist:universal).
FAQ (docs/reference/faq.md):
Replaces the now-wrong 'Why is IRFlow Timeline macOS only?' Q
with 'Which platforms does IRFlow Timeline support?' listing
macOS / Linux / Windows-planned.
Feature-comparison line updated to mention Linux alongside macOS.
Roadmap (docs/about/roadmap.md):
'Windows and Linux builds to make IRFlow Timeline available
beyond macOS' -> 'Windows installer (planned); Linux shipped in
v1.0.6 via the multi-OS fork' with a link to the fork.
Platforms section (docs/features/virtual-grid.md):
'Windows is fully enabled today; Linux, macOS, and Cloud list
upcoming analyzers as disabled menu placeholders until those
platforms ship in a future release' -> makes explicit that the
APP runs on Linux and macOS; only the per-OS analyzers are still
in development. The 'macOS menu bar' references are generalized
to 'native menu' (top of screen on macOS, in-window on Linux/Windows).
Preferences page (docs/reference/preferences.md):
'macOS application menu (Tools)' -> 'Native menu (Tools)' with
a sentence explaining where the menu lives on each platform.
Other tweaks:
- docs/about/credits.md: electron-builder credit now mentions
AppImage/deb alongside DMG.
- docs/dfir-tips/building-final-report.md: Generate Report
shortcut generalized to 'Cmd+Shift+R / Ctrl+Shift+R' (the
Ctrl binding works on Linux/Windows automatically).
- docs/index.md: target-audience bullet and tagline updated to
mention macOS and Linux hosts (Windows still 'planned').
Docs build + tests verified: docs:build clean, vite build clean,
643/643 tests pass.
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
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.
Cross-platform support: add Linux build, make the codebase portable
Why
irflow-timelineis described everywhere in the README, the docs, and the UIas "a native macOS application for DFIR timeline analysis". That's accurate
historically, but the codebase is already 95% cross-platform — the few
process.platform === "darwin"paths inelectron/main.js, the macOS-onlyroles in
electron/menu.js, and the hard-coded~/Library/...errormessage in the Sigma hayabusa binary manager are the only things keeping
it from running on Linux.
This PR:
npm run dist:linuxpipeline that produces an AppImage anda
.debfor x86_64 + arm64."Why is IRFlow Timeline macOS only?" question, the Roadmap section
promising a Linux build, etc.).
End-to-end verified on CachyOS / Arch Linux x86_64 with Node 26.1.0:
./node_modules/.bin/electron .) launches and IPC worksnpm run build:renderer) is cleannpx electron-builder --linux AppImageproduces a working 176 MB AppImagenpx @electron/rebuild -f -w better-sqlite3succeeds(I'm submitting this from the fork
jo3rg/irflow-timeline-multiosbecausethe multi-OS work and the upstream rebrand are best reviewed together.)
What changed
1. Code port (no behaviour change on macOS)
electron/main.js:titleBarStyle: "hiddenInset",trafficLightPosition, andvibrancy: "under-window"increateWindoware now gated behindprocess.platform === "darwin".Non-mac builds get a clean window with the platform's standard chrome.
The
window-all-closedhandler was already correctly gated.electron/menu.js: the App menu (with macOS-only rolesservices,hide,hideOthers,unhide) is now built per-platform. On macOS thefirst menu is the application menu (unchanged); on Linux/Windows,
About and Quit surface inside the File menu instead. The macOS-only
role: "front"in the Window menu is also gated.electron/analyzers/sigma/evtx-scanner/binary-manager.js: theTLS-inspection error message no longer tells the user to drop the
manual Hayabusa binary at
~/Library/Application Support/...(a macOSpath). It now uses
app.getPath("userData")and adds the.exeextension on Windows. The rest of the file (Hayabusa download,
hayabusaAssetPatternforlinux→lin-x64-gnu/lin-aarch64-gnu)was already cross-platform.
electron/updater.js: the "Updates Not Configured" dialog textused to say "publish signed macOS builds with a zip target...".
Reworded to be platform-neutral (mentions mac zip, win nupkg, linux
AppImage).
2. Linux packaging (new)
electron-builder.config.cjs: added alinux:block(
{ target: ["AppImage", "deb"], arch: ["x64", "arm64"] },executableName: "irflow-timeline", etc.). The existingmac:block isunchanged. The
package.jsonauthorfield was promoted to{ name, email }so the deb target has a maintainer string (debpackaging rejects the plain-string form).
build.sh: rewritten as a host-aware wrapper. The install hints,the prerequisite check, and the menu choices now match whatever OS the
script is running on (Darwin/Linux/MinGW). The original was macOS-only.
package.json: addeddist:linux,dist:appimage,dist:debscripts. Description field updated to "for macOS, Linux, and Windows".
assets/256x256.pngandassets/512x512.png: generated fromassets/icon.svgviarsvg-convert. electron-builder'slinux.iconis a single PNG whose filename must encode the size (
WxH.png).README.md: added Linux build commands and prereqs; descriptionno longer says "macOS" exclusively. The macOS section is unchanged.
3. UI + docs rebrand
User-visible strings:
src/App.jsxandsrc/components/InlineModals.jsxhad the home-screen subtitle "DFIR Timeline Analysis for macOS". Removed
the "for macOS" qualifier. Same fix in
docs/public/irflow-hero-graphic.jsx.docs/.vitepress/config.mjs+docs/index.md: site descriptionand og:description / twitter:description updated to mention macOS,
Linux, and Windows.
operatingSystem: 'macOS'→'macOS, Linux, Windows'.docs/getting-started/installation.md: full rewrite as amulti-OS page. macOS DMG, Linux AppImage +
.deb, and a"Windows (planned)" stub. Adds the FUSE 2 note for AppImages on
modern distros that ship fuse3 only.
docs/reference/faq.md: replaced "Why is IRFlow Timeline macOSonly?" with "Which platforms does IRFlow Timeline support?". The
feature-comparison line now mentions Linux alongside macOS.
docs/about/roadmap.md: "Windows and Linux builds" was theplanned section. Updated to note that Linux shipped in v1.0.6 via
this fork; Windows is still planned.
docs/features/virtual-grid.md(Platforms section): the old textsaid "Windows is fully enabled today; Linux, macOS, and Cloud list
upcoming analyzers as disabled menu placeholders until those
platforms ship in a future release." Reworded to make it explicit
that the app itself runs on Linux and macOS — only the per-OS
analyzers are still in development. Generalised "macOS menu bar"
references to "native menu" (top of screen on macOS, in-window on
Linux/Windows).
docs/reference/preferences.md: "macOS application menu (Tools)"→ "Native menu (Tools)" with an explanation of where it lives per
platform.
docs/about/credits.md: electron-builder credit now mentionsAppImage/deb alongside DMG.
docs/dfir-tips/building-final-report.md: "macOS File →Generate Report…" → "File → Generate Report… in the native menu,
Cmd+Shift+R/Ctrl+Shift+R".docs/index.md: tagline and "Incident Responders" bulletupdated to reflect multi-OS host support.
The historical
CHANGELOG.mdanddocs/about/changelog.mdareintentionally not rewritten — they describe what shipped at each
version, and that's still accurate.
4. Toolchain bumps required to install/build on Node 24+
The fork uses Node 26.1.0, which is what CachyOS / Arch and most
up-to-date Linux distros ship in 2026. The original
package.jsontargeted older toolchains and wouldn't build:
better-sqlite3: ^11.7.0→^12.4.1: 11.7.0 uses V8 APIsthat were removed in V8 13.x (
GetPrototypewas renamedGetPrototypeV2;PropertyCallbackInfolost theThismember;v8::Contextno longer exposesGetIsolate). 12.x builds cleanlyagainst the V8 headers shipped with Node 24+ and Electron 33+.
yargspinned to17.5.1viaoverrides+patches/yargs+17.5.1.patch:17.5.1 and 17.7.2 both declare
"type": "module"inpackage.jsonwhile shipping a CJS entry file (
yargs/yargs) with no.cjsextension. Under Node 26's strict ESM detection the entry is loaded
as ESM and the top-level
require('./build/index.cjs')throws. Thepatch removes
"type": "module"from yargs'package.json; therest of yargs' dual ESM/CJS export map already prefers CJS for
require(), so the entry file loads correctly. This affects@electron/rebuild's CLI startup.Both changes are additive — they don't change the public API or
require any user-visible config tweaks. Anyone on an older Node (18-22)
can keep using the old
better-sqlite3@11.x; the new version stillworks there.
Test plan
npm installsucceeds on Node 26.1.0 (CachyOS)npx @electron/rebuild -f -w better-sqlite3succeedsnpm run build:renderer(vite) is clean./node_modules/.bin/electron .launches the dev app, IPChandlers respond, file dialog round-trips
npx electron-builder --linux --dirproducesrelease/linux-unpacked/irflow-timelinenpx electron-builder --linux AppImageproduces a 176 MBrelease/IRFlow-Timeline-1.0.6-x86_64.AppImage; running theinner AppRun starts the app
npm test: 643 pass / 0 fail / 34 skipped (no regressions)npm run docs:buildis cleanbash scripts/bundle-hayabusa.sh) produces aLinux x86_64 binary
bash scripts/bundle-bmc-tools.sh) worksThe deb target fails on CachyOS specifically because the system
ships glibc 2.36 (no
libcrypt.so.1); that's a CachyOS environmentquirk, not a port issue.
sudo pacman -S libxcrypt-compatfixes iton Arch derivatives. Ubuntu / Debian ship
libcrypt.so.1natively,so the deb target works out of the box there.
The AppImage also needs
libfuse2to mount directly on hosts thatship
fuse3only (Arch / CachyOS). The--appimage-extractfallbackis documented in the installation page.
Out of scope (for follow-up PRs)
already Windows-friendly (the
process.platform !== "darwin"pathsin
main.jsand the Linux/Windows menu branch inmenu.jsbothapply on Windows). The remaining work is a Windows CI workflow,
Windows-shaped fpm/NSIS tweaks, and a few shell-quoting fixes in
scripts/bundle-bmc-tools.sh..github/workflows/release-windows.yml)parallel to the existing
release-macos.yml.src/components/MenuBar.jsxstill show the plannedartifact analyzers as disabled stubs. Those features are independent
of the platform-port work and should be tracked separately.