1---
2layout: page
3title: Guidance Catalog Guide
4description: Step-by-step guide to creating Gemara-compatible guidance catalogs
5---
6
7## What This Is
8
9This guide walks through creating a **Guidance Catalog** using the [Gemara](https://gemara.openssf.org/) project.
10
11**The basic idea:** A Guidance Catalog is a structured set of **guidelines**—recommendations, requirements, or best practices—that help readers achieve desired outcomes. Guidelines are grouped into **groups**.
12
13In technical terms:
14* **[Guidance catalogs](../../model/02-definitions.html#guidance)** have a **type** (Standard, Regulation, Best Practice, or Framework), **groups** that group guidelines by theme, and **guidelines** with an **objective**, optional recommendations, and optional references to other guidelines within the *same* guidance catalog.
15* **Guidelines:** state the intent and context; they have statements which act as sub-requirements of the guideline (e.g., `ORG.SSD.001` and statements.id `ORG.SSD.001.1`). The guidance includes a see-also for linking other guidelines within the same guidance catalog (e.g., `ORG.SSD.001` see-also `ORG.SSD.002`, `ORG.SSD.003`).
16* **Guidelines** have the ability to be mapped to external guidance (e.g., OWASP, NIST, HIPAA, GDPR, CRA, PCI, ISO) and to controls in a *separate* **Mapping Document**. Downstream Gemara Layers can reference `guidelines`, defining support for specific controls.
17
18See the [Mapping Document Guide](../mapping/mapping-document-guide) to create a mapping between two artifacts (e.g., your guidance catalog and an external framework).
19
20**Who might write guidance:** Authors can represent **internal** teams (unique organizational circumstances), **industry groups** (e.g., OWASP Top 10, PCI standards), **government agencies** (e.g., NIST Cybersecurity Framework, HIPAA), or **international standards bodies** (e.g., GDPR, CRA, ISO). Compliance professionals can use Gemara as a logical model for categorizing and mapping compliance activities to these sources.
21
22## Walkthrough
23
24### Step 0: Define Scope and Catalog Type
25
26Choose the scope of your guidance (e.g., secure development, supply chain, data protection) and the **catalog type** that best fits intent:
27
28| Type | When to use |
29|----------------|-----------------------------------------------------------------------------|
30| `Standard` | Formal, normative specifications (e.g., ISO 27001, PCI-DSS, NIST 800-53) |
31| `Regulation` | Legal or regulatory requirements (e.g., HIPAA, GDPR, CRA) |
32| `Best Practice`| Non-mandatory recommendations (e.g., internal playbooks, OWASP-style) |
33| `Framework` | High-level structure or taxonomy (e.g., NIST CSF) |
34
35You can later add `mapping-references` to external documents and use a [Mapping Document](https://gemara.openssf.org/schema/mappingdocument.html) to align those sources (walkthrough: [Mapping Document Guide](../mapping/mapping-document-guide)).
36
37### Step 1: Setting Up Metadata
38
39Declare your catalog and, if you will reference external standards, add mapping references. Key fields:
40
41| Field | What It Is | Why |
42|-------------------------------|----------------------------------------------------------------------------|---------------------------------------------------------------------|
43| `title` | Display name for the guidance catalog (top-level) | Human-readable label in reports and tooling |
44| `type` | One of Standard, Regulation, Best Practice, Framework (catalog intent) | Required by schema; clarifies intent |
45| `metadata.id` | Unique identifier for this catalog | Used when other artifacts reference this catalog |
46| `metadata.type` | Artifact kind (e.g. `GuidanceCatalog`) | Required by schema; identifies the Gemara artifact type |
47| `metadata.gemara-version` | Gemara specification version (e.g. `"1.2.0"`) | Required by schema; declares which spec the artifact conforms to |
48| `metadata.description` | High-level summary of purpose and scope | Required by schema; human-readable catalog summary |
49| `metadata.author` | Actor responsible for the artifact (`id`, `name`, `type`, …) | Required by schema; identifies ownership or authorship |
50| `metadata.mapping-references` | Pointers to external standards (e.g., OWASP, NIST) | Optional; resolve IDs used in external Mapping Document on guidelines |
51| `metadata.applicability-groups` | List of groups (id, title, description) for when guidelines apply | Optional; define scope so guidelines reference these ids in `applicability` |
52
53Other optional metadata fields (e.g. `version`, `date`, `draft`, `lexicon`) are documented under [#Metadata](https://gemara.openssf.org/schema/metadata.html).
54
55**Example (YAML):**
56
57```yaml
58title: Secure Software Development Guidance
59metadata:
60 id: ORG.SSD.001
61 type: GuidanceCatalog
62 gemara-version: "1.2.0"
63 description: Internal secure development and supply chain security guidelines (dependencies, images, and development practices) aligned to industry standards
64 version: 1.0.0
65 author:
66 id: example
67 name: Example
68 type: Human
69 mapping-references:
70 - id: OWASP
71 title: OWASP Top 10
72 version: "2021"
73 url: https://owasp.org/Top10
74 description: OWASP Top 10 Web Application Security Risks
75 applicability-groups:
76 - id: containerized_workloads
77 title: Containerized Workloads
78 description: Guidelines that apply to container-based deployments and images.
79 - id: ci_cd
80 title: CI/CD
81 description: Guidelines that apply in continuous integration and deployment pipelines.
82 - id: github_repositories
83 title: GitHub Repositories
84 description: Guidelines that apply to projects using GitHub for source and collaboration.
85type: Best Practice
86```
87
88> **Minimal Mapping Document example:** A Mapping Document that maps this guidance catalog’s guidelines to OWASP Top 10 (source `ORG.SSD.001`, target `OWASP`) is in [mapping-document.yaml](../mapping/mapping-document.yaml).
89
90### Step 2: Define Groups
91
92**Groups** group guidelines by theme. The Guidance Catalog schema requires at least one group when the catalog defines `guidelines`. Each guideline's `group` field must match the `id` of one of these groups (id, title, description).
93
94**Example (YAML):**
95
96```yaml
97groups:
98 - id: ORG.SSD.FAM01
99 title: Secure Dependencies and Supply Chain
100 description: Guidelines for selecting, updating, and verifying dependencies and images.
101```
102
103### Step 3: Define Guidelines
104
105**Guidelines** are the core content. Required fields for each guideline (see `guidancecatalog.cue`):
106
107| Field | Required | Description |
108|-------------|----------|----------------------------------------------------------|
109| `id` | Yes | Unique identifier (e.g., `ORG.SSD.GL01`) |
110| `title` | Yes | Short name for the guideline |
111| `objective` | Yes | Unified statement of intent |
112| `group` | Yes | `id` of a group in this catalog |
113| `state` | Yes | Lifecycle: `Active`, `Draft`, `Deprecated`, or `Retired` (must match this casing) |
114
115Optional: `recommendations`, `rationale`, `vectors`,`extends`, `applicability`, and others (see `guidancecatalog.cue`).
116
117**Applicability:** When you define `metadata.applicability-groups` in Step 1, use those group **ids** in each guideline’s `applicability` list (e.g. `["containerized_workloads", "ci_cd"]`). That keeps applicability consistent and documented.
118
119**Example (YAML):** The following guidelines illustrate supply chain security for dependencies and images (artifact integrity, source/code integrity, and secure transit):
120
121```yaml
122guidelines:
123 - id: ORG.SSD.GL01
124 title: Prefer Immutable Image References
125 objective: |
126 Use digest-based or immutable references for container images to prevent
127 tampering and ensure repeatable deployments.
128 group: ORG.SSD.FAM01
129 state: Active
130 recommendations:
131 - Prefer pull-by-digest over tags for production.
132 - Pin base image digests in Dockerfiles or equivalent.
133 applicability: ["containerized_workloads", "ci_cd"]
134 see-also:
135 - ORG.SSD.GL02
136 - ORG.SSD.GL03
137 - id: ORG.SSD.GL02
138 title: Prefer GitHub Branch Protection Rules
139 objective: |
140 Use branch protection so only approved changes reach the main branch and
141 malicious code cannot be merged without review.
142 group: ORG.SSD.FAM01
143 state: Active
144 recommendations:
145 - Prefer pull requests submitted from fork branch.
146 - Required maintainer/non-author review and approval for merge.
147 - Prefer GitHub Actions Quality checks in CI on pull request.
148 applicability: ["containerized_workloads", "ci_cd", "github_repositories"]
149 see-also:
150 - ORG.SSD.GL01
151 - id: ORG.SSD.GL03
152 title: Prefer VPN on Untrusted Networks
153 objective: |
154 Use a VPN on untrusted networks to protect traffic from interception and
155 DNS spoofing.
156 group: ORG.SSD.FAM01
157 state: Active
158 recommendations:
159 - Use a VPN for registry and build traffic on untrusted networks.
160 applicability: ["containerized_workloads", "ci_cd"]
161 see-also:
162 - ORG.SSD.GL02
163```
164
165### Step 4: Validate
166
167The catalog must conform to Guidance Catalog Definition defined in the CUE module. Validate with CUE:
168
169**Validation commands:**
170
171Using the **published** module:
172
173```bash
174go install cuelang.org/go/cmd/cue@latest
175cue vet -c -d '#GuidanceCatalog' github.com/gemaraproj/gemara@v1 your-guidance.yaml
176```
177
178To validate against the rolling tip of the default branch instead, use `github.com/gemaraproj/gemara@latest`.
179
180### Minimal Full Example
181
182A complete, schema-valid copy of this catalog is in [guidance-example.yaml](guidance-example.yaml) in this directory. Combined minimal catalog:
183
184```yaml
185title: Secure Software Development Guidance
186metadata:
187 id: ORG.SSD.001
188 type: GuidanceCatalog
189 gemara-version: "1.2.0"
190 description: Internal secure development and supply chain security guidelines (dependencies, images, and development practices) aligned to industry standards
191 version: 1.0.0
192 author:
193 id: example
194 name: Example
195 type: Human
196 mapping-references:
197 - id: OWASP
198 title: OWASP Top 10
199 version: "2021"
200 url: https://owasp.org/Top10
201 description: OWASP Top 10 Web Application Security Risks
202 applicability-groups:
203 - id: containerized_workloads
204 title: Containerized Workloads
205 description: Guidelines that apply to container-based deployments and images.
206 - id: ci_cd
207 title: CI/CD
208 description: Guidelines that apply in continuous integration and deployment pipelines.
209 - id: github_repositories
210 title: GitHub Repositories
211 description: Guidelines that apply to projects using GitHub for source and collaboration.
212type: Best Practice
213front-matter: Example best-practices text for tutorials developed by Gemara maintainers.
214groups:
215 - id: ORG.SSD.FAM01
216 title: Secure Dependencies and Supply Chain
217 description: Guidelines for selecting, updating, and verifying dependencies and images.
218
219guidelines:
220 - id: ORG.SSD.GL01
221 title: Prefer Immutable Image References
222 objective: |
223 Use digest-based or immutable references for container images to prevent
224 tampering and ensure repeatable deployments.
225 group: ORG.SSD.FAM01
226 state: Active
227 recommendations:
228 - Prefer pull-by-digest over tags for production.
229 - Pin base image digests in Dockerfiles or equivalent.
230 applicability: ["containerized_workloads", "ci_cd"]
231 see-also:
232 - ORG.SSD.GL02
233 - ORG.SSD.GL03
234 - id: ORG.SSD.GL02
235 title: Prefer GitHub Branch Protection Rules
236 objective: |
237 Use branch protection so only approved changes reach the main branch and
238 malicious code cannot be merged without review.
239 group: ORG.SSD.FAM01
240 state: Active
241 recommendations:
242 - Prefer pull requests submitted from fork branch.
243 - Required maintainer/non-author review and approval for merge.
244 - Prefer GitHub Actions Quality checks in CI on pull request.
245 applicability: ["containerized_workloads", "ci_cd", "github_repositories"]
246 see-also:
247 - ORG.SSD.GL01
248 - id: ORG.SSD.GL03
249 title: Prefer VPN on Untrusted Networks
250 objective: |
251 Use a VPN on untrusted networks to protect traffic from interception and
252 DNS spoofing.
253 group: ORG.SSD.FAM01
254 state: Active
255 recommendations:
256 - Use a VPN for registry and build traffic on untrusted networks.
257 applicability: ["containerized_workloads", "ci_cd"]
258 see-also:
259 - ORG.SSD.GL02
260```
261
262## What's Next
263
264Map guidelines to Layer 2 controls via control catalogs’ `guidelines`, or reference this guidance from a Policy. See the [Guidance Catalog schema](https://gemara.openssf.org/schema/guidancecatalog.html) for optional fields.