Skip to content

refpoint run

Execute a profile against one or more targets.

On this page
refpoint run PROFILE_PATH [flags]

Executes a profile against one or more targets. It takes exactly one path argument. The path may be a single control file, a profile directory containing profile.rpp, or a plain directory that is scanned for profile subdirectories up to scan_depth levels.

Connection flags

Flag Default Description
--ssh-key PATH SSH private key
--ssh-password STRING SSH password
--ssh-known-hosts-file PATH ~/.ssh/known_hosts Also accepts accept-new and insecure
--connect-retries N 0 Extra SSH attempts on transient failures. Attempt N waits N times 2 seconds
--winrm-password STRING WinRM password
--winrm-https false Use HTTPS for WinRM on port 5986
--winrm-insecure false Skip TLS verification for WinRM HTTPS. Prints a warning
--winrm-allow-unencrypted false Permit plain HTTP WinRM to a peer that cannot negotiate NTLM sealing
--sudo false Run commands under sudo on SSH and local Unix targets
--sudo-password STRING Password for sudo -S, or set REFPOINT_SUDO_PASSWORD

Target selection

Flag Default Description
--targets LIST Additional target addresses, repeatable and comma-separated
--targets-file PATH HCL inventory file
--host-tag key=value Select inventory targets by tag. Repeating a key ORs its values, distinct keys AND
--target-parallelism N 16 Max concurrent target scans. 0 means the default

With no target given at all, the run defaults to local. A --host-tag selector that matches nothing is an error, not a silent fall-through to local.

Filtering

Flag Description
--control LIST Only these control IDs
--skip LIST Exclude these control IDs
--tag key=value Filter controls by tag, repeatable
--impact FLOAT Only controls with impact at or above this value, 0.0 to 1.0

Variables and waivers

Flag Description
--var key=value Override a profile variable, repeatable. Always a string
--var-file PATH HCL file of overrides, native types preserved
--waiver-file PATH HCL file declaring accepted exceptions

--var wins over --var-file.

Output

Flag Default Description
--format FORMAT terminal terminal, json, junit, html, gha, gitlab, wazuh
--output PATH stdout Report file, created 0600
--reporter format[:path] Repeatable. Cannot be combined with --format or --output. At most one entry may write to stdout
--audit-log PATH Append an NDJSON trail of every transport operation, created 0600
--signing-key PATH Ed25519 PEM key for report attestation

Execution

Flag Default Description
--concurrency N 1 Controls executed in parallel per target. Must be at least 1
--timeout DURATION 30s Per-control timeout, Go duration syntax
--threshold FLOAT 0 Exit 5 when the weighted score falls below this percentage, 0 to 100
--dry-run false Print the execution plan and exit 0

--dry-run supports only the terminal and json formats and cannot be combined with --reporter.

Security

Flag Default Description
--allowed-commands LIST empty Executable basenames the command resource may run. Deny by default. * permits everything
--allow-private-http false Let http checks reach loopback, link-local and RFC1918 destinations

Examples

Run locally against the shipped example profile, which uses one command check:

refpoint run profiles/example --allowed-commands uname

Write three reports from one run:

refpoint run baseline \
  --reporter terminal \
  --reporter junit:report.xml \
  --reporter html:report.html

Scan a tagged slice of an inventory and gate on the weighted score:

refpoint run baseline \
  --targets-file fleet.rptargets \
  --host-tag env=production \
  --host-tag role=web \
  --threshold 95 \
  --format json --output result.json

Exit codes

Code Condition
0 Everything passed
1 At least one control failed, and either no threshold was set or the score met it
2 At least one target was unreachable or a control errored
5 Controls failed and the weighted score fell below --threshold
130 Interrupted by SIGINT or SIGTERM