Healix Docs — Command Reference

At a glance

All Commands

A complete list of available commands, what they do, and what they cost.

Command	Description	Cost
healix init	Detect language and initialise project configuration	FREE
healix scan	Dual-scanner vulnerability scan + compliance report	FREE
healix scan --sbom	Scan and generate a CycloneDX SBOM alongside results	FREE
healix scan --vex	Scan and generate an OpenVEX document alongside results	FREE
healix remediate	AI-powered autonomous remediation: fix, build, test, verify	1 CREDIT
healix sbom [IMAGE]	Generate a CycloneDX 1.5 SBOM for any image	FREE
healix vex [IMAGE]	Generate an OpenVEX 0.2.0 document from scan results	FREE
healix sign [IMAGE]	Sign image with Cosign; attach SBOM + VEX attestations	FREE
healix push [IMAGE]	Push a signed image to ECR, Docker Hub, GHCR, or private registry	FREE
healix compliance	Generate a per-image regulatory compliance scorecard	FREE
healix credits	Show balance and usage history	FREE
healix status	System health check: tools, API keys, credits, last scan	FREE

Getting started

Typical Workflow

Most users follow this sequence from a cold start to a signed, production-ready image.

01

Initialise your project

Run from the root of any directory containing a Dockerfile. Healix detects your language and creates a local config.

                            healix init

                            ✓ Detected language: Java (Maven)

                            ✓ Config written to .healix/config.json

02

Scan for free

Runs two scanners in parallel and merges results. CVEs confirmed by both are flagged with high confidence. No credit required.

healix scan

03

Remediate autonomously

Healix generates a fix, builds your image, runs your test suite, and retries with alternative strategies if tests fail. One credit is charged only on success — when tests pass and vulnerabilities are reduced.

healix remediate

04

Sign and push

Cryptographically sign the remediated image and push it to your registry. The SBOM and VEX document generated during remediation are attached as signed attestations automatically.

                            healix sign my-app:remediated

                            healix push my-app:remediated --registry registry.example.com/my-app

Supply chain security

What Ships with Every Remediation

Every successful healix remediate produces a complete, cryptographically verifiable supply chain trail automatically — no extra flags required.

🔍

Scan

healix scan

→

🔧

Remediate

healix remediate

→

📋

SBOM

auto-generated

→

📄

VEX

auto-generated

→

🔑

Signed

healix sign

→

🚀

Registry

healix push

💡 Signing is enforced. healix push will block if the image has not been signed. There is no bypass flag — this is intentional.

Command

healix init

Detects your project's language and runtime, and writes a local configuration file to .healix/config.json.

healix init Initialise project

FREE

# Run from the root of any project with a Dockerfile healix init

✓ Detected language: Java (Maven) ✓ Dockerfile found at: ./Dockerfile ✓ Test command detected: mvn test ✓ Config written to: .healix/config.json

Detection is automatic. Supported languages are Java (Maven) and Node.js (npm), with Python, Go, .NET, and Ruby coming soon.

Command

healix scan

Runs a dual-scanner vulnerability scan and compliance report. Free, unlimited, no credits required.

healix scan Scan for vulnerabilities

FREE

Two scanners run in parallel. CVEs confirmed by both are marked as high-confidence findings and prioritised during any subsequent remediation. Compliance issues — including root user configuration, hardcoded secrets, missing OCI labels, and outdated base images — are reported in the same pass.

Flag	Description
--image <ref>	Scan a specific pre-built image instead of building from the Dockerfile
--sbom	Generate a CycloneDX 1.5 SBOM alongside the scan
--vex	Generate an OpenVEX document alongside the scan
--output json	Output results as JSON (useful for CI/CD gating)
--save <file>	Save results to a file instead of stdout

# Scan the project image healix scan # Scan a specific image healix scan --image my-app:v1.2.3 # Scan and generate SBOM in one pass healix scan --sbom # Save report as JSON (useful in CI/CD pipelines) healix scan --output json --save scan-report.json

Scanners: grype + docker-scout ───────────────────────────────────── Critical 38 High 124 Medium 287 Low 431 ───────────────────────────────────── ✓ Confirmed by both scanners: 31 CVEs Compliance issues: root user, 2 hardcoded env vars, missing OCI labels

Command

healix remediate

The core command. Autonomously generates a fix, builds your image, runs your tests, and retries until they pass. Charged only on success.

healix remediate Autonomous fix + build + test

1 CREDIT ON SUCCESS

Healix presents a diff of proposed changes and asks for your approval before building. If you approve, it builds the image, runs your test suite, and — if tests fail — retries with an alternative strategy automatically. SBOM and VEX documents are generated for the remediated image automatically.

A credit is deducted only when both conditions are met: your tests pass, and the total vulnerability count is lower than before.

