# Add scorecard rules

Scorecard rules run while Kix evaluates a cluster. Every built-in rule set
runs by default. Narrow the set when you want fewer checks, and add custom
rules for policy specific to your packages or organization.

This guide assumes the cluster is defined with `kix.buildCluster`.

## Choose the built-in rule sets

`scorecard.rules` defaults to `kix.rules`, the four built-in categories:
`security`, `reliability`, `governance`, and `architecture`. Setting the
option replaces that default, so name every set you want to keep:

```nix title="cluster.nix"
scorecard.rules = {
  inherit (kix.rules) security reliability;
};
```

The attribute name becomes the rule category. For example,
`kix.rules.reliability.hasProbes` is reported as `reliability.hasProbes`.

To keep the whole built-in set and change one rule, leave `rules` alone and
use an override instead. See
[Disable scorecard rules](/docs/how-to/policy-ci-and-compliance/disable-scorecard-rules/)
and
[Override scorecard severity](/docs/how-to/policy-ci-and-compliance/override-scorecard-severity/).

## Add a custom rule

Place custom rules under a category of your own. This tested package-level
rule applies only to packages that advertise the `reverse-proxy` capability,
then checks their evaluated configuration:

<Snippet {...packageRule} />

Add the rule inside `scorecard.rules`. Its full name is
`custom.proxyMaxBodySizeMustBeExplicit`. Because setting `rules` replaces the
default, merge the custom category into the built-in set to keep both:

```nix title="cluster.nix"
scorecard.rules = kix.rules // {
  custom.proxyMaxBodySizeMustBeExplicit = { /* the rule above */ };
};
```

Every rule declares a `level` that determines the value passed to its check:

- `manifest` runs once for each rendered Kubernetes resource.
- `package` runs once for each package instance.
- `namespace` runs once for each namespace.
- `cluster` runs once for the whole cluster.

Kix accepts only these four levels and three severities: `info`, `warning`, and
`error`. Evaluation rejects any other value. This prevents misspelled levels
from creating rules that never run, and misspelled severities from being
treated as warnings.

The check returns one finding for each problem and an empty list when the
input passes. Use `appliesTo` when a rule is meaningful only for a subset of
its level.

## Check the rules

Run the cluster checks after adding or changing a rule:

<Command {...check} />

Kix reports the number of scorecard errors, warnings, and informational
findings. Every finding is capped at `scorecard.maxSeverity`, which defaults
to `warning`, so a new cluster prints what the rules found and still builds.
With the cap raised to `error`, an error-severity finding becomes a failed
assertion: evaluation stops at the first error, the cluster does not build,
and only that finding is reported. Warnings and informational findings are
collected across the cluster and reported together. See
[Fail the build on scorecard findings](/docs/how-to/policy-ci-and-compliance/fail-the-build-on-scorecard-findings/)
for the cap.

:::note[Reference]
See [Rule schema](/docs/reference/scorecard/rule-schema/) for the context
available at each level and the complete rule fields. The built-in rule pages
list the checks available in each category.
:::