Manifest Reference

The manifest is the YAML frontmatter at the top of recipe.md. It’s the public contract between recipe authors and pretorin. The schema is defined by the pydantic models in src/pretorin/recipes/manifest.py and frozen per contract_version.

Minimal Example

---
id: my-first-recipe
version: 0.1.0
name: "My First Recipe"
description: "Capture the active IAM role's trust policy and attach it as a configuration record."
use_when: "The agent needs evidence that an IAM role's trust policy meets least-privilege requirements."
produces: evidence
author: "Jane Doe"
license: Apache-2.0
scripts:
  capture:
    path: scripts/capture.py
    description: "Pull the trust policy from AWS and return it as a redacted dict."
---

# My First Recipe Body

The agent reads everything below the closing `---` to understand what to do.

Required Fields

Optional Fields

Tier

tier is set by the loader from the recipe’s source path, overriding whatever the manifest declares:

• Built-in path → official
• User folder, project folder, explicit path → community
• partner → reserved for installed packages (v1.5)

Authors should still declare a tier — it documents intent, and any manifest-internal validation runs against the declared value.

Params

Recipe-level params are inputs the calling agent supplies via pretorin_start_recipe(...). They flow through to scripts as kwargs.

params:
  stig_id:
    type: string
    description: "STIG benchmark id targeting Linux baseline controls"
    required: true
  target:
    type: string
    description: "Optional connection string (e.g., 'ssh://host')"
    default: "local"

Supported types: string, integer, number, boolean, array. For array, declare items: { type: ... } so the MCP renderer can emit a real JSON Schema.

Requires

Document the runtime environment the recipe needs. v1 captures the requirements but does not run probes — the v1.5 pretorin recipe check will. Failures surface at runtime when scripts try to invoke missing tools.

requires:
  cli:
    - { name: inspec, probe: "inspec --version" }
    - { name: jq, probe: "jq --version" }
  env:
    - AWS_PROFILE
    - INSPEC_TARGET

Attests

attests is a list of {control, framework} entries the recipe is likely relevant to. It’s a hint for filtering, never a binding — the agent picks recipes by reading description and use_when, not by joining on attests.

attests:
  - { control: AC-2, framework: nist-800-53-r5 }
  - { control: AC-6, framework: nist-800-53-r5 }

Scripts

Each ScriptDecl becomes an MCP tool:

scripts:
  run_scan:
    path: scripts/run_scan.py
    description: "Pull the manifest, run the scan, return per-rule results."
    params:
      stig_id:
        type: string
        description: "STIG benchmark id"
        required: true
      target:
        type: string
        description: "Connection string"
    timeout_seconds: 600
    writes_evidence: false

The MCP tool name for this script is pretorin_recipe_<safe_id>__run_scan, where safe_id is the recipe id with hyphens converted to underscores (MCP tool names can’t contain hyphens). The recipe author doesn’t construct this name — pretorin does.

Contract and Schema Versioning

Two version fields exist for forward compatibility:

• contract_version — bumps only on backwards-incompatible shape changes to the frontmatter itself. Most recipes pin to 1.
• recipe_schema_version — the schema this specific recipe is written against. The loader refuses to load a recipe whose schema is newer than what the running pretorin supports, with a hint to upgrade.

min_pretorin_version lets a recipe author require a specific runtime version (e.g., when a recipe uses a writer tool that only exists in pretorin ≥ 0.18).

What the Loader Does to Your Manifest

1. Parses the YAML frontmatter.
2. Validates against the pydantic schema. A failure raises RecipeManifestError for that recipe — the registry keeps loading other recipes.
3. Overrides tier from the source path (built-in → official, otherwise community).
4. Caches the parsed manifest by (path, mtime). If you edit the file, the next load re-parses it.