Core concepts
The object model, status vocabulary, and scoring rules behind every run.
On this page
This page defines the terms the rest of the documentation relies on: what a run executes, what each status means, and how a run becomes a number a pipeline can gate on.
What refpoint is
refpoint evaluates declarative compliance controls against machines. A control states the expected state. refpoint connects to the target, reads the relevant state, and reports whether each assertion holds. It never modifies the target.
Three design constraints:
| Constraint | Effect |
|---|---|
Controls are HCL data, parsed by hashicorp/hcl/v2 |
No profile code executes on the operator’s machine |
| One static Go binary | No runtime on the runner, nothing installed on the target |
| Arbitrary execution denied by default | The command resource runs an executable only when both the operator and the profile list it |
Object model
profile directory containing profile.rpp and controls/*.rpc
└── control one requirement: ID, title, impact, tags, refs
├── check one resource assertion (file, service, package, ...)
├── only_if optional precondition check
└── any_of named group, satisfied by one passing member| Term | Definition |
|---|---|
| Run | One profile, or a tree of profiles, evaluated against one or more targets |
ProfileResult |
The result of one profile on one target |
RunResult |
All ProfileResult entries for one profile across its targets |
| Multi-profile run | An array of RunResult |
Status vocabulary
Every control and check ends in exactly one of five statuses.
| Status | Meaning |
|---|---|
passed |
Every assertion held |
failed |
At least one assertion did not hold |
error |
Not evaluable: unreachable target, blocked command, decode failure, panic |
skipped |
Not evaluated by design: precondition unmet, condition drawn from an unset variable, no assertions |
waived |
An accepted exception applied |
failed and error are kept distinct. A target that cannot be reached is not
a compliant target. Unreachable targets are counted separately, exit with code
2, and are never removed from the report.
Status combination
Within a control:
| Rule | Result |
|---|---|
| Ungrouped checks | Combined with AND |
| Precedence | error over failed over passed |
| All checks skipped | Control is skipped, not passed |
Within an any_of group:
| Condition | Result |
|---|---|
| Any member passes | Group is satisfied. Every member still runs and is reported |
| No member passes, at least one errors | Group is error, since it may have been satisfiable |
| All members skipped | Group contributes nothing: absence of evidence, not failure |
Scoring
Two numbers per target.
| Metric | Formula | Notes |
|---|---|---|
| Pass rate | passed ÷ total | Ignores impact |
| Weighted score | Σ impact of passed controls ÷ Σ impact of scored controls, as a percentage | skipped and waived are excluded from the denominator. All controls passed with zero total impact scores 100 |
Run level: avg_score is the mean weighted score across reachable targets.
--threshold gates on avg_score.
Platform matching
A platform pattern is matched case-insensitively, in order, against:
- The probed OS
- The distro family
- The distro name
| Pattern | Matches |
|---|---|
linux |
Any Linux target |
debian |
Debian and derivatives, via ID_LIKE in /etc/os-release |
ubuntu |
Ubuntu only |
windows |
Any Windows target |
A control that does not apply to the probed platform is omitted, not reported
as skipped, so totals are unaffected. If the platform probe fails, the target
fails. refpoint never scans with platform filtering disabled.
Scope
refpoint is a read-only auditor, not a configuration manager. It produces an artifact that can be filed as evidence. It has no daemon, no server, and no database. State is the JSON results you keep.
Typical placements:
| Placement | Use |
|---|---|
| Scheduled runner | Scan a fleet over SSH, store the JSON |
| Pre-deployment gate | refpoint diff --fail-on-regression against the previous result |
| Workstation | Local check before a change is pushed |
Non-goals
| Not provided | Detail |
|---|---|
| Remediation | remediation is free text carried into the report |
| Bundled content | No baseline library, no framework mapping. One two-control example profile ships. You own the controls and the mapping to the clauses they evidence |
| Sandboxing of target tooling | The command allowlist gates by executable basename. Allowing an interpreter such as awk or perl allows anything |
| Monitoring | No time series, no alerting, no scheduler. Drive it from cron or CI |