Flag	Description
--auto-approve	Skip the interactive diff review and proceed immediately
--dry-run	Preview the proposed changes without building or spending a credit
--test-command <cmd>	Override the test command detected by `healix init`
--output-tag <tag>	Tag the remediated image with a custom name

# Interactive mode (default) — review diff, then approve healix remediate # Skip approval — useful in supervised automation healix remediate --auto-approve # Preview without building or charging a credit healix remediate --dry-run # Override the test command healix remediate --test-command "npm run test:ci" # Tag the output image healix remediate --output-tag my-app:secure

✓ Base image: openjdk:11 → eclipse-temurin:17-jre-alpine ✓ Non-root user added: appuser (UID 1001) ✓ Dependencies updated: 24 packages ✓ All 156 tests passed ✓ Critical: 38 → 0 Total: 880 → 34 (−96%) ✓ Image size: 945 MB → 136 MB (−86%) ✓ SBOM generated: 312 components → .healix/remediation/sbom.json ✓ VEX generated: .healix/remediation/vex.json ✓ 1 credit used | Remaining: 4

ℹ If tests fail on the first attempt, Healix automatically retries with an alternative strategy at no additional cost. Multiple retries are included within the single credit.

Command

healix sbom

Generates a CycloneDX 1.5 Software Bill of Materials for any container image. Required by EO 14028, FDA Premarket guidance, NIS2, and the EU Cyber Resilience Act.

healix sbom [IMAGE] Generate CycloneDX SBOM

FREE

Produces a full component inventory in CycloneDX 1.5 JSON format, broken down into OS packages and application packages. When run as part of healix remediate, the SBOM is generated automatically and written to .healix/remediation/sbom.json.

Flag	Description
--output <file>	Write the CycloneDX JSON to a file instead of stdout

# SBOM for the project image healix sbom # SBOM for a specific image healix sbom my-app:remediated # Write to file healix sbom my-app:remediated --output ./sbom.json

Command

healix vex

Generates an OpenVEX 0.2.0 document that classifies every CVE from the scan results — eliminating alert fatigue from false positives in downstream tools and audits.

healix vex [IMAGE] Generate OpenVEX document

FREE

Compares before and after scan results and classifies each CVE as one of four states: fixed, not_affected, under_investigation, or affected. Generated automatically during remediation at .healix/remediation/vex.json.

Flag	Description
--before <file>	Path to the before-scan JSON (auto-detected from .healix/ if omitted)
--after <file>	Path to the after-scan JSON (auto-detected from .healix/ if omitted)
--output <file>	Write the OpenVEX JSON to a file

# Auto-detect from last remediation healix vex # Explicit image and scan files healix vex my-app:remediated --before before.json --after after.json # Write to file healix vex --output vex.json

Command

healix sign

Cryptographically signs a container image using Cosign and attaches the SBOM and VEX documents as signed OCI attestations — satisfying EO 14028, FedRAMP, and PCI DSS supply chain requirements.

healix sign [IMAGE] Sign image + attach attestations

FREE

Supports two signing modes. Keyless signing uses the Sigstore OIDC flow — no key file required. Key-based signing uses an ECDSA private key you provide. The image must already exist in a registry before signing.

Flag	Description
--key <file>	Path to ECDSA private key for key-based signing (omit for keyless)

# Keyless signing (Sigstore OIDC — no key file needed) healix sign my-app:remediated # Key-based signing healix sign my-app:remediated --key cosign.key # Verify the signature and attestations afterwards cosign verify --key cosign.pub my-app:remediated cosign verify-attestation --type cyclonedx my-app:remediated cosign verify-attestation --type openvex my-app:remediated

Command

healix push

Pushes a signed image to a container registry. Signing is enforced — the push is blocked if healix sign has not been run on the image.

healix push [IMAGE] Push signed image to registry

FREE

Supports Amazon ECR (auto-detected by URL pattern with automatic AWS authentication), Docker Hub, GitHub Container Registry (GHCR), and any private registry accessible via standard Docker credentials.

The --registry URL is saved to .healix/config.json after first use — you can omit it on subsequent pushes.

Flag	Description
--registry <url>	Registry URL (saved after first use — optional on subsequent calls)

# Push to Amazon ECR healix push my-app:remediated --registry 123456789.dkr.ecr.us-east-1.amazonaws.com/my-app # Push to Docker Hub healix push my-app:remediated --registry docker.io/myorg/my-app # Push to GHCR healix push my-app:remediated --registry ghcr.io/myorg/my-app # Subsequent push — registry saved from previous run healix push my-app:remediated

Command

healix compliance

Generates a per-image regulatory compliance scorecard. Covers 17 frameworks across finance, healthcare, government, EU regulation, and cross-industry standards. Always free.

healix compliance Regulatory scorecard

