BoltClam/docs/SECURITY.md

BoltClam security model

BoltClam is a signature-based second opinion, not a replacement for Windows Defender or a kernel-level endpoint protection platform. This file states exactly what the user-mode protections do, where they stop, and what the app stores.

Trust boundaries

• Bolt API (api.themajesticnetwork.com) is the only network service BoltClam talks to. It proxies Gitea release metadata and assets, so a Gitea token is never shipped to a desktop.
• ClamAV is a separate, user-installed executable (clamscan.exe / freshclam.exe). BoltClam runs it as the current user and parses its output. BoltClam does not load ClamAV DLLs into its own process.
• Windows is trusted for DPAPI, file handles, and security-center facts reported by PowerShell. If PowerShell or Defender cmdlets are unavailable, the UI says "not reported" rather than inventing a pass.
• Gitea is trusted for release metadata only. Downloads are either proxied through the Bolt API or checked against a release SHA-256 when a checksum asset exists.

Credentials

• Sign-in uses the existing desk API browser/PKCE flow. The password is entered on a Bolt-hosted page and is never sent to BoltClam.
• The resulting bolt_live_... API key is stored in %APPDATA%\BoltClam\credentials.dat encrypted with Windows DPAPI (current-user scope, with an app-specific entropy value).
• On non-Windows development hosts the credential store falls back to a mode-0600 local file and logs a warning. That fallback is for development only.
• A key is never written to settings.json, logs, or diagnostics bundles.
• Sign-out revokes only the key this PC used, then deletes the local copy.

Scan and remediation

• Scans run clamscan with --infected --verbose --stdout and explicit argument lists (no shell). Extra options come from the user's settings and are parsed; --remove, --move, and --copy are refused so every action goes through BoltClam's recorded quarantine/delete path.
• A detection is written to SQLite before remediation is attempted. If quarantine or delete fails, the record stays visible as failed instead of disappearing.
• Quarantine moves the original file into %LOCALAPPDATA%\BoltClam\quarantine, renames it to .quarantine, records its SHA-256 and original path, and writes a JSON sidecar. Restore refuses to overwrite an existing file. Delete is permanent and explicitly confirmed.
• The quarantine folder is user-writable. A malicious process already running as that user could tamper with it; strong tamper resistance would require a privileged service and kernel driver, which this app does not install.

Real-time download gate

BoltClam watches browser download folders and waits for a file's size and mtime to stop changing. It then:

1. opens the file with CreateFileW and dwShareMode = 0 (deny other opens) where possible;
2. copies it to a private temp path through that handle;
3. scans the copy with ClamAV while the original remains locked;
4. on a clean result, releases the lock;
5. on a detection, closes the lock and moves the file to quarantine (or deletes it if that setting was chosen).

This blocks ordinary CreateFile opens during the scan, including a double-click, which is the meaningful user-mode speed bump. It is not:

• a kernel minifilter, so a driver or a process using backup semantics can bypass it;
• a guarantee when another process already holds the file open — BoltClam reports "File was in use; scanned a copy" and still remediates afterward;
• protection for downloads made outside a watched browser download folder (curl, scripts, existing files, network shares);
• a replacement for Windows Defender's real-time engine.

The Notify only response leaves the detected file in place. Use Quarantine (the default) if the machine must not retain detected downloads. Files larger than BOLTCLAM_REALTIME_MAX_MB (default 1024 MiB) are reported and not scanned in real time.

Definitions and updates

• freshclam writes to BoltClam's own %LOCALAPPDATA%\BoltClam\clamav-db, avoiding a Program Files write. clamscan uses that database when present and otherwise falls back to the database beside the installed binary.
• The signed-in user can see definition age in the Homepage and Settings. "Fresh" means no older than seven days; older than 30 days is critical.
• Update downloads require a valid Bolt key. If the release includes SHA256SUMS.txt, the SHA-256 is verified before the installer is offered. Without a checksum asset the UI says so rather than claiming verification.
• Run installers only from the BoltClam Gitea releases page. The app itself does not silently replace its own executable.

Diagnostics

Uploading diagnostics is opt-in and explicit. The bundle contains:

• redacted app logs;
• settings (API key absent);
• scan/quarantine summaries and real-time event metadata (paths redacted to %USERPROFILE%);
• ClamAV and system summary;
• account email, so support can identify the upload.

It never contains file contents, browser history, passwords, API keys, or the DPAPI credential file. Logs cap size and rotate locally.

Reporting a problem

For a security issue in BoltClam or the BoltClam API, contact The Majestic Network directly rather than opening a public issue with exploit details. Include the app version, Windows version, and the relevant redacted log excerpt.