Docs

Requirements

Minimum sizing for a PoC deployment. heretix-api and heretix-management are separate Docker Compose stacks; totals below cover both.

CPU

2 vCPU minimum. The heretix-api app container can burst to roughly 70% of one core during data imports and searches; Postgres adds its own load while an import is running.

RAM

8GB minimum, 16GB recommended. Postgres for heretix-api is the dominant consumer (around 7.7GB with a full NVD mirror plus several OSV ecosystems loaded); the two app containers and heretix-management’s database use well under 1GB combined.

Disk

20GB to start. heretix-api’s database volume alone can reach around 11GB after months of accumulated NVD and OSV data; budget more if you import every OSV ecosystem heretix supports.

Software

Docker, Docker Compose v2, and git.

Deploy heretix-apiGitHub

heretix-api aggregates NVD, OSV, CISA KEV, EPSS, and vendor advisories into a searchable database. It ships with its own PostgreSQL via Docker Compose.

1. Clone and configure

git clone https://github.com/TITeee/heretix-api
cd heretix-api
cp .env.example .env

Set API_KEY to a secret of your choosing (openssl rand -hex 32); heretix-cli and heretix-management both authenticate with it. Set ADMIN_API_KEY to a second secret, for the dashboard and for running and switching jobs, and keep it to administrators. Also set POSTGRES_PASSWORD, which otherwise defaults to changeme.

2. Start the stack

docker compose up --build -d
docker compose logs -f app

The API is now live at http://localhost:5000. GET /health checks it’s up; /dashboard shows import status and signs in with ADMIN_API_KEY.

3. Verify it’s running

curl http://localhost:5000/health
docker compose ps

Expect {"status":"ok",...} from the health check, and both containers listed as Up (the db container also shows healthy). If the app container keeps restarting, check docker compose logs -f app.

4. Update (later, when a new version is out)

git pull
docker compose up --build -d

Not part of the initial setup. Run it whenever you want to pick up new changes. Rebuilds the image and restarts the container; schema migrations and one-time backfills run automatically on every container start.

Reaching it from beyond your own network? Serve it over HTTPS: reverse proxy guide

Import vulnerability data

A fresh database is empty, and the scheduled jobs only fetch changes. Load it once from the dashboard before scanning anything: open /dashboard and sign in with ADMIN_API_KEY.

1. NVD

Press Load on the NVD row. The full mirror (~400k CVEs) takes several hours; setting NVD_API_KEY in .env raises the rate limit and is recommended. If it fails part way, press Load again and it carries on from where it stopped.

2. KEV and EPSS

Once NVD finishes, press Run on each. They only add data to CVEs already imported, so a scheduled run that fires before NVD completes leaves them empty until the next day.

3. OSV ecosystems

Under OSV Ecosystems, choose each ecosystem you actually scan (npm, PyPI, Go, Ubuntu, …) and press Add and load. That switches its daily job on and loads it in full. Malicious packages (MAL-*) arrive with these ecosystems.

4. Everything else

Switch the job On and press Run once: the vendor advisories and the Debian and Ubuntu trackers (debian-tracker, ubuntu-tracker). CVE Records (cna, a download of about 650MB) and Microsoft’s Windows Server advisories (advisory-microsoft) say Load the first time, like NVD. Only NVD, KEV and EPSS are scheduled by default.

Full ecosystem and vendor advisory list

Deploy heretix-managementGitHub

heretix-management is the web console for asset inventory, alert triage, and SLAs, and runs as its own Docker Compose stack with its own database.

1. Clone and configure

git clone https://github.com/TITeee/heretix-management
cd heretix-management
cp .env.example .env
# set AUTH_SECRET, AUTH_URL, HERETIX_API_KEY, POSTGRES_PASSWORD

AUTH_SECRET: generate with openssl rand -base64 32. AUTH_URL: the URL users will open, such as http://192.0.2.10:3000; sign-in redirects go there, so it must not be localhost unless you only use the server’s own browser. HERETIX_API_KEY must match the API_KEY set for heretix-api above. POSTGRES_PASSWORD: change it from the default, changeme. heretix-api’s URL defaults to http://host.docker.internal:5000, which reaches a heretix-api on the same server; set HERETIX_API_URL only if it runs elsewhere.

2. Start and create the admin user

docker compose up --build -d
docker compose exec app node_modules/.bin/tsx prisma/seed.ts

The seed creates admin@example.com with a generated password, printed once in its output: copy it before you close the terminal, since only a hash is stored. Set SEED_EMAIL and SEED_PASSWORD (at least 12 characters) to choose your own. Sign in at your AUTH_URL, then change the password on the Users page. Lost the password? Recovery steps

3. Verify it’s running

docker compose ps
curl -s -o /dev/null -w "%{http_code}\n" localhost:3000/login
docker compose logs -f app

The db container shows healthy once Postgres accepts connections; the app container has no built-in health check, so confirm it isn’t restarting and that the sign-in page answers 200.

4. Update (later, when a new version is out)

git pull
docker compose up --build -d

Not part of the initial setup. Run it whenever you want to pick up new changes. Database migrations run automatically on container start; the seed command from step 2 only needs to run once.

Reaching it from beyond your own network? Serve it over HTTPS: reverse proxy guide

Quick Start (CLI)GitHub

With both services running, pick what you want to do: check a host now, track findings in heretix-management, fail a CI build, or send them to GitHub. Download the heretix-cli binary for your platform (Linux amd64/arm64, Windows amd64) from the releases page, or build it from source with go build.

# The API key can also be passed with --api-key
export HERETIX_API_KEY=<your key>

# Scan this host
heretix-cli scan --api-url http://<api-host>:5000

# Scan a container image
heretix-cli scan --image nginx:latest --api-url http://<api-host>:5000

# By hand: write the SBOM, then import sbom.json on the Assets page
heretix-cli collect --output sbom.json

# From the command line or CI: send it with an access token
export HERETIX_MANAGEMENT_URL=https://heretix.example.com
export HERETIX_MANAGEMENT_TOKEN=<access token>
heretix-cli collect --image myapp:1.0 --name myapp --output sbom.json
heretix-cli upload sbom.json

# Fail the step on findings with a CVSS score of 7.0 or higher
# (HERETIX_API_KEY set as a CI secret)
heretix-cli scan --image myapp:latest --api-url http://<api-host>:5000 --severity 7.0

# Supply-chain checks only (offline, no API)
heretix-cli detect --scan-path .

# Submit the SBOM to the GitHub Dependency Submission API
heretix-cli submit sbom.json \
  --token $GITHUB_TOKEN \
  --repo owner/repo \
  --sha $SHA \
  --ref $REF

Cannot run heretix-cli on a host? The contrib tools build the same SBOM from rpm -qa output (RHEL family) or from a few Windows Server system commands. contrib