FREE

Flag	Framework
--framework nist	NIST SP 800-190 (default)
--framework pci	PCI DSS 4.0
--framework hipaa	HIPAA Security Rule
--framework fedramp	FedRAMP
--framework soc2	SOC 2 Type II / ISO 27001
--framework nis2	NIS2 / Cyber Resilience Act / DORA

# NIST SP 800-190 scorecard (default) healix compliance # PCI DSS 4.0 scorecard healix compliance --framework pci # HIPAA scorecard healix compliance --framework hipaa

Command

healix credits

Check your balance, view remediation history, and purchase credit packs.

healix credits Manage credits

FREE

# Balance + last 10 entries + success rate healix credits # Full history with before/after vulnerability counts healix credits history # Purchase a credit pack healix credits buy

Command

healix status

System health check. Verifies tool availability, API key configuration, credit balance, and last scan summary.

healix status System health

FREE

healix status

✓ Docker daemon: running ✓ grype: v0.73.x ✓ docker scout: v1.x ✓ syft: v1.x ✓ cosign: v2.x ✓ API key: sk-ant-••••••••••••xxxx ✓ Credits: 4 remaining Last scan: 880 vulns (38 critical) my-app:latest

Examples

Real-World Usage

End-to-end examples for common project types.

cd my-spring-app healix init ✓ Detected language: Java (Maven) healix scan Critical: 38 High: 124 Medium: 287 Low: 431 Total: 880 healix remediate ✓ openjdk:11 → eclipse-temurin:17-jre-alpine ✓ 24 dependencies updated ✓ All 156 tests passed ✓ 880 → 34 vulnerabilities (−96%) ✓ 945 MB → 136 MB (−86%) healix sign my-app:remediated --key cosign.key healix push my-app:remediated --registry 123456.dkr.ecr.us-east-1.amazonaws.com/my-app

cd my-express-app healix scan Critical: 12 High: 67 Medium: 143 Low: 234 Total: 456 healix remediate --auto-approve ✓ node:14 → node:20-alpine ✓ 18 npm packages updated ✓ All 89 tests passed ✓ 456 → 28 vulnerabilities (−94%) healix sign my-app:remediated healix push my-app:remediated --registry ghcr.io/myorg/my-app

# Fail the pipeline if critical vulnerabilities are found healix scan --output json --save scan-report.json if [ $(jq '.summary.critical' scan-report.json) -gt 0 ]; then echo "Critical vulnerabilities found — blocking merge" exit 1 fi # Generate SBOM for every build as an artefact healix scan --sbom

💡 Scanning is free and unlimited. Gate your pipeline on scan results at no cost. Use healix remediate for scheduled overnight fix runs where a credit is warranted.

Reference

Output Files

All files written by Healix are placed under the .healix/ directory in your project root.

File	Contents	Written by
.healix/config.json	Project config — language, image name, registry URL, test command	healix init, healix push
.healix/sbom.json	CycloneDX 1.5 SBOM for the scanned image	healix scan --sbom
.healix/vex.json	OpenVEX document from scan results	healix scan --vex
.healix/remediation/sbom.json	CycloneDX 1.5 SBOM for the remediated image	healix remediate (auto)
.healix/remediation/vex.json	OpenVEX comparing before/after CVE states	healix remediate (auto)

Reference

Supported Languages

Language	Build Tool	Detected by	Test Runner	Status
Java	Maven	pom.xml	mvn test	LIVE
Node.js	npm	package.json	npm test	LIVE
Python	pip	requirements.txt	pytest	COMING SOON
Go	modules	go.mod	go test ./...	COMING SOON
.NET	NuGet	.csproj	dotnet test	COMING SOON
Ruby	Bundler	Gemfile	bundle exec rspec	COMING SOON

Reference

Compliance Frameworks

The healix compliance command maps scan results to the following 17 regulatory frameworks.

Industry	Framework	--framework flag
Finance	PCI DSS 4.0	`pci`
Finance	SOX	`sox`
Finance (EU)	DORA	`nis2`
Finance (US)	GLBA	`glba`
Healthcare	HIPAA Security Rule	`hipaa`
Healthcare	FDA Premarket Cyber Guidance	`fda`
Government (US)	FedRAMP	`fedramp`
Government (US)	EO 14028	`fedramp`
Government (US)	NIST SP 800-190	`nist`
Government (US)	NIST SP 800-53 Rev 5	`nist`
EU	NIS2 Directive	`nis2`
EU	Cyber Resilience Act (CRA)	`nis2`
Cross-industry	ISO/IEC 27001:2022	`soc2`
Cross-industry	SOC 2 Type II	`soc2`
Cross-industry	CIS Controls v8	`nist`
Insurance	NAIC Model Law	`naic`
Energy	NERC CIP	`nerc`