1---
2layout: page
3title: Organizational Risk & Policy Guide
4---
5
6## What This Is
7
8This guide walks through creating a **[Policy Document](../../model/02-definitions.html#policy)** using the [Gemara](https://gemara.openssf.org/) project. The document conforms to the Policy Definition in [`policy.cue`](https://github.com/gemaraproj/gemara/blob/main/policy.cue).
9
10Terms to know:
11* **RACI**: Who is responsible, accountable, consulted, and informed.
12* **Scope**: What is in and out of scope (technologies, regions, sensitivity, users).
13* **Imports**: Which external policies, Control Catalogs, and Guidance the policy references (and any exclusions, constraints, or assessment-requirement modifications).
14* **Implementation plan**: When the policy becomes active (evaluation and enforcement timelines).
15* **[Risks](../../model/02-definitions.html#risk)**: Which risks are mitigated vs accepted (with justification for accepted risks).
16* **Adherence**: How compliance is evaluated and enforced (evaluation methods, assessment plans, enforcement methods, non-compliance handling).
17
18This exercise produces a policy document that captures scope, imported controls and guidance, and how adherence is evaluated and enforced.
19
20## Walkthrough
21
22### Step 0: Metadata and mapping-references
23
24Set `title` and `metadata` (see [metadata.cue](https://github.com/gemaraproj/gemara/blob/main/metadata.cue) for the standard metadata fields). Include `mapping-references` for every external catalog, guidance document, or policy you reference in `imports` (by `reference-id`). Key fields (see [`policy.cue`](https://github.com/gemaraproj/gemara/blob/main/policy.cue) and [metadata.cue](https://github.com/gemaraproj/gemara/blob/main/metadata.cue):
25
26| Field | What It Is | Why |
27|-------------------------------|----------------------------------------------------------------------------|---------------------------------------------------------------------|
28| `title` | Display name for the policy (top-level) | Human-readable label in reports and tooling |
29| `metadata.id` | Unique identifier for this policy | Used when other documents reference this policy |
30| `metadata.type` | Must be `Policy` | Required by schema; identifies the artifact kind |
31| `metadata.gemara-version` | Gemara specification version (e.g. `"1.2.0"`) | Required by schema; should match the module tag you pass to `cue vet` |
32| `metadata.description` | High-level summary of the policy's purpose and scope | Required by schema; clarifies intent |
33| `metadata.author` | Actor (id, name, type) primarily responsible for this policy | Required by schema; identifies the author |
34| `metadata.version` | Version identifier (e.g. `"1.0.0"`) | Optional; supports versioning and references |
35| `metadata.mapping-references` | Pointers to external catalogs, guidance, or policies referenced in imports | Required for `imports`; each `reference-id` must match an entry here |
36
37> **Note:** Include a `mapping-references` entry for every external catalog, guidance document, or policy you reference in `imports` (by `reference-id`).
38
39**Example (YAML):**
40
41```yaml
42title: "Information Security Policy for Cloud and Web Applications"
43metadata:
44 id: "org-policy-001"
45 type: Policy
46 gemara-version: "1.2.0"
47 description: "Policy for cloud and web application security; references control catalogs."
48 version: "1.0.0"
49 author:
50 id: security-team
51 name: "Security Team"
52 type: Human
53 mapping-references:
54 - id: "SEC.SLAM.CM"
55 title: "Container Management Tool Security Control Catalog"
56 version: "1.0.0"
57 description: "Control catalog for container management tool security."
58```
59
60
61### Step 1: Contacts
62
63Define `contacts` with at least `responsible` and `accountable`. Each entry has `name`; optionally `affiliation` and `email`. Add `consulted` and `informed` if needed.
64
65**Example (YAML):**
66
67```yaml
68contacts:
69 responsible:
70 - name: "Platform Engineering"
71 affiliation: "Engineering"
72 email: "platform@example.com"
73 accountable:
74 - name: "CISO"
75 affiliation: "Security"
76 email: "ciso@example.com"
77 consulted:
78 - name: "Legal"
79 affiliation: "Legal"
80 informed:
81 - name: "All Engineering"
82 affiliation: "Engineering"
83```
84
85### Step 2: Scope
86
87Set `scope.in` (and optionally `scope.out`) with dimension fields that define where and to whom the policy applies:
88
89| Field | Purpose |
90| --------------- | -------------------------- |
91| `technologies` | Tech stack or systems |
92| `geopolitical` | Regions or jurisdictions |
93| `sensitivity` | Data or asset sensitivity |
94| `users` | User roles or populations |
95| `groups` | Teams or org units |
96
97**Example (YAML):**
98
99```yaml
100scope:
101 in:
102 technologies:
103 - "Cloud Computing"
104 - "Web Applications"
105 geopolitical:
106 - "United States"
107 - "European Union"
108 users:
109 - "developers"
110 - "platform-engineers"
111 out:
112 technologies:
113 - "Legacy On-Premises"
114```
115
116### Step 3: Imports
117
118Under `imports`:
119
120- **`policies`** — List of external policy imports. Each entry: reference-id (must match metadata.mapping-references) to reference other policy documents this policy inherits or extends.
121- **`guidance`** — List of guidance imports used when the policy aligns to Layer 1 Guidance Catalogs. Each entry: reference-id (match metadata.mapping-references), optional exclusions and constraints.
122- **`catalogs`** — List of catalog imports used when the policy references Layer 2 Control Catalogs. Use assessment-requirement-modifications to tailor how assessment requirements are applied (Add, Modify, Remove, Replace, or Override).
123
124Ensure each `reference-id` appears in `metadata.mapping-references`.
125
126**Example (YAML):**
127
128```yaml
129imports:
130 catalogs:
131 - reference-id: "SEC.SLAM.CM"
132 assessment-requirement-modifications:
133 - id: "CTL02-AR01-strict"
134 target-id: "SEC.SLAM.CM.CTL02.AR01"
135 modification-type: Override
136 modification-rationale: "Require TLS and certificate pinning for all registry communication in this org."
137 text: "The system MUST use TLS/SSL for all registry communication and MUST pin to the expected server certificate or public key (or certificate chain) for the registry."
138 - id: "CTL02-AR02-strict"
139 target-id: "SEC.SLAM.CM.CTL02.AR02"
140 modification-type: Override
141 modification-rationale: "Require VPN or trusted path on untrusted networks for registry traffic in this org."
142 text: "On untrusted networks, the system or deployment pipeline MUST use a VPN or other trusted path for registry traffic, or MUST restrict image pulls to environments where the network is trusted."
143
144```
145
146### Step 4: Implementation plan (optional)
147
148Add `implementation-plan` with `evaluation-timeline` and `enforcement-timeline`. Each has `start`, optional `end`, and `notes`. Optionally add `notification-process` (string).
149
150**Example (YAML):**
151
152```yaml
153implementation-plan:
154 notification-process: "Policy communicated via internal wiki and team leads; rollout via Platform Engineering."
155 evaluation-timeline:
156 start: "2025-03-01T00:00:00Z"
157 end: "2025-06-01T00:00:00Z"
158 notes: "Initial evaluation phase; automated checks rolled out by Q2."
159 enforcement-timeline:
160 start: "2025-06-01T00:00:00Z"
161 notes: "Enforcement begins after evaluation baseline is established."
162```
163
164### Step 5: Adherence
165
166Define `adherence` with at least one of the following:
167
168| Field | Purpose |
169| ----------------------- | ----------------------------------------------------------------------- |
170| `evaluation-methods` | List of methods: required `id`; `type` (`Behavioral`, `Intent`, `Remediation`, `Gate`); `mode` (`Manual`, `Automated`); optional `required`, `description`, `executor` |
171| `assessment-plans` | Plans: required `id`, `requirement-id`, `frequency`, and `evaluation-methods`; optional `evidence-requirements`, `parameters` |
172| `enforcement-methods` | Same structure as `evaluation-methods` (required `id`, `type`, `mode`) |
173| `non-compliance` | String describing handling of non-compliance |
174
175**Example (YAML):**
176
177```yaml
178adherence:
179 evaluation-methods:
180 - id: "EV-AUTO-01"
181 type: "Behavioral"
182 mode: "Automated"
183 required: true
184 description: "CI pipeline runs control checks via Privateer."
185 - id: "EV-MANUAL-01"
186 type: "Behavioral"
187 mode: "Manual"
188 required: true
189 description: "Quarterly review of exception requests."
190 assessment-plans:
191 - id: "plan-ctl01-ar01"
192 requirement-id: "SEC.SLAM.CM.CTL01.AR01"
193 frequency: "every push"
194 evaluation-methods:
195 - id: "EV-AUTO-02"
196 type: "Behavioral"
197 mode: "Automated"
198 required: true
199 enforcement-methods:
200 - id: "EM-GATE-01"
201 type: "Gate"
202 mode: "Automated"
203 required: true
204 description: "Block merge if control check fails."
205 non-compliance: "Non-compliance is reported to responsible contacts and tracked in issue tracker; critical failures block deployment."
206```
207
208## Step 6: Validation
209
210The policy must conform to the Policy Definition defined in the CUE module. Validate with CUE:
211
212**Validation commands:**
213
214Using the **published** module:
215
216```bash
217go install cuelang.org/go/cmd/cue@latest
218cue vet -c -d '#Policy' github.com/gemaraproj/gemara@v1 your-policy.yaml
219```
220
221Fix any errors (e.g. missing required fields, invalid reference-ids, or type mismatches) so the policy is schema-valid.
222
223## Minimal Full Example
224
225A complete, schema-valid copy of this policy is in [policy-example.yaml](policy-example.yaml) in this directory. The following combines the snippets above into a single policy document. Omit optional sections (e.g. implementation-plan, risks) if not needed.
226
227```yaml
228title: "Information Security Policy for Cloud and Web Applications"
229metadata:
230 id: "org-policy-001"
231 type: Policy
232 gemara-version: "1.2.0"
233 description: "Policy for cloud and web application security; references control catalogs."
234 version: "1.0.0"
235 author:
236 id: security-team
237 name: "Security Team"
238 type: Human
239 mapping-references:
240 - id: "SEC.SLAM.CM"
241 title: "Container Management Tool Security Control Catalog"
242 version: "1.0.0"
243 description: "Control catalog for container management tool security."
244
245contacts:
246 responsible:
247 - name: "Platform Engineering"
248 affiliation: "Engineering"
249 email: "platform@example.com"
250 accountable:
251 - name: "CISO"
252 affiliation: "Security"
253 email: "ciso@example.com"
254
255scope:
256 in:
257 technologies:
258 - "Cloud Computing"
259 - "Web Applications"
260 geopolitical:
261 - "United States"
262 - "European Union"
263
264imports:
265 catalogs:
266 - reference-id: "SEC.SLAM.CM"
267 assessment-requirement-modifications:
268 - id: "CTL02-AR01-strict"
269 target-id: "SEC.SLAM.CM.CTL02.AR01"
270 modification-type: Override
271 modification-rationale: "Require TLS and certificate pinning for all registry communication in this org."
272 text: "The system MUST use TLS/SSL for all registry communication and MUST pin to the expected server certificate or public key (or certificate chain) for the registry."
273 - id: "CTL02-AR02-strict"
274 target-id: "SEC.SLAM.CM.CTL02.AR02"
275 modification-type: Override
276 modification-rationale: "Require VPN or trusted path on untrusted networks for registry traffic in this org."
277 text: "On untrusted networks, the system or deployment pipeline MUST use a VPN or other trusted path for registry traffic, or MUST restrict image pulls to environments where the network is trusted."
278
279adherence:
280 evaluation-methods:
281 - id: "EV-AUTO-01"
282 type: "Behavioral"
283 mode: "Automated"
284 required: true
285 description: "CI pipeline runs control checks."
286 non-compliance: "Non-compliance is reported to responsible contacts and tracked."
287```
288
289## What's Next
290
291- Use the policy in **Layer 5** evaluations to determine whether implementations conform.
292- Use **Layer 7** audit and continuous monitoring to assess policy effectiveness.
293
294See the [Policy schema documentation](https://gemara.openssf.org/schema/policy.html) and [policy.cue](https://github.com/gemaraproj/gemara/blob/main/policy.cue) for the full specification.