---
layout: page
title: Tutorials
---

## Start here

**Gemara Layers — Knowledge, Inputs & Outputs** — Start here if you're new to the model.

---

## Find Your Tutorial

Pick your goal — each path leads to the right guide.

### Performing a threat assessment

For a system or component → [Threat Assessment Guide](controls/threat-assessment-guide) — identify capabilities and threats, map them to attack surfaces (Layer 2).

### Defining security controls

That mitigate those threats → [Control Catalog Guide](controls/control-catalog-guide) — create a control catalog with assessment requirements and threat-mappings (Layer 2).

### Understanding what threats and controls exist

Before writing policy → [Threat Assessment Guide](controls/threat-assessment-guide) for threats and capabilities, and [Control Catalog Guide](controls/control-catalog-guide) for threat-informed controls and assessment requirements (Layer 2).

### Reviewing the controls to reference in a policy

→ [Control Catalog Guide](controls/control-catalog-guide) — control structure, assessment requirements, and threat links (Layer 2).

### Understanding the security posture of consumed software

→ [Threat Assessment Guide](controls/threat-assessment-guide) — review threat catalogs for your dependencies (Layer 2).

→ **COMING SOON:** Use control catalogs (e.g. OSPS, CCC) as hardening guides (Layer 2).

### Creating a guidance catalog from best practices

From a spreadsheet or checklist — create a guidance catalog (guidelines, groups, mapping-references) that threat-informed controls can reference; express relationships to other frameworks in a [Mapping Document Guide](mapping/mapping-document-guide) (see also the [Mapping Document schema](https://gemara.openssf.org/schema/mappingdocument.html)). → [Guidance Catalog Guide](guidance/guidance-guide).

### Creating a mapping document between artifacts

Express how entries in a source artifact (e.g., guidance, principle, or control catalog) relate to a target artifact (e.g., regulation or framework) — [Mapping Document Guide](mapping/mapping-document-guide) — typed source/target references (`#TypedMapping`), `source` plus `targets` (`#MappingTarget`), relationship types, and applicability (cross-artifact).

### Creating organizational policy

Create a policy document that translates risk appetite into mandatory rules — [Policy Guide](policy/policy-guide) — scope, imports, adherence, and risks (Layer 3).

### Creating a risk catalog

When you need a structured inventory of organizational or system risks—**risk categories** (appetite, optional max-severity), per-risk **severity**, optional **`rank`** for ordering within the catalog, optional RACI **owner** and **impact**, and optional **threats** links backed by `metadata.mapping-references`—so policies can reference mitigated or accepted risks → [Risk Catalog Guide](policy/risk-catalog-guide) (Layer 3).

## What You'll Build

| Layer | Artifact | Guide |
|-------|----------|-------|
| **Layer 1** — Guidance | Guidance Catalog (guidelines, groups, mapping-references); [Principle Catalog](https://gemara.openssf.org/schema/principlecatalog.html) (principles, groups) | [Guidance Catalog Guide](guidance/guidance-guide) |
| **Layer 2** — Controls | Threat Catalog + Control Catalog (assessment requirements, threats) | [Threat Assessment](controls/threat-assessment-guide), [Control Catalog](controls/control-catalog-guide) |
| **Layer 3** — Policy   | Policy Document (scope, imports, adherence)                  | [Policy Guide](policy/policy-guide) |
| **Layer 3** — Risks    | Risk Catalog (risk categories, appetite, risks, optional rank and threat mappings) | [Risk Catalog Guide](policy/risk-catalog-guide) |
| **Cross-artifact**     | Mapping Document (typed `source`/`target` references, `targets` per mapping, relationship types; entry types per schema include guidelines, controls, Principle, threats, risks, and others) | [Mapping Document Guide](mapping/mapping-document-guide) |

## What You'll Need

- `go` installed
- `cue` installed for validation (e.g. `cue vet -c -d '#MappingDocument' . your-mapping-document-example.yaml` from a clone, or the same placeholder filename with `github.com/gemaraproj/gemara@latest` for the published module)

## Have Ideas?

- Reach out via Slack in `#gemara`
- Discuss in one of our bi-weekly meetings on the [OpenSSF calendar](https://calendar.google.com/calendar/u/0?cid=czYzdm9lZmhwNWk5cGZsdGI1cTY3bmdwZXNAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ)
- Open a [GitHub Issue](https://github.com/gemaraproj/gemara/issues)