Scanning

CLI Reference

The hzsec CLI is installed alongside the desktop app. It exposes the full scanner with output format options suited for CI pipelines and scripting.

`hzsec scan [path]`

Scan a file or directory for security issues. Defaults to the current directory if no path is given.

# Scan ./src with all detectors (full mode, default)
hzsec scan ./src

# Quick mode — faster, covers code, config, and web only
hzsec scan --mode quick ./src

# Scan for secrets only
hzsec scan --mode secret ./src

# Output as JSON (for CI scripts or other tooling)
hzsec scan --format json . > results.json

# Output as SARIF (for GitHub Code Scanning)
hzsec scan --format sarif --output results.sarif .

# Fail the pipeline if any CRITICAL or HIGH findings exist
hzsec scan --fail-on critical,high .

Flags

Flag	Short	Description
--mode <mode>	-m	Scan mode. Default: full. Choices: full \| quick \| secret \| config \| web \| hardening \| custom
--format <format>	-f	Output format. Default: text. Choices: text \| json \| sarif
--output <file>	-o	Write output to a file instead of stdout.
--fail-on <severities>		Exit with code 1 if any findings match. Comma-separated list of: CRITICAL, HIGH, MEDIUM, LOW, INFO. Example: --fail-on critical,high
--no-color		Disable ANSI colors in text output.
--quiet		Suppress the progress spinner. Only findings and the summary are printed.
--version	-v	Print the installed hzsec version and exit.

Scan modes

Mode	Detectors active
full	code, config, secret, web, hardening — all detectors (default)
quick	code, config, web — faster, targeted at changed files in practice
secret	Secrets and credentials only
config	Configuration files only
web	Web exposure issues only
hardening	System hardening and CI/CD config only
custom	code, config, secret, web, hardening + any custom rules

Output formats

text (default)

Human-readable terminal output with ANSI colors. Findings are sorted by severity, each showing the severity level, title, file path, line number, and a brief description. A posture score is printed at the end.

json

Structured JSON containing the full findings array, posture score, scan metadata, and risk distribution. Suitable for piping into other tools or storing as a CI artifact.

hzsec scan --format json . > results.json

sarif

SARIF v2.1.0 output — the standard format for GitHub Code Scanning and other SAST tooling integrations.

hzsec scan --format sarif --output results.sarif .

Exit codes

Code	Meaning
0	Scan completed. No findings matched the --fail-on threshold (or --fail-on was not set).
1	Scan completed. One or more findings matched the --fail-on severity list.
2	Invalid arguments or runtime error. Details printed to stderr.

GitHub Actions example

- name: HZSec security scan
  run: |
    hzsec scan --format sarif --output hzsec.sarif .
    hzsec scan --fail-on critical,high .

- name: Upload SARIF to GitHub Code Scanning
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: hzsec.sarif

Running the SARIF pass first (exit code 0 always) ensures the artifact is uploaded even when the fail-on pass returns exit code 1.

← Scan Modes Architecture →