Architecture
HZSec is built around a local-first scanning model. This page explains what that means in practice, what data stays on your machine, and what the AI assistant actually sends when you ask it a question.
Local-first scanning
Every scan runs entirely inside the HZSec desktop process on your machine. No source files, no file paths, and no code content are transmitted anywhere during a scan. The scanner reads your files locally, evaluates them against local detection rules, and writes results to local storage.
You can verify this: run a scan while watching outbound network traffic in Charles, Proxyman, or macOS's Activity Monitor. You will see no outbound calls carrying source content while the scan runs.
The local-first guarantee applies to scanning. The AI assistant works differently — it reads your files to give you useful answers. See the AI assistant section below for exactly what gets sent.
What stays on your machine
All scan data is stored locally under ~/.shieldops/. Nothing in this directory is synced to HZSec servers.
~/.shieldops/
key.enc # encrypted Anthropic API key (AES-256-GCM)
key.salt # 32-byte random salt for key derivation
scan-history.json # scan results and score history
audit.log # append-only event log (NDJSON)
prefs.json # app settings and preferences
license.json # license key + 24h-cached validation
knowledge.db # local CVE database (SQLite)Finding details, severities, security scores over time.
Append-only record of scans, fixes, and key events.
Local SQLite copy of CISA KEV and NVD data.
AES-256-GCM encrypted before being written to disk.
CVE database
HZSec maintains a local SQLite database of known vulnerabilities. It is populated from two public sources:
Fetched directly from www.cisa.gov. The KEV catalog lists vulnerabilities with confirmed active exploitation — the highest-priority CVEs for most teams.
Fetched directly from the NVD public API at services.nvd.nist.gov. Includes CVSS scores, CWE mappings, and recently published CVEs.
Dependency CVE checks run against this local database. No package names or dependency lists are sent anywhere.
AI assistant — what gets sent
The AI assistant is designed to give you answers grounded in your actual code, not generic security advice. To do that, it reads the relevant files from your project and includes that content in the conversation with Claude.
What the assistant sends to Claude
Where it goes
Content is sent directly from your machine to api.anthropic.com using your own API key. HZSec servers never see it.
Content is sent to the HZSec backend (api.hzsec.io), which validates your license, meters usage, and forwards the request to Anthropic. The response is passed back unmodified.
Sending file content is intentional. An assistant that only sees finding metadata gives generic answers. One that can read your actual code gives specific, actionable answers. You are in control — you choose when to ask a question, and nothing is sent automatically during scanning.
API key storage
When you enter an Anthropic API key, HZSec encrypts it before writing to disk. The key is never stored in plaintext.
On the Pro tier with a managed key, no API key is stored on your device at all.
Audit log
HZSec maintains an append-only NDJSON log at ~/.shieldops/audit.log. Every significant event is recorded — scans, applied fixes, API key changes, monitor start/stop. Past entries cannot be modified; clearing the log itself creates a new entry recording the clear.
The log is readable from the desktop app (Reports view) and exportable as JSON or PDF. SeeCompliance for export details.