# Resource reference

> How checks address a resource, and what every resource type has in common.

Source: https://refpoint.dev/docs/resources

A resource type is what a check knows how to look at: a file, a service, a
listening port, a registry key. There are 28 of them. This page covers the
rules that hold for all of them, and the pages that follow list each type with
its attributes.

## Every attribute is checked at load time

Check bodies are decoded strictly. An attribute the resource does not declare
is a hard error with a suggestion, never a silently ignored typo. You find out
from `refpoint check`, before a run touches a machine.

Optional attributes are only asserted when you write them. A check with no
assertions produces no assertion results, and that aggregates to `skipped`
rather than `passed`. An empty check is not a passing check.

## Addressing a resource

Each resource is addressed by exactly one attribute. The loader peels that
attribute off and evaluates it with the profile's variable context, so an
address may interpolate a variable. Everything else in the body is decoded
later by the provider itself.

| Address attribute | Resource types |
|---|---|
| `path` | `file`, `directory`, `folder_contents`, `mount`, `x509_certificate` |
| `cmd` | `command` |
| `name` | `service`, `package`, `process`, `user`, `windows_feature`, `windows_firewall`, `audit_policy`, `windows_hotfix`, `windows_scheduled_task` |
| `port` | `port` |
| `param` | `kernel_param` |
| `key` | `registry` |
| `url` | `http` |
| none | `auditd`, `cron`, `firewall`, `security_policy`, `sshd_config`, `user_db`, `timesync`, `mac`, `boot_params` |

The last row is the label-only resources. Nothing on the target needs
addressing, because the check inspects a subsystem as a whole, so the check
name serves as the report label instead.

## Arguments reach the tool verbatim

A resource address is passed to the underlying tool exactly as written.
refpoint expands nothing, so `name = "nginx*"` reaches `systemctl` as `nginx*`,
and whether that matches anything is `systemctl`'s business.

Three consequences follow.

Pattern support differs between tools and platforms. `dpkg-query` accepts
shell-style patterns and others do not, so check the tool rather than assuming
the shell will help.

A name containing `*` or `[` is never expanded against the runner's working
directory, which would otherwise substitute unrelated filenames. Values are
single-quoted for POSIX shells and quote-doubled for PowerShell before they are
interpolated into a command.

`allowed_commands` gates which programs run, never which units or packages a
check inspects. Narrowing the subject of a check is the author's job.

## Privilege

Only the `command` resource is gated by `allowed_commands`. Every other
provider runs its own fixed commands through the transport, `ss`, `findmnt`,
`sshd -T`, `auditctl`, `getent`, PowerShell cmdlets, and so on, with arguments
shell-quoted. Those are part of the provider's contract rather than
user-supplied command lines, which is why the allowlist does not apply to them.

Some checks need root to mean anything. `user_db` reads `/etc/shadow`, and a
`file` check on `/etc/shadow` has to stat and read it. Pair those with
`--sudo`, or accept that they will error rather than silently pass.

## The pages

Resources are grouped by where they run. A control that uses a
platform-specific resource should carry a matching `platform` constraint, so it
is omitted on targets it does not apply to rather than erroring there.