The rule catalog

Conventions are what your repo does. The catalog is what the world says. The interesting page is the boundary between them, and this is it.

Opt-in, always

Nothing in the catalog runs until your organisation adopts it. Not one rule, not by default, not “just the critical ones”. A catalog rule that fired without being adopted would be a rule you did not choose appearing in your engineers’ pull requests, which is the behaviour that gets tools banned.

Browse the whole thing offline with garboard library list, or read the generated reference.

Re-expressed, not imported

This matters both legally and technically, so it is worth being precise.

Every catalog rule is written in Garboard’s own rule language, against Garboard’s own parser facts. No upstream code, policy file, Rego or Python was copied, translated or machine-converted. Titles and bodies are written here.

source_id — for example CKV_AWS_21 — is a citation, not content. It exists so that a security team can answer “does Garboard cover CKV_AWS_16?”, and so a future review can diff our coverage against upstream’s.

Sources credited

These projects are credited because they are the reason these controls are common knowledge, and because citing an identifier is only useful if you know which project it belongs to.

The adoption ladder

A rule moves through three states, and the middle one is the useful one:

Shadow is how you find out whether a rule is noisy without finding out the expensive way. The rule runs against real pull requests, its findings are recorded, and nobody sees a thing. A fortnight later you know exactly how often it would have fired and on what — and then you decide.

Adopting straight to live is available and is usually the wrong first move for anything you have not seen behave on your own code.

Profiles

A profile is a curated bundle — aws-security-baseline, for example — that adopts a set of rules in one action. garboard library profiles lists them; garboard gate --profile <name> enforces one in CI without adopting it at all, which is a good way to try one.

Profiles are pinned: the bundle contents and the catalog release they were curated against both move only through a reviewed change, because applying a profile turns N rules on for a whole organisation in one click and the contents of that N are not something to edit casually.

Recommendations

garboard library recommend ranks the catalog against what a repository actually contains, with the numbers behind each score. It is a suggestion — the CLI cannot see your organisation’s adoption decisions, so a rule you already adopted or declined still appears in the list.

We publish our own false positives

The catalog has at least one rule we know is wrong: lib.aws.kms_key_rotation fires on asymmetric KMS keys, which cannot rotate. It is named on the gauntlet page with the reason it is not yet fixed.

A catalog that never admits a bad rule is a catalog nobody has measured.