zeuslock-dlp-cli 0.2.0

package/README.md

@@ -0,0 +1,570 @@
+# ZeusLock CLI
+
+JavaScript CLI package for ZeusLock.
+
+## Requirements
+
+- Node.js 22.12 or newer
+- npm 10 or newer
+
+## Install
+
+Install the latest release:
+
+```bash
+npm install -g zeuslock-dlp-cli@latest
+```
+
+Verify the installed command:
+
+```bash
+zeuslock --version
+zeuslock --help
+```
+
+Update an existing install:
+
+```bash
+npm install -g zeuslock-dlp-cli@latest
+```
+
+Run without a global install:
+
+```bash
+npm exec --package zeuslock-dlp-cli@latest -- zeuslock status
+```
+
+## Local Development
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Run the CLI directly:
+
+```bash
+npm start -- --help
+npm start -- auth login --token zlu_your_cli_access_token
+npm start -- auth login --email admin@example.com
+npm start -- whoami
+npm start -- status
+npm start -- status --json
+npm start -- auth api-key set zl_your_org_api_key
+npm start -- scan ./README.md --json
+npm start -- anonymize ./dataset.txt --output dataset.safe.txt
+npm start -- hook install --force
+npm start -- deploy gpo-config --api-key zl_your_key_here --output zeuslock-deploy
+npm start -- deploy agent-verify --hostname CLIENT01
+npm start -- agents list
+npm start -- agents list --status offline --search linux
+npm start -- extensions status
+npm start -- incidents list --days 7
+npm start -- incidents stats
+npm start -- shadow-ai stats --days 7
+npm start -- shadow-ai tools --source endpoint --status shadow
+npm start -- mcp events --transport stdio --decision block
+npm start -- mcp servers
+npm start -- siem pull --api-key zl_your_key_here --limit 100
+npm start -- status --api-key zl_your_key_here --require-license
+npm start -- users list
+npm start -- users remove departing@example.com --yes
+npm start -- keys list --status active
+npm start -- keys create --name rotation-2026-08
+npm start -- keys revoke <key_id> --yes
+npm start -- tokens list --status active
+npm start -- tokens create --name work-laptop
+npm start -- tokens revoke <token_id> --yes
+npm start -- tokens purge <token_id> --yes
+npm start -- rules get --output zeuslock.rules.yaml
+npm start -- rules diff zeuslock.rules.yaml
+```
+
+Install it locally as the `zeuslock` command:
+
+```bash
+npm link
+zeuslock --help
+zeuslock auth login --token zlu_your_cli_access_token
+zeuslock auth login --email admin@example.com
+zeuslock whoami
+zeuslock --token zlu_your_cli_access_token whoami
+zeuslock status
+zeuslock auth api-key set zl_your_org_api_key
+zeuslock scan ./README.md
+zeuslock scan --stdin
+zeuslock anonymize ./dataset.txt --output dataset.safe.txt
+zeuslock hook install
+zeuslock deploy gpo-config --api-key zl_your_key_here --output zeuslock-deploy
+zeuslock deploy agent-verify --hostname CLIENT01
+zeuslock agents list --status online
+zeuslock agents revoke <agent_id> --yes
+zeuslock extensions status
+zeuslock incidents list --days 7
+zeuslock incidents export --days 7 --format csv --output incidents.csv
+zeuslock shadow-ai stats --days 30
+zeuslock shadow-ai tools --category chatbot --status shadow
+zeuslock shadow-ai users --days 7
+zeuslock mcp stats --days 30
+zeuslock mcp events --transport stdio --method tools/call
+zeuslock mcp servers
+zeuslock siem pull --api-key zl_your_key_here --severity high --format json
+zeuslock siem tail --api-key zl_your_key_here --category dlp
+zeuslock users list --role admin
+zeuslock users remove departing@example.com --yes
+zeuslock keys list --status active
+zeuslock keys create --name rotation-2026-08
+zeuslock keys revoke <key_id> --yes
+zeuslock tokens list --status active
+zeuslock tokens create --name work-laptop
+zeuslock tokens revoke <token_id> --yes
+zeuslock tokens purge <token_id> --yes
+zeuslock rules get --format json
+zeuslock rules diff zeuslock.rules.yaml
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+Check what would be published:
+
+```bash
+npm run pack:dry-run
+```
+
+## Configuration
+
+The CLI uses `https://api.zeuslock.ai` by default. Override the backend URL with:
+
+```bash
+export ZEUSLOCK_API_URL="https://api.zeuslock.ai"
+```
+
+Authenticate with a personal CLI access token generated from the dashboard CLI page:
+
+```bash
+zeuslock auth login --token zlu_your_cli_access_token
+zeuslock whoami
+```
+
+You can also pass a CLI token for one invocation:
+
+```bash
+zeuslock --token zlu_your_cli_access_token whoami
+```
+
+Or authenticate with the same email/password backend flow used by the dashboard:
+
+```bash
+zeuslock auth login --email admin@example.com
+zeuslock whoami
+```
+
+`auth login` prompts for the password when `--password` is not provided. User authentication is stored in a per-user config directory with restrictive filesystem permissions. The password is never stored.
+
+Personal CLI access tokens use the `zlu_` prefix, authenticate as `Authorization: Bearer`, and do not refresh. If a saved CLI token is expired, revoked, or invalid, generate a new token from the dashboard CLI page and run `zeuslock auth login --token ...` again.
+
+Clear saved user authentication with `zeuslock auth logout`. This does not clear a saved organization API key.
+
+For automation and tests, these inputs can also be supplied through environment variables:
+
+```bash
+export ZEUSLOCK_EMAIL="admin@example.com"
+export ZEUSLOCK_PASSWORD="..."
+export ZEUSLOCK_MFA_CODE="123456"
+export ZEUSLOCK_API_TOKEN="zlu_your_cli_access_token"
+export ZEUSLOCK_API_KEY="zl_your_org_api_key"
+export ZEUSLOCK_CONFIG_DIR="/secure/custom/path"
+```
+
+Bearer credential precedence for user-authenticated commands is:
+
+| Source | Priority | Notes |
+| --- | --- | --- |
+| `zeuslock --token zlu_... <command>` | 1 | One invocation only; must appear before the subcommand. |
+| `ZEUSLOCK_API_TOKEN` | 2 | Best for CI or ephemeral automation. |
+| Saved CLI token | 3 | Created by `zeuslock auth login --token zlu_...`; never refreshed. |
+| Saved email/password session | 4 | Created by `zeuslock auth login --email ...`; refreshes once on `401`. |
+
+`ZEUSLOCK_API_KEY` is an organization API key from the dashboard API Keys page. SIEM pull/tail, scan, anonymize, hooks, and license validation use it as `X-API-Key`; personal CLI tokens are not used for those machine-authenticated endpoints.
+
+You can also save the organization API key locally for scan, anonymize, hook, SIEM, and license checks:
+
+```bash
+zeuslock auth api-key set zl_your_org_api_key
+zeuslock auth api-key status
+zeuslock auth api-key clear
+```
+
+`zeuslock status` reports whether authentication is configured, checks backend `/healthz` and `/readyz`, and can validate license status when an API key is provided. It never prints token or API-key values.
+
+## Content Scanning, Hooks, And Anonymization
+
+These commands use the backend surfaces already used by the dashboard, extension, and desktop agent. The CLI does not carry local DLP rules.
+
+| Command | Purpose |
+| --- | --- |
+| `zeuslock scan <file\|dir>` | Upload content to `POST /api/v1/dlp/analyze` using the organization's active DLP policy. |
+| `zeuslock scan --stdin` | Analyze stdin text with the same DLP endpoint. |
+| `zeuslock anonymize <file>` | Send text to `POST /api/v1/anonymize` and print/write anonymized text. |
+| `zeuslock hook install` | Install a Git `pre-commit` hook that runs `zeuslock hook run`. |
+| `zeuslock hook run` | Scan staged Git files exactly as they will be committed. |
+
+Supported options and values:
+
+| Command | Option | Values |
+| --- | --- | --- |
+| `scan` | `--fail-on` | `alert`, `block`, `never`; default `block` |
+| `scan` | `--source`, `--platform`, `--hostname`, `--path`, `--user-email` | Metadata labels sent to the backend; defaults are `source=cli`, `platform=cli`, local hostname, and `/cli/<input>` |
+| `scan` | `--include-sensitive` | Includes backend anonymization maps in JSON output; hidden by default |
+| `scan` | `--api-key` | Organization API key; otherwise saved key or `ZEUSLOCK_API_KEY` |
+| `anonymize` | `--output` | Output file path; stdout by default |
+| `anonymize` | `--include-sensitive-map` | Includes original-to-masked substitutions in JSON output; hidden by default |
+| `hook install` | `--repo` | Git repository path; default current directory |
+| `hook install` | `--fail-on` | `alert` or `block`; default `alert` |
+| `hook install` | `--force` | Replace an existing `.git/hooks/pre-commit` |
+| `hook run` | `--fail-on` | `alert`, `block`, `never`; default `alert` |
+
+Hardcoded backend-parity values:
+
+| Value | Used by |
+| --- | --- |
+| 5 files per upload batch | Matches the backend DLP analyze default file limit. |
+| `source=cli` | Manual scan incidents. |
+| `source=git_pre_commit`, `platform=git`, `method=PRE_COMMIT` | Git hook scan incidents. |
+
+Skipped because the dashboard/backend do not expose them:
+
+| Skipped command/workflow | Reason |
+| --- | --- |
+| Local/offline scan | No dashboard/backend source-of-truth implementation. |
+| Rule override flags such as `--rule` or `--severity` on `scan` | Rules are controlled by dashboard Policies/Rules, not per CLI request. |
+| No-report/dry-run scan | `POST /api/v1/dlp/analyze` persists incidents on alert/block. |
+| PDF/image/Office anonymization | `/api/v1/anonymize` accepts text JSON only; file parsing belongs to scan. |
+
+## Fleet Deployment And Onboarding
+
+Deployment commands mirror only the dashboard Extension page and Agents deployment modal. They generate local artifacts from existing dashboard data and APIs; they do not change the backend.
+
+| Command | Purpose |
+| --- | --- |
+| `zeuslock deploy gpo-config` | Generate dashboard-supported extension GPO policy files and desktop-agent config files. |
+| `zeuslock deploy agent-verify` | Verify installed/enrolled/reachable state from `GET /api/agents`. |
+
+Supported filters and values:
+
+| Command | Option | Values |
+| --- | --- | --- |
+| `deploy gpo-config` | `--artifact` | `all`, `extension`, `agent`; default `all` |
+| `deploy gpo-config` | `--browser` | `all`, `chrome`, `edge`; default `all`; applies to extension artifacts |
+| `deploy gpo-config` | `--output` | Output directory; default `zeuslock-deploy` |
+| `deploy gpo-config` | `--api-key` | Full organization API key to embed in generated files |
+| `deploy gpo-config` | `--key-id` | Existing key id from `zeuslock keys list --show-secret`; requires a decryptable key from `GET /api/keys` |
+| `deploy gpo-config` | `--create-key-name` | Creates a new key with `POST /api/keys` and embeds the returned full key |
+| `deploy gpo-config` | `--json` | Prints generated artifact metadata without secret values |
+| `deploy agent-verify` | `--agent-id` | Exact agent id from `zeuslock agents list` |
+| `deploy agent-verify` | `--hostname` | Exact hostname, case-insensitive |
+| `deploy agent-verify` | `--platform` | `windows`, `macos`, `linux` |
+| `deploy agent-verify` | `--status` | `online`, `offline`, `any`; default `online` |
+| `deploy agent-verify` | `--json` | Prints verification metadata and matching agent rows |
+
+Generated artifacts:
+
+| Artifact | Generated when | Contents |
+| --- | --- | --- |
+| `extension/chrome-extension-forcelist.txt` | `--artifact all/extension`, Chrome | Dashboard extension force-install value. |
+| `extension/chrome-extension-settings.json` | `--artifact all/extension`, Chrome | Dashboard `ExtensionSettings` JSON. |
+| `extension/edge-extension-forcelist.txt` | `--artifact all/extension`, Edge | Dashboard extension force-install value. |
+| `extension/edge-extension-settings.json` | `--artifact all/extension`, Edge | Dashboard `ExtensionSettings` JSON. |
+| `agent/windows-agent-policy.reg` | `--artifact all/agent` | `HKLM\SOFTWARE\Policies\ZeusLock` values for `ServerUrl` and `LicenseKey`. |
+| `agent/agent-config.json` | `--artifact all/agent` | Agent config with `ServerUrl`, `LicenseKey`, `apiUrl`, and `apiKey`. |
+| `deployment-summary.json` | Always | Non-secret summary of org, selected key, requested options, generated files, and skipped items. |
+
+Hardcoded dashboard parity values:
+
+| Value | Used by |
+| --- | --- |
+| `hgooghpcnalhpjbemnnmdoabfjhchoip` | Published Chrome Web Store extension id. |
+| `https://clients2.google.com/service/update2/crx` | Chrome/Edge extension force-install update URL. |
+| `monitor_clipboard=true`, `monitor_ai_apps=true`, `show_notifications=true` | Extension configuration defaults from the dashboard. |
+| `business`, `enterprise` | Plans allowed to generate extension GPO artifacts, matching the dashboard gate. |
+| 5 minutes | Fallback online window when `GET /api/agents` does not include `is_online`. |
+
+Skipped because the dashboard/backend do not expose them:
+
+| Skipped command/workflow | Reason |
+| --- | --- |
+| Proxy `.reg` artifact | No dashboard UI or backend API exposes proxy registry policy values. |
+| Local post-GPO machine checks | No API exposes `gpresult`, registry, package, or service state from client machines. |
+| Dedicated agent verification endpoint | The backend has no dashboard-used `agent-verify` endpoint; verification uses `GET /api/agents`. |
+| Non-dashboard installer/platform artifact generation | The dashboard/backend expose only the documented extension policy and agent config/install guidance. |
+
+## Access Governance
+
+Access governance commands mirror the dashboard Users and API Keys pages. The dashboard/backend are the source of truth: the CLI only uses existing API behavior and applies filters locally when the API does not expose server-side filters.
+
+| Command | Purpose |
+| --- | --- |
+| `zeuslock users list` | List organization users from `GET /api/users`. |
+| `zeuslock users remove <user>` | Remove one user with `DELETE /api/users/{user_id}` after resolving `<user>` from `GET /api/users`. |
+| `zeuslock keys list` | List API keys from `GET /api/keys`. |
+| `zeuslock keys create --name <name>` | Create an API key with `POST /api/keys`. |
+| `zeuslock keys revoke <key_id>` | Revoke an active API key with `DELETE /api/keys/{key_id}`. |
+| `zeuslock tokens list` | List personal CLI access tokens from `GET /api/v1/cli-tokens`. |
+| `zeuslock tokens create --name <name>` | Create a CLI access token with `POST /api/v1/cli-tokens`. |
+| `zeuslock tokens revoke <token_id>` | Revoke a CLI access token with `DELETE /api/v1/cli-tokens/{token_id}`. |
+| `zeuslock tokens purge <token_id>` | Permanently delete an already-revoked CLI access token with `DELETE /api/v1/cli-tokens/{token_id}?purge=true`. |
+
+Supported filters and values:
+
+| Command | Option | Values |
+| --- | --- | --- |
+| `users list` | `--search` | Any text; searches email, role, status, and display name locally |
+| `users list` | `--role` | Values returned by `GET /api/users/roles`; typically `admin`, `user`, `viewer`, `viewer_user` depending on plan |
+| `users list` | `--json` | Prints totals, filters, available role values, and normalized user rows |
+| `users remove` | `<user>` | User id, `user_id`, or email from `users list` |
+| `users remove` | `--yes` | Skips the confirmation prompt |
+| `users remove` | `--json` | Prints the removal result |
+| `keys list` | `--status` | `all`, `active`, `revoked`; default `all` |
+| `keys list` | `--show-secret` | Shows returned full key values when the backend includes them; hidden by default |
+| `keys list` | `--json` | Prints totals, filters, and normalized key rows |
+| `keys create` | `--name` | Required key name |
+| `keys create` | `--json` | Prints the created key, including the returned full key |
+| `keys revoke` | `<key_id>` | API key id from `keys list` |
+| `keys revoke` | `--yes` | Skips the confirmation prompt |
+| `keys revoke` | `--json` | Prints the revoke result |
+| `tokens list` | `--status` | `all`, `active`, `revoked`, `expired`; default `all` |
+| `tokens list` | `--show-secret` | Shows returned full token values when the backend includes them; hidden by default |
+| `tokens list` | `--json` | Prints totals, filters, and normalized token rows |
+| `tokens create` | `--name` | Required token name, 1-255 chars |
+| `tokens create` | `--expires-in-days` | Optional integer from 1 to 365; backend default is 90 when omitted |
+| `tokens create` | `--json` | Prints the created token, including the returned full token |
+| `tokens revoke` | `<token_id>` | CLI token id from `tokens list` |
+| `tokens revoke` | `--yes` | Skips the confirmation prompt |
+| `tokens revoke` | `--json` | Prints the revoke result |
+| `tokens purge` | `<token_id>` | Already-revoked CLI token id from `tokens list` |
+| `tokens purge` | `--yes` | Skips the confirmation prompt |
+| `tokens purge` | `--json` | Prints the purge result |
+
+Hard-coded CLI safety behavior:
+
+| Area | Behavior |
+| --- | --- |
+| User removal | Refuses to remove the currently authenticated user. |
+| User removal | Refuses to remove the last active admin, matching the dashboard UI guard. |
+| API key listing | Full keys are hidden unless `--show-secret` is provided. |
+| API key revocation | Refuses already-revoked keys because the dashboard backend uses a second `DELETE` as permanent deletion. |
+| CLI token listing | Full tokens are hidden unless `--show-secret` is provided. |
+| CLI token purge | Refuses active tokens; revoke first, then purge. |
+
+Skipped because the dashboard/backend do not expose them:
+
+| Skipped command/workflow | Reason |
+| --- | --- |
+| `zeuslock users remove --file departures.csv` | No dashboard/backend bulk-remove endpoint. Script repeated single-user removals externally if needed. |
+| `zeuslock keys rotate` | No atomic rotation endpoint; use create, deploy the new key, then revoke the old key. |
+| `zeuslock keys delete` | Not part of the requested feature and easy to confuse with revoke. |
+| `zeuslock tokens rotate` | No atomic CLI-token rotation endpoint; create a new token, update callers, then revoke the old token. |
+| `zeuslock users invite` / bulk invite | Available in the dashboard, but outside the attached access-governance command list. |
+
+## Fleet Visibility
+
+Fleet visibility commands mirror the dashboard/backend agent and extension APIs.
+
+| Command | Purpose |
+| --- | --- |
+| `zeuslock agents list` | List desktop agents from `GET /api/agents`. |
+| `zeuslock agents revoke <agent_id>` | Revoke an agent with `DELETE /api/agents/{agent_id}`. |
+| `zeuslock extensions status` | Show active browser extensions from `GET /api/extensions`. |
+
+Supported filters and values:
+
+| Command | Option | Values |
+| --- | --- | --- |
+| `agents list` | `--status` | `all`, `online`, `offline`; default `all` |
+| `agents list` | `--search` | Any text; searches hostname and platform |
+| `agents list` | `--json` | Prints summary and normalized agent rows |
+| `agents revoke` | `--yes` | Skips the confirmation prompt |
+| `agents revoke` | `--json` | Prints the revoke result |
+| `extensions status` | `--json` | Prints summary and normalized extension rows |
+
+`agents list` fetches `GET /api/v1/agents/downloads` best-effort to mark rows with `update_available`, matching the dashboard update badge. It does not expose an outdated-only filter because the dashboard does not.
+
+`zeuslock report coverage` is not implemented because the dashboard/backend do not expose expected endpoint inventory, AD/Intune/MDM cross-reference data, or unprotected endpoint reporting.
+
+## Incidents
+
+The incidents commands mirror the dashboard and use the same authenticated backend APIs.
+
+| Command | Purpose |
+| --- | --- |
+| `zeuslock incidents list` | List incidents from `GET /api/incidents?days=N`. |
+| `zeuslock incidents stats` | Show incident statistics from `GET /api/stats?days=N`. |
+| `zeuslock incidents export` | Export dashboard-filtered incident data from `GET /api/incidents?days=N`. |
+
+Supported filters and values:
+
+| Command | Option | Values |
+| --- | --- | --- |
+| `incidents list` | `--days` | `7`, `30`, `90`; `90` requires Business or Enterprise |
+| `incidents list` | `--severity` | `critical`, `warning`; `warning` includes high, medium, and low |
+| `incidents list` | `--search` | Any text; searches user email, URL, and finding type |
+| `incidents list` | `--jailbreak` | Only incidents with a `jailbreak_attempt` finding |
+| `incidents stats` | `--days` | `1`, `7`, `30`, `365`; `365` requires Business or Enterprise |
+| `incidents export` | `--days` | `7`, `30`, `90`; default `30`; export requires Business or Enterprise |
+| `incidents export` | `--severity` | `critical`, `warning`; `warning` includes high, medium, and low |
+| `incidents export` | `--search` | Any text; searches user email, URL, and finding type |
+| `incidents export` | `--jailbreak` | Only incidents with a `jailbreak_attempt` finding |
+| `incidents export` | `--format` | `csv`, `json`; default `csv` |
+| `incidents export` | `--output` | Optional output file path; defaults to `incidents-<timestamp>.<format>` |
+
+`zeuslock incidents export` intentionally does not support arbitrary day values or `--from`/`--to`: the dashboard exposes only 7, 30, and 90-day windows. Server-side archived export history and `zeuslock report weekly` are not implemented because the dashboard does not expose those features.
+
+## Shadow AI And MCP Monitoring
+
+Shadow AI and MCP commands mirror the dashboard pages and use only existing dashboard read APIs. They first read `GET /api/org` and follow the same feature-flag behavior as the dashboard: Shadow AI is available only when `settings.shadow_ai_enabled` is true; MCP is available unless `settings.mcp_enabled` is explicitly false.
+
+| Command | Purpose |
+| --- | --- |
+| `zeuslock shadow-ai stats` | Show Shadow AI KPI totals from `GET /api/shadow-ai/stats`. |
+| `zeuslock shadow-ai tools` | List detected AI tools from `GET /api/shadow-ai/tools`. |
+| `zeuslock shadow-ai users` | List users with shadow-tool usage from `GET /api/shadow-ai/users`. |
+| `zeuslock mcp stats` | Show MCP KPI totals from `GET /api/v1/mcp/stats`. |
+| `zeuslock mcp events` | List sanitized MCP metadata events from `GET /api/v1/mcp/events`. |
+| `zeuslock mcp servers` | List discovered MCP server inventory from `GET /api/v1/mcp/servers`. |
+
+Supported filters and values:
+
+| Command | Option | Values |
+| --- | --- | --- |
+| `shadow-ai stats/tools` | `--days` | `7`, `30`, `90`; default `30` |
+| `shadow-ai stats/tools` | `--source` | `all`, `endpoint`, `browser`, `both`; default `all` |
+| `shadow-ai stats/tools` | `--status` | `all`, `sanctioned`, `shadow`; default `all` |
+| `shadow-ai stats/tools` | `--category` | `all`, `chatbot`, `coding_assistant`, `image_gen`, `agent`, `other`; default `all` |
+| `shadow-ai users` | `--days` | `7`, `30`, `90`; default `30` |
+| `mcp stats/events` | `--days` | `7`, `30`, `90`; default `30` |
+| `mcp events` | `--transport` | `all`, `http`, `sse`, `stdio`; default `all` |
+| `mcp events` | `--direction` | `all`, `client_to_server`, `server_to_client`; default `all` |
+| `mcp events` | `--decision` | `all`, `allow`, `alert`, `block`; default `all` |
+| `mcp events` | `--method` | Any backend MCP method string, for example `tools/call`; omitted means all |
+| `mcp events` | `--search` | Any text; searches server, tool, user, method, hostname, or path |
+| `mcp events` | `--cursor` | Opaque `next_cursor` from a previous `mcp events --json` response |
+| all Shadow AI/MCP commands | `--json` | Prints normalized JSON with filters and data |
+
+Hardcoded dashboard parity values:
+
+| Value | Used by |
+| --- | --- |
+| `limit=50` | `mcp events`, matching the dashboard page size |
+| `days=90` | `mcp servers`, matching the dashboard server inventory load |
+| `settings.shadow_ai_enabled` | Shadow AI feature gate; missing or false means disabled |
+| `settings.mcp_enabled !== false` | MCP feature gate; missing means enabled |
+| Metadata-only MCP rows | MCP event output; raw prompts/content are not exposed |
+
+Skipped because the dashboard/backend do not expose them:
+
+| Skipped command/workflow | Reason |
+| --- | --- |
+| Full user-to-all-tools matrix | Dashboard user table exposes user, distinct tool count, and most-used tool only. |
+| Dedicated Shadow AI or MCP export command | Dashboard export is client-side only; the backend has no export endpoint for these pages. Use `--json` for scriptable output. |
+| Raw MCP prompt/content inspection | Backend stores sanitized metadata and non-reversible content hashes only. |
+| Shadow AI policy mutation | The dashboard modal exposes policy changes, but the requested CLI surface only covers stats, tools, and users. |
+
+## SIEM Integration And Monitoring
+
+SIEM commands use the backend pull API shown on the dashboard SIEM page. Events are OCSF DLP events and are authenticated with an organization API key, not a dashboard user JWT.
+
+| Command | Purpose |
+| --- | --- |
+| `zeuslock siem pull` | Retrieve one page of SIEM events from `GET /api/v1/siem/events`. |
+| `zeuslock siem tail` | Poll `GET /api/v1/siem/events` continuously with a persisted cursor. |
+| `zeuslock status` | Check CLI context, backend health/readiness, and optional license validity. |
+
+Supported filters and values:
+
+| Command | Option | Values |
+| --- | --- | --- |
+| `siem pull` | `--api-key` | Organization API key; defaults to `ZEUSLOCK_API_KEY` |
+| `siem pull` | `--since` | Backend `next_cursor` string |
+| `siem pull` | `--from`, `--to` | Backend-parseable ISO date/time or epoch |
+| `siem pull` | `--days` | Positive integer; CLI converts to `start_time`; mutually exclusive with `--from` |
+| `siem pull` | `--category` | Generic backend category string; current dashboard SIEM events use `dlp` |
+| `siem pull` | `--severity` | `unknown`, `low`, `medium`, `high`, `critical`; backend treats this as minimum severity |
+| `siem pull` | `--limit` | `1` to `500`; backend default is `100` |
+| `siem pull` | `--format` | `jsonl`, `json`; default `jsonl` |
+| `siem tail` | `--api-key`, `--since`, `--category`, `--severity`, `--limit` | Same meaning as `siem pull` |
+| `siem tail` | `--interval` | Positive seconds; default `5` |
+| `siem tail` | `--cursor-name` | Any stable namespace; default `default` |
+| `siem tail` | `--reset-cursor` | Ignore the saved cursor for this run |
+| `status` | `--api-key` | Organization API key; defaults to `ZEUSLOCK_API_KEY` |
+| `status` | `--require-license` | Exit nonzero unless health, readiness, and license validation pass |
+| `status` | `--json` | Print machine-readable output |
+
+Hardcoded values:
+
+| Value | Used by |
+| --- | --- |
+| `/api/v1/siem/events` | SIEM pull/tail event source |
+| `X-API-Key` | SIEM and license API-key authentication header |
+| `500` | Maximum SIEM page size accepted by the backend |
+| `100` | Backend default SIEM page size when `--limit` is omitted |
+| `5 seconds` | Default `siem tail` poll interval |
+| `siem-cursors.json` | Local cursor store under the CLI config directory |
+| `/healthz` and `/readyz` | Backend health and readiness checks |
+| `/api/v1/validate-license` | API-key license validation endpoint |
+
+Skipped because the dashboard/backend do not expose them:
+
+| Skipped command/workflow | Reason |
+| --- | --- |
+| QRadar-specific destination setup | Dashboard/backend destinations are Splunk HEC, Microsoft Sentinel, and Elastic Bulk API only. |
+| True streaming over SSE/WebSocket | Backend exposes pull pagination only, so `tail` is implemented as polling. |
+| Backend-side `days` query parameter | Backend supports time filters, so CLI `--days` is converted to `start_time`. |
+
+## DLP Rules Policy-as-Code
+
+The rules commands mirror the dashboard's current Policies page and existing backend APIs. They are read-only: export and diff are implemented in the CLI from existing read endpoints, and no backend import/apply endpoint is called.
+
+| Command | Purpose |
+| --- | --- |
+| `zeuslock rules get` | Export policy/rules state as YAML or JSON. |
+| `zeuslock rules diff [file]` | Compare a local YAML/JSON rules file against live dashboard/backend state. |
+
+Supported filters and values:
+
+| Command | Option | Values |
+| --- | --- | --- |
+| `rules get` | `--scope` | `policies`, `default`, `policy`; default `policies` |
+| `rules get` | `--policy-id` | Required only with `--scope policy` |
+| `rules get` | `--format` | `yaml`, `json`; default `yaml` |
+| `rules get` | `--output` | Optional output file path; defaults to stdout |
+| `rules diff` | `[file]` | YAML or JSON file; defaults to `zeuslock.rules.yaml`, `zeuslock.rules.yml`, then `zeuslock.rules.json` |
+| `rules diff` | `--scope` | `policies`, `default`, `policy`; default `policies` |
+| `rules diff` | `--policy-id` | Required only with `--scope policy` |
+| `rules diff` | `--format` | `text`, `json`; default `text` |
+
+Rules export scopes:
+
+| Scope | Backend APIs |
+| --- | --- |
+| `policies` | `GET /api/policies` plus `GET /api/groups`; exports the visible dashboard policy system. |
+| `default` | `GET /api/rules`; exports the org-wide Default Policy ruleset used by the frozen rules contract. |
+| `policy` | `GET /api/policies/{policy_id}`; exports one policy. |
+
+`rules diff` exits with status code `1` when differences are found. Rule import/apply, policy publishing, and backend-side diff are not implemented because the dashboard/backend do not expose policy-as-code import/apply or diff features.
+
+## Publishing
+
+This package is configured as `zeuslock-dlp-cli` and exposes the executable command `zeuslock`.
+
+Before publishing, confirm that the npm account is the intended package owner, choose the final license, and verify that `package.json` is already at the intended release version. Then run:
+
+```bash
+npm publish --access public
+```
+
+For production releases, prefer npm Trusted Publishing from GitHub Actions instead of storing a long-lived npm token.

package/bin/zeuslock.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { run } from "../src/cli.js";
+
+run(process.argv).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "zeuslock-dlp-cli",
+  "version": "0.2.0",
+  "description": "Command line tools for ZeusLock.",
+  "type": "module",
+  "bin": {
+    "zeuslock": "bin/zeuslock.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node ./bin/zeuslock.js",
+    "test": "node --test",
+    "test:cli": "node ./bin/zeuslock.js --help && node ./bin/zeuslock.js status --json",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "keywords": [
+    "zeuslock",
+    "cli",
+    "security"
+  ],
+  "license": "UNLICENSED",
+  "dependencies": {
+    "commander": "^15.0.0",
+    "yaml": "^2.9.0"
+  }
+}