Write a control pack

A pack of your own is added exactly the way a shipped one is, and is held to the same checks first. Write one when the regime you are held to is not among the packs that ship, or when several deployments in the same organisation should decide the same way without anybody copying rules between documents.

Make the four files

A pack is one directory named for its id, holding pack.yaml, deployment.yaml, pistra.tests.yaml and README.md. Every field of each is in the format.

packs/acme-controls/
  pack.yaml           the id, the controls it cites, and their citations
  deployment.yaml     the detectors, guardrail rules and access rules
  pistra.tests.yaml   the suite that proves them
  README.md           scope, what it does not cover, what to decide first

The id is the namespace of the pack’s own controls. A rule in acme-controls cites acme-controls:… and nothing else, so two packs in one document cannot collide on an identifier neither author chose.

Declare a control before a rule cites it

Every control is declared once in pack.yaml with a title and a citation, and every declared control is named by a rule, an attachment or a mapping. A control nothing names is refused, and so is a rule citing one that was never declared.

controls:
  - id: acme-controls:retention-7y
    title: Records of a customer interaction are kept for seven years.
    citation: https://intranet.acme.example/policy/retention

The citation is where the text is. It is what lets somebody else check the reading, which is the only thing that makes a pack reviewable.

Add it, and let the checks run

add takes a directory path as readily as a built-in id, and verifies it before it merges anything.

$ pistra pack add -deployment deployment.yaml ./packs/acme-controls

It refuses the pack when a rule cites an undeclared control, when a guardrail rule omits requires, when deployment.yaml does not compile the way the gateway compiles it, when the suite fails, or when a rule is named by no case. Nothing is written until all of them pass. → Start from a control pack for what add reports and what happens the second time.

Build on a pack that ships

Name a shipped pack in depends and your pack is added after it. attach then puts your identifiers onto a rule that pack already carries, so one rule decides once and the record names both regimes.

depends: [sa-pdpl]
attach:
  - rule: sa-pdpl-national-id
    controls: [acme-controls:retention-7y]

An attachment names a rule of a pack in depends and never one of your own. Your own rules carry their controls directly.

Keep it where the deployments can reach it

The controls identifiers are the same opaque strings a governance platform writes, so a pack of your own and a platform’s source meet in the same field on the same records. An organisation with several business units writes its controls once and adds them to each unit’s document. → Connect your AI governance platform

What a pack cannot do

A pack sets detectors, guardrail rules and access rules and nothing else. Providers, credentials, keys, budgets, models and the guardrails block’s tuning are the deployment’s, and a pack that names one is refused. A pack is not a second configuration source either: its rules are copied into the document that owns them rather than layered beside it, and after add the pack is not consulted again.

The control pack format is every field and every check, generated from the packs directory. Control packs is what ships, and each one is a worked example of everything above.