# Core concepts

> The object model, status vocabulary, and scoring rules behind every run.

Source: https://refpoint.dev/docs/getting-started/concepts

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:

1. The probed OS
2. The distro family
3. 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 |