BoltClam/README.md

BoltClam

BoltClam is a Windows desktop front-end for ClamAV, built with PyQt6 and signed in with a Bolt account. It scans every user's home or the full disk, quarantines or deletes what ClamAV finds, watches browser downloads, and receives update notifications from the private Gitea release feed.

What it does

• Homepage — a live protection summary: a shell gauge for engine, definitions, real-time protection and system firewall; security concerns; network details; recent detections; the signed-in user and Bolt plan.
• Scan & results — user-home or full-disk scans, live progress, scan history, per-detection actions, and a quarantine manager with restore.
• About & updates — app version, account and subscription, ClamAV version/definitions, release notes, beta/release channels, and checksum-verified downloads.
• Settings — update channel, ClamAV install location, extra clamscan options, real-time protection, automatic response, logging/debug, and opt-in diagnostics upload to Bolt.
• Browser download protection — watches the configured download folder of Chrome, Edge, Brave, Firefox, Vivaldi and Opera (plus every readable user's Downloads folder), waits for the file to settle, holds it with an exclusive Windows handle while ClamAV scans a copy, then quarantines or deletes it according to the setting.
• Bolt sign-in — opens a Bolt-hosted sign-in page in the default browser, receives a one-time code on a loopback listener, and exchanges it through PKCE for an ordinary bolt_live_... API key. The key is stored with Windows DPAPI; the password is never seen or stored by BoltClam.

Requirements

• Windows 10 or 11, x64.
• ClamAV for Windows installed separately. BoltClam does not bundle ClamAV binaries.
• A Bolt account (the same account used by the iOS/Android/Boltville clients).
• Internet access for sign-in, updates, and the first signature download.
• Administrator rights are optional but improve coverage of other users' profiles and protected files.

Install

Portable build

1. Download BoltClam-1.0.0-windows-x64-portable.zip and extract the whole folder (not just BoltClam.exe).
2. Run BoltClam.exe.
3. Sign in with your Bolt account in the browser.
4. Install ClamAV, open Settings → ClamAV engine, choose clamscan.exe (or use Auto-detect), and click Update definitions.
5. Run a scan from Scan & results.

The portable build is assembled by packaging/build_portable_windows.py from official Python Embeddable, PyQt6 wheels, and the tiny packaging/launcher.c bootstrap. It is not signed; Windows SmartScreen may warn about an unknown publisher. Compare the SHA-256 in SHA256SUMS.txt with the release.

Installer / PyInstaller

On a Windows build machine with Python 3.11 x64:

.\build_windows.ps1

This creates a one-folder build under dist\BoltClam\, a zip, and — when Inno Setup 6 is installed — dist\BoltClam-1.0.0-Setup.exe. Use .\build_windows.ps1 -OneFile for a single-file BoltClam.exe. build_windows.bat is a double-click wrapper.

Updates

Release notifications are read from:

https://git.themajesticnetwork.com/TheMajesticNetwork/BoltClam

BoltClam calls the Bolt API (/boltclam/updates) rather than the Gitea API directly, so the Gitea token stays server-side. The API normalizes releases, filters them by channel, and proxies asset downloads:

• Release channel: stable releases only.
• Beta channel: prereleases and stable releases.
• Assets are downloaded through the API with the user's Bolt key.
• If the release publishes SHA256SUMS.txt, the downloaded installer/zip is verified before it is offered for installation.

The Gitea repo is currently public and starts empty. The first release is created by pushing a v* tag once a Windows build runner is available (see .gitea/workflows/windows-release.yml) or by running build_windows.ps1 on Windows and uploading the assets with packaging/publish_release.ps1.

Server API

The BoltClam client uses the desk API at https://api.themajesticnetwork.com by default:

Endpoint	Purpose
GET /desk/auth/boltclam/start	BoltClam-branded browser sign-in page; validates loopback redirect + PKCE.
POST /desk/auth/boltclam/login	Email/password form handler; returns a one-time code to the app.
GET /desk/auth/oauth/{google|discord}/start	Existing provider flow, reused by the page's OAuth buttons.
POST /desk/auth/oauth/exchange	Existing PKCE exchange; mints the bolt_live_... key.
GET /boltclam/account	User, username/email, plan/subscription, balance.
GET /boltclam/updates?channel=release|beta	Normalized Gitea release feed.
GET /boltclam/updates/<release_id>/assets/<asset_id>	Authenticated asset proxy.
POST /boltclam/logs	Opt-in diagnostics zip upload.
GET /boltclam/admin/logs	Owner-only log listing (master desk key).

The server implementation lives in /home/themajesticmagician/Documents/Server/tmn-api/ai/boltclam_api.py (plus the small registration in ai/desk_api.py and the boltclam client name in ai/desk_auth.py). See docs/BOLTCLAM.md in that repository for deployment notes.

Security and privacy

• The Bolt password is sent only to the Bolt-hosted sign-in page/API. BoltClam receives a device-scoped API key, stored with Windows DPAPI.
• Signing out revokes only this PC's key.
• No API key is written to settings or diagnostics.
• Diagnostics upload is off by default. When enabled and explicitly sent, the zip contains app logs, settings, scan/quarantine summaries, a system summary and the account email. Tokens and passwords are redacted, emails in logs are redacted, and user-profile path prefixes become %USERPROFILE%. File contents are never included.
• Quarantine files are renamed to .quarantine, made read-only/hidden where possible, and recorded with SHA-256 plus a JSON sidecar.
• ClamAV extra options that would delete or move files (--remove, --move, --copy) are refused; remediation stays in BoltClam so it is recorded and reversible.

Real-time protection is user-mode, not a kernel filter driver. Holding a file with dwShareMode = 0 makes Windows refuse other opens while ClamAV scans a copy, which is a strong speed bump, but it is not a guarantee against a kernel-level bypass. If another process already has the file open, BoltClam falls back to scanning a copy and records that in the event detail. Read docs/SECURITY.md before relying on it as the only anti-malware layer.

Development

python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt
.venv/bin/pip install -e .
.venv/bin/python -m boltclam
QT_QPA_PLATFORM=offscreen .venv/bin/python -m pytest tests -q

The app reads BOLTCLAM_API_URL to override the API base (useful for a local desk API). Tests redirect config/data with BOLTCLAM_CONFIG_DIR and BOLTCLAM_DATA_DIR; never point those at a real user profile.

Repository

BoltClam/
├── src/boltclam/          application, services and PyQt pages
├── tests/                 unit and offscreen UI tests
├── resources/             icon, stylesheet rasters and OFL fonts
├── packaging/             Windows portable builder, launcher, release helper
├── installer/             Inno Setup script
├── build_windows.ps1      PyInstaller + installer build on Windows
├── BoltClam.spec          PyInstaller definition
└── .gitea/workflows/      Windows release workflow

Push / release

The remote is already configured:

git remote -v
# origin  https://git.themajesticnetwork.com/TheMajesticNetwork/BoltClam.git

Push the initial commit (Git will ask for your Gitea credentials/token):

git push -u origin main
git push origin v1.0.0

Pushing the tag triggers the Windows release workflow if the repository has a Windows Actions runner and a GITEA_TOKEN secret. Without such a runner, build on a Windows PC with build_windows.ps1 and upload the artifacts with packaging/publish_release.ps1.

Licensing

BoltClam is internal software for The Majestic Network; no public license is granted by this repository. PyQt6 is GPLv3-or-commercial: distributing BoltClam binaries under proprietary terms requires a commercial PyQt license, or GPLv3 compliance. ClamAV is GPLv2 and is installed separately, not bundled. Fonts are under the SIL Open Font License. See THIRD_PARTY_NOTICES.md.