Organisations
A company has more than one level of policy: what security or platform require of every repository, what a business unit or a team adds, and what a repository decides for itself. fleetlint models that with catalogs that build on each other, applied in the order they are listed, and labelled by whoever owns them.
This page follows the order an administrator sets things up in: write the catalog, publish and pin it, name it in a sources file, enforce it in CI, then look at the whole fleet.
The setup in one example
A standards repository at https://git.example.com/platform/standards.git:
sources.yaml what every repository runs
org/catalog.yaml the organisation's catalog
org/rules/deps/unused-check/ruby.yaml an implementation the presets lack
org/templates/SECURITY.md replaces the preset's security policy template
org/catalog.yaml:
apiVersion: fleetlint.org/v1
kind: Catalog
metadata:
name: acme-baseline
version: 1.0.0
engine: 7
label: org # who owns it; reports attribute by it
catalog: { version: v0.8.0 } # the fleetlint catalog it builds on
includes: ["fleetlint:recommended"]
rules:
- use: deps/unused-check # with the Ruby implementation from rules/
- id: acme/owner-file
title: Every repository names its owning team
kind: expr
severity: error
expr: file("OWNERS")
message: "OWNERS is missing"
requirement: An OWNERS file names the team responsible for the repository.
fix: { human: "Add OWNERS with the team's handle." }
overrides:
repo/no-tracked-env: { locked: true, exceptions: false }
ci/actions-pinned: { severity: error, min_severity: warning }
exception_policy:
max_days: 90
require_approver: true
org/rules/deps/unused-check/ruby.yaml states only its check; the rest comes from the capability in fleetlint’s library:
id: deps/unused-check/ruby
kind: outcome
satisfiers:
- name: our-tool
expr: workflows().exists(w, steps(w).exists(s, s.run.contains("bin/unused-gems")))
sources.yaml pins the catalog by the commit that last changed org/. A commit cannot name itself, so the pin moves in a commit of its own:
# sources.yaml
version: 1
catalog: { version: v0.8.0 } # the fleetlint catalog every repository runs
extends: [org] # the baseline every repository gets
catalogs:
org: git+https://git.example.com/platform/standards.git//org/catalog.yaml@<commit>
Each repository names the sources file, pinned the same way:
version: 1
sources: git+https://git.example.com/platform/standards.git//sources.yaml@<commit>
The organisation’s CI template runs the check and insists on the baseline. fleetlint fetches the standards repository with git’s own credentials, so the runner needs read access to it (a deploy key, a credential helper):
# .github/workflows/fleetlint.yml; GitHub, Gitea and Forgejo Actions
name: fleetlint
on: [push, pull_request]
permissions: { contents: read }
jobs:
fleetlint:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with: { persist-credentials: false }
- run: curl --proto '=https' --tlsv1.2 -fsSL https://fleetlint.org/install.sh | sh -s -- v0.11.1
- run: ~/.local/bin/fleetlint check --require org
Every repository now runs fleetlint:recommended, the organisation’s rule and its Ruby implementation, and fleetlint fix writes the organisation’s SECURITY.md. Nothing loaded after org can unlock, lower or except repo/no-tracked-env, take ci/actions-pinned below warning, or write an exception without an approver and a date at most 90 days ahead. A repository that drops the sources file fails in CI.
Your own catalog
A catalog is a YAML file in the format of the presets. In the example:
labelsays who owns it:org,team/mobile,security-team, any name. Reports attribute the catalog’s rules, locks, lowered severities and exceptions to it. It does not order anything, and--requiredoes not match it. A catalog without one is labelled by the sources-file name it is loaded under, else by its own name.catalognames the fleetlint catalog version that its presets and itsuse:selections come from. A remote catalog that includes presets or uses the library must state it, and a run on another version fails. The sources file sets that version for every repository.includesloads other catalogs first. A remote catalog includes presets and pinned references (https, git,oci://) only; a sources-file name such asorgworks inextends, not here.rulesadds rules of its own (writing rules) and selects library rules withuse:, one family or one rule at a time, without taking all of a preset:
rules:
- use: release/*
- use: slop/focused-tests
overridesadjust the included rules and set policy on them (below).exceptionsare the same as a repository’s, granted to every repository that extends the catalog, and bound by its ownexception_policy.fleet.jsonrecords the catalog that granted one in the exception’slabelandwhere.
exceptions:
- { rule: repo/no-tracked-junk, match: "fixtures/*.log", reason: "parser fixtures across the fleet" }
Catalogs apply in the order they are listed: the sources file’s extends first, then the repository’s, and an include always before the catalog that includes it. Policy only tightens, so a catalog binds every catalog after it. A team catalog that must come after the organisation’s includes it by its pinned reference; an organisation that must come first everywhere puts its catalogs in the sources file’s extends. How rules combine has the full account, and fleetlint hierarchy prints the order of a run.
A catalog loaded over https, git or OCI can add and tighten rules, use the built-in fix templates and every function in the CEL reference. It cannot declare rules that execute commands; only a repository’s own configuration and catalog files in the repository can.
Overrides in a catalog
A catalog that builds on another does not restate a rule to change it. Next to rules: it lists overrides: for the rules its includes brought in:
apiVersion: fleetlint.org/v1
kind: Catalog
metadata:
name: acme-baseline
version: 1.1.0
engine: 7
catalog: { version: v0.8.0 }
includes: ["fleetlint:recommended"]
overrides:
repo/no-tracked-env: { locked: true, exceptions: false }
ci/actions-pinned: { severity: error, min_severity: warning }
taskrunner/targets: { params: { required: [lint, test, check] } }
deps/vulnerability-scan: { accept: [{ name: acme-scan, expr: 'taskrunner.file != "" && text(taskrunner.file).contains("acme-scan")' }] }
docs/adr-directory: { enabled: false, reason: "decisions are kept in the wiki" }
public/license: { when: "true" } # whatever the detected visibility
docs/architecture: { tiers: [1, 2] }
"release/*": { locked: true } # a pattern: the whole family
"*": { raise: 1 } # every included rule one step stricter
- A key is a rule id or a pattern over ids:
"*"is every included rule,"release/*"a family. Patterns apply first, exact ids refine them.raise: 1lifts whatever matches one severity step (info → warning → error, capped at error).fleetlint:strictis written this way:"*": {raise: 1}plusexceptions: falseon the security rules. severity,params,acceptandenabledwork as in a repository’soverrides:block, including the need for areasonwhen a rule is disabled or its severity lowered. Such changes appear in every report with the catalog’s label.whenandtiersreplace the rule’s applicability:when: "true"makes a conditional rule unconditional (this is howfleetlint:ossswitches thepublic/*family on),tierswidens or narrows the tiers it applies to. A locked rule refuses both.- The rule keeps the catalog it came from as its source and follows that catalog’s later improvements;
explainand the reports name the catalog that set the policy. - An override for a rule that no earlier catalog defines is an error, as is one for a rule the same catalog defines: the catalog changes its own rules directly.
Locks and floors
Three overrides constrain everything loaded after the catalog: later catalogs, the repository, its scopes and nested files. A catalog sets the same fields on a rule it defines itself.
overrides:
repo/no-tracked-env: { locked: true, exceptions: false } # an absolute rule
ci/actions-pinned: { severity: error, min_severity: warning }
| Policy | What is loaded later cannot | It can still |
|---|---|---|
locked: true | disable the rule, lower its severity, change when, tiers, params or accept, or redefine it | raise the severity; add a reasoned exception unless exceptions are forbidden |
min_severity: <severity> | disable the rule, or set its severity below the floor | lower it to the floor, with a reason; change when, tiers, params, accept |
exceptions: false | add an exception for the rule, or disable it | change its severity (lowering needs a reason), when, tiers, params, accept |
exceptions: false forbids disabling because disabling is the widest exception; reserve it for the few absolute rules. Under fleetlint:strict the security rules can therefore be neither excepted nor disabled. Policy only tightens: a rule an earlier catalog locked cannot be unlocked, a floor cannot be lowered, and exceptions that were forbidden cannot be allowed again.
A violation is a configuration error when the configuration loads (exit 2), never a weaker check at run time, and it names the catalog that set the policy:
fleetlint: .fleetlint.yaml: rules.repo/no-tracked-env: rule is locked by acme-baseline@1.0.0 and cannot be disabled
fleetlint: .fleetlint.yaml: rules.ci/actions-pinned: acme-baseline@1.0.0 set a severity floor of warning; off is below every floor
fleetlint: .fleetlint.yaml: exceptions: rule repo/no-tracked-env forbids exceptions (set by acme-baseline@1.0.0)
Locks hold only for catalogs that are loaded; enforcing the baseline makes sure they are.
Stacks and per-stack rules
Your catalog uses the stacks of the fleetlint catalog it builds on (stacks/ at the version in metadata.catalog): detection, repo.stacks and the dev environment fleetlint fix writes come from there, so it never redefines Go or Node. On top of them it can:
- scope its own rules to a stack with
stacks: [go]; a stack id the base does not define fails the load; - select a capability with all its implementations (
use: lint/configured) or adjust one stack (overrides: {lint/configured/go: ...}); - add or replace an implementation of a base capability, as
org/rules/deps/unused-check/ruby.yamldoes in the example. The catalog must ship itsrules/directory (anoci://artifact or a git tree pinned to a full commit SHA), and the implementation applies where the catalog selects it withuse:, the capability or the implementation’s own id.
What it cannot do is define a stack. A stack fleetlint does not ship (Terraform, an in-house language) needs its definition in stacks/ of the catalog version the run uses: a fork of fleetlint/catalog, pinned with catalog: {repo: ..., version: ...}. Capabilities and stacks explain the formats.
Publishing and pinning
A repository or a sources file references a catalog in one of these forms; fleetlint catalog digest catalog.yaml prints the digest of a file.
| Reference | Pinned by | Ships rules/ and templates/ |
|---|---|---|
./standards/catalog.yaml, or a directory of *.yaml, inside the repository | the repository’s own history | no |
https://standards.example.com/catalog.yaml#sha256-<hex> | the digest | no |
git+https://git.example.com/platform/standards.git//org/catalog.yaml@v1.0.0#sha256-<hex> | a tag and the digest of the catalog file | no, and the run warns when they exist |
git+https://git.example.com/platform/standards.git//org/catalog.yaml@<commit> | a full commit SHA | yes, the directories next to the catalog file |
oci://ghcr.io/acme/fleetlint-catalog@sha256:<digest>, or a tag with signers | the artifact digest, or a verified signature | yes |
- An https catalog is fetched over https only, follows redirects only within the same host, times out after 20 seconds and refuses bodies over 2 MiB. The digest, not the transport, is what makes the content trusted.
- A git catalog is
git+<url>//<path>@<revision>, with an https or ssh URL. It is fetched with the credentials git already has (credential helper, ssh agent), so private repositories work. The revision is a tag or a full commit SHA, never a branch. A tag can be moved, so it must carry#sha256-<hex>, and a moved tag fails the digest check. That digest covers the catalog file only, which is why a tag pin ships neitherrules/nortemplates/; the run says so on stderr:rules/ and templates/ ignored: a git catalog pinned to a tag ships only its catalog file; pin a full commit SHA to ship them. - A git fetch times out after two minutes. Files over 2 MiB are refused, and so is a catalog directory with its
templates/andrules/over 16 MiB or 512 files. - Catalogs are fetched on every run, hooks included. A catalog that cannot be fetched is a configuration error (exit 2). Only the
catalog:version pin is kept in a cache. - Catalogs fetched over https, git or OCI are untrusted: they cannot declare command rules, and include only presets and other pinned references. A catalog file in the repository is trusted like the repository’s own configuration.
Catalogs from a registry: oci://, signatures, private templates
An organisation that runs a container registry can publish its catalog as an OCI artifact and sign it, so repositories pin a signer instead of a digest and a new catalog version needs no change in any repository:
oras push ghcr.io/acme/fleetlint-catalog:3.2.0 catalog.yaml templates/SECURITY.md templates/pre-commit/head.yaml
cosign sign --new-bundle-format ghcr.io/acme/fleetlint-catalog@sha256:<digest> # keyless, from the publishing workflow
# sources.yaml
version: 1
signers:
- issuer: https://token.actions.githubusercontent.com
subject_regex: '^https://github\.com/acme/standards/\.github/workflows/publish\.yml@refs/tags/v'
catalogs:
org: oci://ghcr.io/acme/fleetlint-catalog:3
team/platform: oci://ghcr.io/acme/fleetlint-catalog@sha256:<digest>
team/mobile:
ref: oci://ghcr.io/acme/mobile-catalog:2
signers:
- issuer: https://token.actions.githubusercontent.com
subject_regex: '^https://github\.com/acme/mobile-standards/\.github/workflows/publish\.yml@refs/tags/v'
min_version: 2.4.0
- An
oci://<registry>/<repository>:<tag>reference is accepted only when signers are listed for it, in the sources file’ssignersor on the entry itself; a@sha256:<digest>reference needs none. When signers are listed, the signature is verified for everyoci://catalog, digest or not. - A
catalogs:entry is the reference, or{ref, signers, min_version}.signerson an entry verify that catalog alone and replace the top-levelsignersfor it, so a team that publishes from its own repository is trusted for its own catalog and for nothing else. An entry withoutsignerskeeps the top-level ones, which also verify thecatalog:pin.signersare allowed only on anoci://reference; on any other the sources file is refused. min_versionis a floor on the loaded catalog’smetadata.version(a semantic version, with or without a leadingv): a catalog below it fails the run, naming the alias, the loaded version and the floor. A tag such as:3follows the publisher, so the floor is how every repository notices the tag being moved back to an older release. Withmin_version, a catalog whosemetadata.versionis not a semantic version fails the run, since the floor cannot be checked.- A signer is an OIDC
issuerplus the certificatesubject, exact or assubject_regex. For GitHub Actions the subject is the workflow reference (https://github.com/<owner>/<repo>/.github/workflows/<file>@refs/tags/<tag>); for a person signing withcosign signit is their e-mail withissuer: https://accounts.google.comor another identity provider. Verification uses the sigstore public-good instance: the certificate chain, the transparency-log entry or a signed timestamp, and the certificate’s signed certificate timestamp. The bundle must be attached to the artifact in the sigstore bundle format (cosign sign --new-bundle-format, cosign 2.5 or later); the older.sigtag layout is not read. - Every layer of the artifact with an
org.opencontainers.image.titleannotation is a file, which is whatoras push <ref> <files...>produces. Files named*.yamlat the root are catalogs, loaded in name order. Files underrules/are the catalog’s library. Files undertemplates/are fix templates that travel with the catalog:fleetlint fixtakes them before the preset’s templates (the lookup order is in writing rules), so the organisation’sSECURITY.md, hook fragments or workflow head replace the public ones without a fork of fleetlint. A template is written only from a catalog that was pinned or whose signature was verified, and the fix plan names the catalog each such change comes from ((template from catalog oci://...)), since a template can become a hook or a workflow. - The registry is read with the credentials docker or oras already stored (
docker login,oras login, credential helpers). Registries on exactlylocalhost,127.0.0.1or::1, on any port, are spoken to over plain http, as in tests;localhost.example.comis not. Signature lookup reads at most 32 referrers of an artifact and 8 bundle layers per referrer, and fetching the sigstore trust root stops after two minutes. - A sources file cannot come from a registry: it is the trust anchor, so it stays a local path, an https URL with a digest or a git reference.
- Without a registry, a git tree pinned to a full commit SHA ships
rules/andtemplates/the same way, from the directories next to the catalog file. That is the example at the top:org/templates/SECURITY.mdmakesfleetlint fixwrite the organisation’s security policy.
Names: the sources file
Repositories should not carry URLs and pins for every catalog. An organisation publishes one sources file that names its catalogs:
# sources.yaml
version: 1
catalog: { version: v0.8.0 } # the fleetlint catalog version every repository runs (or {oci: ghcr.io/fleetlint/catalog:v0.8.0})
extends: [fleetlint:recommended, org, compliance/pci] # the baseline every repository gets, in this order, before its own extends
catalogs:
org: git+https://git.example.com/platform/standards.git//org/catalog.yaml@<commit>
compliance/pci: oci://ghcr.io/acme/compliance-catalog@sha256:<digest>
bu/payments: git+https://git.example.com/payments/standards.git//catalog.yaml@v1.4.0#sha256-<hex>
team/platform: git+https://git.example.com/platform/standards.git//teams/platform/catalog.yaml@<commit>
team/mobile: https://standards.example.com/teams/mobile.yaml#sha256-<hex>
A repository names it with sources: and adds only what is its own, such as extends: [team/platform].
- Names are lowercase words joined by
/(org,team/mobile,compliance/pci,bu/payments): any hierarchy the organisation has. Targets are presets, https catalogs with a digest, git oroci://catalogs. A sources file given as a local path may also name local paths, resolved relative to itself; a remote one may not. A catalog loaded under a name takes that name as its label unless it declares one. catalogis the one version of the fleetlint catalog for every repository; a repository may repeat it, not change it.extendsis the baseline: the repository’s ownextendsadds to it and cannot leave anything out. Only the catalogs that are extended are fetched.- The sources file itself is a local path, an https URL with a digest or a git reference, pinned the same way as a catalog. Rotating a catalog version is then one change to the sources file and one pin update per repository.
- The order is what is written: the sources file’s
extends, then the repository’sextends, then its own file, with every include before the catalog that includes it. A team catalog that includes the organisation’s can never come before it. Nothing is sorted by name or label. - Every rule carries the label of the catalog that brought it in (
preset,repo,org,team/mobile, …), the catalog that defined its text (source, the library for selected rules) and the catalog that selected it (selected_by).explainprints them, JSON has them on the rule, SARIF in the rule properties. The JSONcatalogslist,fleetlint hierarchyand the fleet report’s Catalogs section have every catalog of the run in order with its label, name, version and pin. - Locks and severity floors hold across catalogs: a later catalog cannot redefine a locked rule or set a severity below an earlier
min_severity, and the floor still binds the repository after a team redefines the rule. Every lowering, by whichever catalog, is recorded: underweakenedin JSON, and under Lowered severities in the fleet report with the label.
Enforcing the baseline
The sources file’s extends reaches every repository that names the file, but a repository can drop sources: or a catalog from extends. Enforcement belongs where the check runs: the organisation’s CI template and its fleet runs pass --require, as in the example.
--require orgnames a catalog by its sources-file name or itsmetadata.name, by its reference, or asref#sha256-<digest>for the exact content; the label does not count. A name counts only for a catalog fetched by digest, commit or signature: a file in the repository that calls itselforgdoes not satisfy it.- A repository whose configuration lacks a required catalog fails with exit 2 before any rule runs:
required catalog org is not part of the effective configuration (add it to extends). In fleet mode it becomes an error row. - The flag is global, so
fix,explainandbaselinerefuse under a weaker configuration too. - fleetlint’s GitHub Action and GitLab component have no input for it; a CI template that requires a catalog runs the binary, as the example does.
Exception policy
What an exception must say is set once, for every repository that extends the catalog:
exception_policy:
require_until: true # every exception has an expiry date
max_days: 90 # until is at most 90 days after the run (implies require_until)
require_approver: true # every exception names approved_by
- The policy binds the exceptions of the catalog that sets it and of everything loaded after it: later catalogs, the repository’s
.fleetlint.yaml, its scopes and nested files. - Policies of several catalogs add up, so a team catalog can tighten the organisation’s (a smaller
max_days) but never loosen it. - An exception that breaks the policy is a configuration error (exit 2) that names the exception’s rule and the catalogs whose policy it breaks:
exceptions: rule repo/readme-present: approved_by is required (exception policy of …). max_daysis counted from the day of the run, so an exception written for 90 days stays valid until it expires. An expired exception is no error; its findings simply count again.- The policy checks what an exception says, not who wrote it:
approved_byis a name fleetlint records without verifying, and the approval itself is the review of the change to.fleetlint.yaml.
The fleet view
fleetlint fleet checks every repository and writes one report: compliance per repository and per team, the repository-by-rule matrix, and three tables of what the fleet weakened. Disabled rules and Lowered severities name the label and the file of the catalog or configuration that made each change; Exceptions lists each with its team, reason, approver and deadline. Run it with --require org so a repository without the baseline shows up as an error. See fleet mode.