One dashboard. Lightweight collectors.

01 / Host the central service

Download the MIT source archive or use your Git checkout. Docker/Compose runs the app, PostgreSQL and Caddy HTTPS proxy. Use compose.external.yaml to use your existing PostgreSQL without another database container. A configuration generator needs Node 20+; the application container uses Node 24.

node scripts/setup.mjs
# Edit the private .env: PUBLIC_URL, DATABASE_URL, SMTP_URL and SMTP_FROM.
# Keep the random master key and database password private and backed up.
docker compose up -d --build
docker compose exec app node platform/selfhost/server.mjs create-admin you@example.com
# Existing PostgreSQL:
# docker compose -f compose.external.yaml up -d --build

Point DNS to your server and configure HTTP/HTTPS access for TLS. The app's HTTP port stays internal. Set PUBLIC_URL to your HTTPS origin. Use verified TLS for an external database. Registration is off by default; enable it only after SMTP works. New registrations require email verification; password recovery uses one-time links. The first administrator account is created through your server terminal with a hidden password prompt.

The app uses its own login/session system. It does not require ChatGPT hosting or login, a local dashboard on monitored machines, or a model runtime on each machine. Back up PostgreSQL and the master key separately, rehearse restore and monitor your central service independently. Detailed instructions are in the bundled README, deployment/ARCHITECTURE.md and deployment/BACKUP.md.

02 / Download and connect

Download the matching Linux script, installer, npm tarball and SHA-256 checksums. Inspect the source and compare downloaded files to their checksums. Checksums are not independent signatures. Python 3.9+ is required for Linux; npm collectors require Node 20.11+, with Node 24 recommended.

curl -fSLO __ZYRASEC_PUBLIC_URL__/downloads/zyrasec.py
curl -fSLO __ZYRASEC_PUBLIC_URL__/downloads/install.sh
# Verify and inspect both companion files before executing the installer.
sh install.sh
python3 "$HOME/.local/share/zyrasec/zyrasec.py" login \
  --dashboard __ZYRASEC_PUBLIC_URL__ --asset-id my-server --online
python3 "$HOME/.local/share/zyrasec/zyrasec.py" watch \
  --config "$HOME/.config/zyrasec/host.json"

npm install --global --ignore-scripts ./zyralabs-zyrasec-0.3.0-beta.1.tgz
# Inside your project:
zyrasec login --dashboard __ZYRASEC_PUBLIC_URL__ \
  --config "$HOME/.config/zyrasec/my-app.json" --asset-id my-app --online
zyrasec watch --config "$HOME/.config/zyrasec/my-app.json"

The terminal shows a device code. Sign in at the displayed dashboard URL, review the collector label/type/asset and approve the code you started. A scoped token is saved once in a separate private file; your dashboard password never goes to the collector. Tokens are revocable. You can also create one manually under Connect a collector and use init.

Each project needs a separate config. Default watch interval is one hour (minimum 60 seconds); --once runs one cycle. Plain scans stay offline. --online queries OSV explicitly; omit it to upload inventory for central matching. Report sync requires HTTPS, with loopback HTTP for local testing. Linux service --config /absolute/path/host.json --output zyrasec.service writes a monitoring service for review; installation never enables it.

03 / Serverless and CI

Use a one-shot scan in your build or deployment pipeline. Store the token in CI secrets and keep it out of browser bundles, code, logs and command arguments.

zyrasec scan --online --asset-id my-deployment \
  --lockfile package-lock.json --output report.json \
  --endpoint __ZYRASEC_PUBLIC_URL__/api/ingest
# The pipeline supplies ZYRASEC_SYNC_TOKEN through its secret store.

The @zyralabs/zyrasec/serverless entrypoint provides submitInventory using Web APIs only. It accepts a real build-generated list of public package names, exact versions and registry origins; it requires neither filesystem access nor a daemon. The central worker matches uploaded inventory afterwards. Prefer reporting once per deployment over reporting on every request.

Connect a repository in Central controls to scan its lockfile hourly, independently of a serverless runtime. This does not prove which commit is deployed; report observation time and advisory freshness remain separate.

