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.