Imported from zzeloff/zabbix-threat-control (AGENTS.md). Install upstream with npx skills add zzeloff/zabbix-threat-control. Copyright stays with the author.

AGENTS.md

Runbook for integrating ztc into a Zabbix installation. Written so an AI assistant (or a human integrator) can take a client's Zabbix from zero to a working vulnerability-management view. Each step has a command and a way to verify it worked. For hacking on the ztc code itself, see Developing ztc at the end and docs/guide.md.

What ztc does

ztc reads each host's software inventory through the stock zabbix-agent2, audits it against Vulners, and pushes scored, per-host findings back into Zabbix as problems, a dashboard and CVSS graphs. It runs as one static Linux binary and talks to Zabbix over the JSON-RPC API + zabbix-sender.

agent2 UserParameters ─► Zabbix items ─► ztc scan ─► Vulners audit ─► sender ─► Zabbix problems/dashboard

Prerequisites

• Zabbix 6.0 / 7.0 LTS, 7.4 or 8.0 — the API version is auto-detected; no per-version setup.
• A Vulners API key — from https://vulners.com (account → API keys).
• zabbix-agent2 on every host you want scanned, with the ztc UserParameter snippet:
  • Linux — deploy/agent/linux/vulners.conf: keys vulners.os, vulners.version, vulners.arch, vulners.packages, vulners.fix[*].
  • Windows — deploy/agent/windows/vulners.conf: keys vulners.os, vulners.version, vulners.win.software, vulners.win.kb.
• One Linux host (amd64/arm64) to run ztc — reachable to the Zabbix API and to Vulners. The Zabbix server itself is a fine choice.

1. Install ztc

On the Linux host that will run ztc:

curl -fsSL https://raw.githubusercontent.com/vulnersCom/zabbix-threat-control/master/deploy/install.sh | sudo sh

The installer detects the arch, downloads the latest stable release, installs /usr/local/bin/ztc, creates a ztc service user, writes /etc/ztc/ztc.env, and installs a systemd unit. Alternatives (Docker, manual, air-gapped): deploy/README.md.

• Verify: ztc version prints a version.
• Note: releases marked pre-release are not resolved by "latest" — pin one with ZTC_VERSION=vX.Y.Z ... | sudo sh if needed.

2. Configure

Secrets go through environment variables (they override the YAML file). The installer collects these into /etc/ztc/ztc.env; every knob is documented in config.example.yaml.

ztc --help lists the same set. The only settings with no env form are the entities.* names of the group/templates/report hosts/dashboard — pass a YAML file (--config) if you need to rename those.

3. Provision the Zabbix objects

ztc provision --all

Creates: the Vulners host group, two collection templates (Linux + Windows), the four report hosts — Vulners - Hosts, - Bulletins, - Packages, - Statistics — with their LLD rules, prototypes and CVSS-scored triggers, and the Vulners dashboard. Granular flags exist: --template, --vhosts, --dashboard.

Re-running it is a reconciliation, not a no-op: objects that already exist are updated in place (trapper Allowed hosts, value_type, LLD severity overrides, trigger prototypes) and the log names what changed. Run it after every ztc upgrade — the new binary alone does not fix objects the old one created; see Upgrading an existing ztc install.

• Verify: Data collection → Templates shows Template Vulners OS-Report Linux/… Windows; Monitoring → Dashboards → Vulners exists.
• Note: with zabbix.trapper_hosts unset, provision logs a warning and sets Allowed hosts to 0.0.0.0/0,::/0 (accept from anywhere) — required for Zabbix 8.0, which otherwise rejects ztc's pushes. Set it to ztc's source address to narrow that down.

4. Link the collection template to monitored hosts

This is what connects real hosts to ztc. For each host to be scanned, in Data collection → Hosts → → Templates, attach:

• Template Vulners OS-Report Linux — for Linux hosts, or
• Template Vulners OS-Report Windows — for Windows hosts.

The template's items poll the agent2 vulners.* UserParameters into Zabbix.

• Verify: zabbix_get -s <host-ip> -k vulners.os returns the OS (agent side); after a minute, Monitoring → Latest data for the host shows vulners.* values.

5. Scan and verify

ztc scan --once      # a single collect → audit → push cycle
ztc scan --daemon    # loop on `schedule` (default 24h); this is what the systemd unit runs

Useful flags: --limit N (first N hosts), --nopush (dry run, audit only), --push-delay D, --auto-fix (see step 7).

• Verify: systemctl status ztc is active; Monitoring → Problems fills with Vulners - … problems within a scan cycle.

6. Read the results

Monitoring → Dashboards → Vulners gives you:

• Problems by severity — findings fire at Disaster / High / Average / Warning by their CVSS, so the breakdown is meaningful.
• Vulners - Hosts / Packages / Bulletins — per-report problem lists.
• Median CVSS Score trend and CVSS Score ratio by hosts pie.

Every finding is one (vulnerability, host) problem, carrying a vulners.host tag. To see one host's vulnerabilities: Monitoring → Problems → Filter → Tags: vulners.host Equals <host>.

7. Remediate (optional)

ztc fix --host <host> --package <pkg>   # upgrade one package
ztc fix --host <host> --all             # upgrade all vulnerable packages on the host
ztc fix ... --dry-run                   # preview only

Auto-fix: ztc scan --daemon --auto-fix upgrades a package when a trusted user (fix.trusted_users) acknowledges its problem in Zabbix. Upgrades run through the whitelisted vulners.fix[<pkg>] UserParameter drained by a host-side worker (deploy/agent/linux/vulners-fix-worker.sh

• cron) — never arbitrary system.run. Rationale: docs/adr/0001-remediation-mechanism.md.

Troubleshooting

Commands

ztc scan --daemon                 # run the scan loop on a schedule
ztc scan --once                   # a single cycle
ztc provision --all               # create group, templates, report hosts, dashboard
ztc fix --host H --package P      # remediate a package (whitelisted, opt-in)
ztc upgrade [--version vX.Y.Z]    # self-update the binary from GitHub Releases
ztc version [--check]             # print version (and check for a newer release)

Developing ztc

This file is an integrator guide, not a contributor guide. If you are changing ztc's code, read docs/guide.md for the architecture. In short: external systems sit behind interfaces with test doubles (vulners.Auditor, zabbix.Client); audit/aggregate are pure transforms with table-driven tests; add a Zabbix version as a new zabbix.Client, never as branches in business logic. Build/verify: go build ./... && go test ./... && go vet ./... && gofmt -l ..