04 / Exact-action approvals and optional automation

Repository connection uses a selected-repository GitHub token encrypted on this server. Contents read enables scans; Contents/Pull requests write enables fix PRs; Actions write enables dispatch. Proposing the workflow installation also requires Workflows write permission, or you can install the workflow manually. Review and merge the setup PR before requesting a repair.

An approved repository action fixes an exact package/target on an exact base commit. Actions prepares metadata without install scripts, runs your npm test in a separate read-only job, and creates a PR from a separate publishing job after tests pass. The workflow does not merge or deploy the change. A missing test script or moved base blocks the repair. Review compatibility and stage the PR before merging.

Linux repair execution is a separate, explicitly enabled agent. It currently supports Debian/Ubuntu APT packages only, with a package allowlist, daily limit, private config owned by its user and deliberate root privileges. It never invokes sudo. APT updates may run vendor maintainer scripts and restart affected services; schedule a maintenance window. It rejects expired/tampered approvals, changed installed versions, downgrades, removals and dependency changes beyond the exact approved package.

# Review examples/repair-policy.json. Place root-owned config and policy
# under a root-owned directory such as /etc/zyrasec/ before running as root.
python3 zyrasec.py agent --config /etc/zyrasec/host.json \
  --repair-policy /etc/zyrasec/repair-policy.json --allow-package-updates

Default policy requires manual approval. Automatic host updates require both a dashboard allowlist/limit and allowAutomatic: true in the local policy. Automatic repository selection is limited to known same-major/minor candidate fixes that have no remaining OSV match, and still opens a tested PR. No AI-proposed shell command is executed. Coordinated upgrades, SSH/firewall rewrites, automatic rollback and production deployment remain manual.

05 / Central email and your model

Your administrator configures SMTP_URL and SMTP_FROM. TLS or verified STARTTLS is required. The central worker queues/retries emails for finding changes, stale collectors and repair outcomes, even when a monitored collector is offline. Users choose severity and an optional daily critical/supply-chain digest. A central-service or SMTP outage needs independent operational monitoring.

Central controls supports your chosen OpenAI-compatible endpoint, Anthropic, your open-source model service, or an operator-managed profile. MODEL_ALLOWED_ORIGINS limits destinations and can include an explicitly trusted local model server. Profile keys are encrypted and excluded from list/export APIs. The managed option uses your operator's configured provider/key; there is no billing service in this beta.

Models receive up to 50 findings and coverage metadata. Default maximum output is 1,200 tokens, maximum 4,096; at most 10 attempts per account per day. Plans are untrusted review material and use a separate path from typed repair approvals. Provider charges may apply.

06 / CVE and supply-chain tracking

Public advisories combine NVD critical CVEs (every six hours), CISA known-exploited CVEs and GitHub critical/malware advisories (hourly), with source links, CVE identifiers and feed status. The central worker rechecks stored inventories through OSV every six hours. Old inventory stays stale until the collector reports again.

Feeds have bounded pagination and source/API limits. Published-advisory tracking is not complete zero-day, runtime exploitability, provenance or malware detection. A known malicious package may require incident response beyond changing versions. A source failure retains previous evidence and is shown in feed status.

Coverage and beta limits

npm lockfile versions 1/2/3 and public npm registry identities are supported. Git/local/private dependencies, Yarn/pnpm, source reachability and containers are outside matching coverage. Host advisories support Ubuntu 20.04/22.04/24.04/26.04 LTS and Debian 11/12/13, using full source-package revisions and backports. Selected SSH/UFW/reboot observations are incomplete; missing permission stays unknown.

Unknown means incomplete/unqueried/stale; Needs review means findings; Attention means high/critical matches. Clear in scope means no matches in a fresh complete reported scope, not a guarantee of security. Acknowledgement/review does not resolve a finding.

Limits: 100 assets and tokens, 12,000 packages, 5,000 findings, 2 MiB per report. One latest full report, 50 check summaries per asset and latest 200 alerts. Reviews expire in at most 30 days. Mail/model plans have 30-day retention, audit records 90 days. Back up your database and master key; complete provider delivery tests and a restore rehearsal before inviting users.