1---
2layout: page
3title: Organizational Risk & Policy Guide
4---
5
6## What This Is
7
8This guide walks through creating a **Policy Document** using the [Gemara](https://gemara.openssf.org/) project. The document conforms to the **Policy** schema in `layer-3.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**: 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 [layer-3.cue](https://github.com/gemaraproj/gemara/blob/main/layer-3.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.description` | High-level summary of the policy's purpose and scope | Required by schema; clarifies intent |
31| `metadata.author` | Actor (id, name, type) primarily responsible for this policy | Required by schema; identifies the author |
32| `metadata.version` | Version identifier (e.g. `"1.0.0"`) | Optional; supports versioning and references |
33| `metadata.mapping-references` | Pointers to external catalogs, guidance, or policies referenced in imports | Required for `imports`; each `reference-id` must match an entry here |
34
35> **Note:** Include a `mapping-references` entry for every external catalog, guidance document, or policy you reference in `imports` (by `reference-id`).
36
37**Example (YAML):**
38
39```yaml
40title: "Information Security Policy for Cloud and Web Applications"
41metadata:
42 id: "org-policy-001"
43 type: Policy
44 gemara-version: "0.20.0"
45 description: "Policy for cloud and web application security; references control catalogs."
46 version: "1.0.0"
47 author:
48 id: security-team
49 name: "Security Team"
50 type: Human
51 mapping-references:
52 - id: "SEC.SLAM.CM"
53 title: "Container Management Tool Security Control Catalog"
54 version: "1.0.0"
55 description: "Control catalog for container management tool security."
56```
57
58
59### Step 1: Contacts
60
61Define `contacts` with at least `responsible` and `accountable`. Each entry has `name`; optionally `affiliation` and `email`. Add `consulted` and `informed` if needed.
62
63**Example (YAML):**
64
65```yaml
66contacts:
67 responsible:
68 - name: "Platform Engineering"
69 affiliation: "Engineering"
70 email: "platform@example.com"
71 accountable:
72 - name: "CISO"
73 affiliation: "Security"
74 email: "ciso@example.com"
75 consulted:
76 - name: "Legal"
77 affiliation: "Legal"
78 informed:
79 - name: "All Engineering"
80 affiliation: "Engineering"
81```
82
83### Step 2: Scope
84
85Set `scope.in` (and optionally `scope.out`) with dimension fields that define where and to whom the policy applies:
86
87| Field | Purpose |
88| --------------- | -------------------------- |
89| `technologies` | Tech stack or systems |
90| `geopolitical` | Regions or jurisdictions |
91| `sensitivity` | Data or asset sensitivity |
92| `users` | User roles or populations |
93| `groups` | Teams or org units |
94
95**Example (YAML):**
96
97```yaml
98scope:
99 in:
100 technologies:
101 - "Cloud Computing"
102 - "Web Applications"
103 geopolitical:
104 - "United States"
105 - "European Union"
106 users:
107 - "developers"
108 - "platform-engineers"
109 out:
110 technologies:
111 - "Legacy On-Premises"
112```
113
114### Step 3: Imports
115
116Under `imports`:
117
118- **`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.
119- **`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.
120- **`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, override).
121
122
123Ensure each `reference-id` appears in `metadata.mapping-references`.
124
125**Example (YAML):**
126
127```yaml
128imports:
129 catalogs:
130 - reference-id: "SEC.SLAM.CM"
131 assessment-requirement-modifications:
132 - id: "CTL02-AR01-strict"
133 target-id: "SEC.SLAM.CM.CTL02.AR01"
134 modification-type: Override
135 modification-rationale: "Require TLS and certificate pinning for all registry communication in this org."
136 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."
137 - id: "CTL02-AR02-strict"
138 target-id: "SEC.SLAM.CM.CTL02.AR02"
139 modification-type: Override
140 modification-rationale: "Require VPN or trusted path on untrusted networks for registry traffic in this org."
141 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."
142
143```
144
145### Step 4: Implementation plan (optional)
146
147Add `implementation-plan` with `evaluation-timeline` and `enforcement-timeline`. Each has `start`, optional `end`, and `notes`. Optionally add `notification-process` (string).
148
149**Example (YAML):**
150
151```yaml
152implementation-plan:
153 notification-process: Policy communicated via internal wiki and team leads.
154 evaluation-timeline:
155 start: 2025-03-01T00:00:00Z
156 end: 2025-06-01T00:00:00Z
157 notes: Initial evaluation phase; automated checks rolled out by Q2.
158 enforcement-timeline:
159 start: 2025-06-01T00:00:00Z
160 notes: Enforcement begins after evaluation baseline is established.
161```
162
163### Step 5: Adherence
164
165Define `adherence` with at least one of the following:
166
167| Field | Purpose |
168| ----------------------- | ----------------------------------------------------------------------- |
169| `evaluation-methods` | List of methods: `type` (Manual, Behavioral, Automated, Autoremediation, Gate), optional `description`, `executor` |
170| `assessment-plans` | Plans: `requirement-id`, `frequency`, `evaluation-methods`; optional `evidence-requirements`, `parameters` |
171| `enforcement-methods` | Same structure as evaluation-methods (type, description, executor) |
172| `non-compliance` | String describing handling of non-compliance |
173
174**Example (YAML):**
175
176```yaml
177adherence:
178 evaluation-methods:
179 - type: "Automated"
180 description: "CI pipeline runs control checks via Privateer."
181 - type: "Manual"
182 description: "Quarterly review of exception requests."
183 assessment-plans:
184 - id: "SEC.SLAM.CM.CTL01"
185 requirement-id: "SEC.SLAM.CM.CTL01.AR01"
186 frequency: "every push"
187 evaluation-methods:
188 - type: "Automated"
189 enforcement-methods:
190 - type: "Gate"
191 description: "Block merge if control check fails."
192 non-compliance: "Non-compliance is reported to responsible contacts and tracked in issue tracker; critical failures block deployment."
193```
194
195## Step 6: Validation
196
197The policy must conform to the Policy Definition defined in the CUE module. Validate with CUE:
198
199**Validation commands:**
200
201Using the **published** module:
202
203```bash
204go install cuelang.org/go/cmd/cue@latest
205cue vet -c -d '#Policy' github.com/gemaraproj/gemara@latest your-policy.yaml
206```
207
208Fix any errors (e.g. missing required fields, invalid reference-ids, or type mismatches) so the policy is schema-valid.
209
210## Minimal Full Example
211
212A 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.
213
214```yaml
215title: "Information Security Policy for Cloud and Web Applications"
216metadata:
217 id: "org-policy-001"
218 description: "Policy for cloud and web application security; references control catalogs."
219 version: "1.0.0"
220 author:
221 id: security-team
222 name: "Security Team"
223 type: Human
224 mapping-references:
225 - id: "SEC.SLAM.CM"
226 title: "Container Management Tool Security Control Catalog"
227 version: "1.0.0"
228 description: "Control catalog for container management tool security."
229
230contacts:
231 responsible:
232 - name: "Platform Engineering"
233 affiliation: "Engineering"
234 email: "platform@example.com"
235 accountable:
236 - name: "CISO"
237 affiliation: "Security"
238 email: "ciso@example.com"
239
240scope:
241 in:
242 technologies:
243 - "Cloud Computing"
244 - "Web Applications"
245 geopolitical:
246 - "United States"
247 - "European Union"
248
249imports:
250 catalogs:
251 - reference-id: "SEC.SLAM.CM"
252 assessment-requirement-modifications:
253 - id: "CTL02-AR01-strict"
254 target-id: "SEC.SLAM.CM.CTL02.AR01"
255 modification-type: Override
256 modification-rationale: "Require TLS and certificate pinning for all registry communication in this org."
257 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."
258 - id: "CTL02-AR02-strict"
259 target-id: "SEC.SLAM.CM.CTL02.AR02"
260 modification-type: Override
261 modification-rationale: "Require VPN or trusted path on untrusted networks for registry traffic in this org."
262 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."
263
264adherence:
265 evaluation-methods:
266 - type: "Automated"
267 description: "CI pipeline runs control checks."
268 non-compliance: "Non-compliance is reported to responsible contacts and tracked."
269```
270
271## What's Next
272
273- Use the policy in **Layer 5** evaluations to determine whether implementations conform.
274- Use **Layer 7** audit and continuous monitoring to assess policy effectiveness.
275
276See the [Layer 3 schema documentation](https://gemara.openssf.org/schema/layer-3.html) and [layer-3.cue](https://github.com/gemaraproj/gemara/blob/main/layer-3.cue) for the full specification.