kmarc

Bun-based TypeScript CLI for downloading DMARC reports from IMAP, storing raw messages, decompressed aggregate XML artifacts, normalized SQLite data, and producing terminal summaries, exports, and SPF-aware human-readable reports.

Setup

bun install

Configuration

kmarc uses two config layers in the config/ directory:

1. Application config: config/kmarc.json

Contains app-level settings: where to store local data, raw messages, extracted attachments, exports, the SQLite database, polling interval, and DMARC options. If config/kmarc.json is missing, sensible defaults are used. If it exists but is malformed, kmarc fails rather than silently falling back.

Example config/kmarc.json:

{
  "dataDir": "./data",
  "messagesDir": "./data/messages",
  "attachmentsDir": "./data/artifacts",
  "exportsDir": "./data/exports",
  "dbPath": "./data/kmarc.sqlite",
  "pollIntervalSeconds": 60,
  "dmarc": {
    "acceptedPsdDomains": []
  }
}

acceptedPsdDomains enables PSD DMARC discovery for explicitly trusted public suffix domains, per RFC 9091.

2. Host configs: config/domain.tld.json

On first startup kmarc creates a ./config folder if it does not exist.

Place one or more host JSON files next to config/kmarc.json, named after the remote domain, for example config/example.com.json. Each file represents a mailbox source. The source name defaults to the filename without .json, so name is optional.

Host object:

{
  "host": "mail.example.com",
  "port": 993,
  "secure": true,
  "user": "postmaster@example.com",
  "pass": "replace-me",
  "mailbox": "INBOX",
  "remoteDelete": true
}

• remoteDelete (optional, default false): automatically delete successfully-imported DMARC messages from the remote mailbox after processing.
• Runtime flags override this setting only for the current execution: --delete-remote forces deletion, --keep-remote forces mail retention.

Commands

bun run src/cli.ts help
bun run sync
bun run sync --delete-remote
bun run sync --keep-remote
bun run watch
bun run summary
bun run report
bun run export --format csv

Optional host override for sync/watch:

bun run src/cli.ts sync --host ./config/example.com.json
bun run src/cli.ts sync --delete-remote --host ./config/example.com.json
bun run src/cli.ts sync --keep-remote --host ./config/example.com.json

Reports read from the local SQLite database:

bun run src/cli.ts report --domain example.com --output html --write ./data/exports/report.html

Exports are written to ./data/exports. Raw messages are stored under messagesDir; aggregate artifacts are stored as decompressed XML under attachmentsDir.

Single Binary

Build a standalone Windows executable with:

bun run build

On Windows, that produces dist/kmarc.exe with the application icon from assets/kmarc.ico. On Linux and macOS, it produces the native dist/kmarc executable for the current platform. The binary reads application settings from config/kmarc.json (or uses defaults), loads host configs from config/domain.tld.json, and processes them in filename order unless you pass --host with a single host config file for sync or watch.

Cross-platform release builds:

bun run build:linux
bun run build:windows
bun run build:macos
bun run build:all

build:macos emits both Apple Silicon and Intel binaries. Windows icon metadata is embedded only when the Windows build is run from Windows, matching Bun's platform constraint for Windows resources.

The compiled binary also supports:

./dist/kmarc help
./dist/kmarc --help
./dist/kmarc sync
./dist/kmarc sync --delete-remote --host ./config/example.com.json
./dist/kmarc sync --keep-remote --host ./config/example.com.json
./dist/kmarc report --domain example.com --output html --write ./report.html