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** 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
18> **Coming Soon:** Mapping Document Tutorial.
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 an **external** [Mapping Document](https://gemara.openssf.org/schema/mapping.html) (Tutorial Coming Soon) to align those sources.
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. `"0.20.0"`) | Required by schema; declares which spec the artifact conforms to |
48| `metadata.mapping-references` | Pointers to external standards (e.g., OWASP, NIST) | Resolve IDs used in external Mapping Document on guidelines. |
49| `metadata.applicability-groups` | List of groups (id, title, description) for when guidelines apply | Define scope so guidelines reference these ids in `applicability`; keeps applicability consistent and documented |
50
51**Example (YAML):**
52
53```yaml
54title: Secure Software Development Guidance
55metadata:
56 id: ORG.SSD.001
57 type: GuidanceCatalog
58 gemara-version: "0.20.0"
59 description: Internal secure development and supply chain security guidelines (dependencies, images, and development practices) aligned to industry standards
60 version: 1.0.0
61 author:
62 id: example
63 name: Example
64 type: Human
65 mapping-references:
66 - id: OWASP
67 title: OWASP Top 10
68 version: "2021"
69 url: https://owasp.org/Top10
70 description: OWASP Top 10 Web Application Security Risks
71 applicability-groups:
72 - id: containerized_workloads
73 title: Containerized Workloads
74 description: Guidelines that apply to container-based deployments and images.
75 - id: ci_cd
76 title: CI/CD
77 description: Guidelines that apply in continuous integration and deployment pipelines.
78 - id: github_repositories
79 title: GitHub Repositories
80 description: Guidelines that apply to projects using GitHub for source and collaboration.
81type: Best Practice
82```
83
84> **Minimal Mapping Document example:** A Mapping Document that maps this guidance catalog’s guidelines to OWASP Top 10 (source `ORG-SSD`, target `OWASP`) is in [mapping-document.yaml](mapping-document.yaml).
85
86### Step 2: Define Groups
87
88**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).
89
90**Example (YAML):**
91
92```yaml
93groups:
94 - id: ORG.SSD.FAM01
95 title: Secure Dependencies and Supply Chain
96 description: Guidelines for selecting, updating, and verifying dependencies and images.
97```
98
99### Step 3: Define Guidelines
100
101**Guidelines** are the core content. Required fields for each guideline (see `layer-1.cue`):
102
103| Field | Required | Description |
104|-------------|----------|----------------------------------------------------------|
105| `id` | Yes | Unique identifier (e.g., `ORG.SSD.GL01`) |
106| `title` | Yes | Short name for the guideline |
107| `objective` | Yes | Unified statement of intent |
108| `group` | Yes | `id` of a group in this catalog |
109| `state` | Yes | Lifecycle: `Active`, `Draft`, `Deprecated`, or `Retired` |
110
111Optional: `recommendations`, `applicability`, `rationale`, `statements`, `guidelines`, `vectors`, and others (see `layer-1.cue`).
112
113**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.
114
115**Example (YAML):** The following guidelines illustrate supply chain security for dependencies and images (artifact integrity, source/code integrity, and secure transit):
116
117```yaml
118guidelines:
119 - id: ORG.SSD.GL01
120 title: Prefer Immutable Image References
121 objective: |
122 Use digest-based or immutable references for container images to prevent
123 tampering and ensure repeatable deployments.
124 group: ORG.SSD.FAM01
125 state: active
126 recommendations:
127 - Prefer pull-by-digest over tags for production.
128 - Pin base image digests in Dockerfiles or equivalent.
129 applicability: ["containerized_workloads", "ci_cd"]
130 see-also:
131 - ORG.SSD.GL02
132 - ORG.SSD.GL03
133 - id: ORG.SSD.GL02
134 title: Prefer GitHub Branch Protection Rules
135 objective: |
136 Use branch protection so only approved changes reach the main branch and
137 malicious code cannot be merged without review.
138 group: ORG.SSD.FAM01
139 state: Active
140 recommendations:
141 - Prefer pull requests submitted from fork branch.
142 - Required maintainer/non-author review and approval for merge.
143 - Prefer GitHub Actions Quality checks in CI on pull request.
144 applicability: ["containerized_workloads", "ci_cd", "github_repositories"]
145 see-also:
146 - ORG.SSD.GL01
147 - id: ORG.SSD.GL03
148 title: Prefer VPN on Untrusted Networks
149 objective: |
150 Use a VPN on untrusted networks to protect traffic from interception and
151 DNS spoofing.
152 group: ORG.SSD.FAM01
153 state: Active
154 recommendations:
155 - Use a VPN for registry and build traffic on untrusted networks.
156 see-also:
157 - ORG.SSD.GL02
158```
159
160### Step 4: Validate
161
162The catalog must conform to the Guidance Catalog Definition defined in the CUE module. Validate with CUE:
163
164**Validation commands:**
165
166Using the **published** module:
167
168```bash
169go install cuelang.org/go/cmd/cue@latest
170cue vet -c -d '#GuidanceCatalog' github.com/gemaraproj/gemara@latest your-guidance.yaml
171```
172
173### Minimal Full Example
174
175A complete, schema-valid copy of this catalog is in [guidance-example.yaml](guidance-example.yaml) in this directory. Combined minimal catalog:
176
177```yaml
178title: Secure Software Development Guidance
179metadata:
180 id: ORG.SSD.001
181 type: GuidanceCatalog
182 gemara-version: "0.20.0"
183 description: Internal secure development and supply chain security guidelines (dependencies, images, and development practices) aligned to industry standards
184 version: 1.0.0
185 author:
186 id: example
187 name: Example
188 type: Human
189 mapping-references:
190 - id: OWASP
191 title: OWASP Top 10
192 version: "2021"
193 url: https://owasp.org/Top10
194 description: OWASP Top 10 Web Application Security Risks
195 applicability-groups:
196 - id: containerized_workloads
197 title: Containerized Workloads
198 description: Guidelines that apply to container-based deployments and images.
199 - id: ci_cd
200 title: CI/CD
201 description: Guidelines that apply in continuous integration and deployment pipelines.
202 - id: github_repositories
203 title: GitHub Repositories
204 description: Guidelines that apply to projects using GitHub for source and collaboration.
205type: Best Practice
206front-matter: Example best-practices text for tutorials developed by Gemara maintainers.
207groups:
208 - id: ORG.SSD.FAM01
209 title: Secure Dependencies and Supply Chain
210 description: Guidelines for selecting, updating, and verifying dependencies and images.
211
212guidelines:
213 - id: ORG.SSD.GL01
214 title: Prefer Immutable Image References
215 objective: |
216 Use digest-based or immutable references for container images to prevent
217 tampering and ensure repeatable deployments.
218 group: ORG.SSD.FAM01
219 state: Active
220 recommendations:
221 - Prefer pull-by-digest over tags for production.
222 - Pin base image digests in Dockerfiles or equivalent.
223 applicability: ["containerized_workloads", "ci_cd"]
224 see-also:
225 - ORG.SSD.GL02
226 - ORG.SSD.GL03
227 - id: ORG.SSD.GL02
228 title: Prefer GitHub Branch Protection Rules
229 objective: |
230 Use branch protection so only approved changes reach the main branch and
231 malicious code cannot be merged without review.
232 group: ORG.SSD.FAM01
233 state: Active
234 recommendations:
235 - Prefer pull requests submitted from fork branch.
236 - Required maintainer/non-author review and approval for merge.
237 - Prefer GitHub Actions Quality checks in CI on pull request.
238 applicability: ["containerized_workloads", "ci_cd", "github_repositories"]
239 see-also:
240 - ORG.SSD.GL01
241 - id: ORG.SSD.GL03
242 title: Prefer VPN on Untrusted Networks
243 objective: |
244 Use a VPN on untrusted networks to protect traffic from interception and
245 DNS spoofing.
246 group: ORG.SSD.FAM01
247 state: Active
248 recommendations:
249 - Use a VPN for registry and build traffic on untrusted networks.
250 applicability: ["containerized_workloads", "ci_cd"]
251 see-also:
252 - ORG.SSD.GL02
253```
254
255## What's Next
256
257Map guidelines to Layer 2 controls via control catalogs’ `guidelines`, or reference this guidance from a Policy. See the [schema documentation](https://gemara.openssf.org/schema/layer-1.html) for optional fields such as `exemptions`, `see-also`, `replaced-by`, `front-matter`, `rationale`, `statements`, and `principles` or `vectors`.