crml

What is crml?

crml (CRML — Cyber Risk Modeling Language) is an open-source, declarative language for cyber risk modeling. It lets you describe risk models, telemetry mappings, simulation pipelines, dependencies, and required outputs using a YAML/JSON format—without requiring a specific quantification method, simulation engine, or control/threat framework.

The project is designed to support “Risk as Code” workflows, where assumptions and model definitions can live in versioned, reviewable artifacts (e.g., in Git). This aims to make cyber risk models easier to validate, reproduce, and exchange across teams and tools by standardizing how inputs, assumptions, and outputs are represented.

Key Features

• Declarative YAML/JSON model descriptions: Express risk models and their execution requirements in a portable format rather than embedding logic in spreadsheets or one-off tooling.
• Engine-agnostic simulation specification: Define simulation pipelines and dependencies so different simulation engines can consume the same model definition (as long as they are compliant with CRML).
• Control/Attack framework–agnostic mappings: Represent mappings to controls and attacks without locking the model to a single framework or catalog, which helps when frameworks evolve.
• Control effectiveness modeling: Model how controls reduce risk, including “defense in depth” assumptions.
• Median-based parameterization for lognormal distributions: Specify medians directly for lognormal distributions, aligning with how risk distributions are parameterized in the CRML approach.
• Strict validation via JSON Schema: Validate model documents before simulation to catch structural errors early.

How to Use crml

1. Get the project and documentation: Start from the repository (README and docs are included via the repo contents) and install the package available on PyPI.
2. Write a CRML document: Create a YAML/JSON document describing the model elements you want to run—such as telemetry mappings, dependencies, simulation pipeline structure, and output requirements.
3. Validate the document: Use the project’s schema-based validation to check for errors before running simulations.
4. Run with a compatible engine: Execute the model using a simulation pipeline compatible with CRML. Because CRML is intended to be engine-agnostic, the same CRML document can be reused across different compliant engines.

Use Cases

• Making risk models reviewable in Git: Convert spreadsheet- or deck-based model assumptions into versioned CRML documents so changes are visible in diffs and can be audited.
• Standardizing model exchange across teams: Share a single CRML-defined risk model between analysts and tools so that the same inputs/assumptions/outputs are interpreted consistently.
• Quantified risk comparison with explicit assumptions: Run scenarios such as “with vs. without an investment” or “across time periods” while keeping assumptions explicit and tied to validated model definitions.
• Mapping cyber risk to broader enterprise risk workflows: Use CRML’s standardized input/output representation to support traceability when cyber metrics feed into enterprise risk and financial planning processes.
• Evolving mappings as frameworks change: When control or threat frameworks (e.g., ATT&CK, NIST, ISO, or internal catalogs) update, update the CRML mappings rather than rewriting engine-specific modeling logic.

FAQ

• Is crml production-ready? The repository states the project status is Draft and that it is under heavy development and may change without notice. It also notes the active development branch is crml-dev-1.3.

• What format does crml use to define models? CRML uses a YAML/JSON format to describe risk models, telemetry mappings, simulation pipelines, dependencies, and output requirements.

• Does crml force a specific risk quantification method? No. It is intended to be implementation-agnostic and engine-agnostic, so you can describe models without forcing a specific quantification method or simulation engine.

• How does crml reduce modeling errors? It supports strict validation using JSON Schema to catch errors in the model documents before simulation.

• Where is the project distributed? The repository metadata states it is available on PyPI.

Alternatives

• Spreadsheet- or slide-based cyber risk modeling: Common for qualitative or semi-quantitative work, but these formats are harder to validate and reproduce consistently compared to a declarative, schema-validated document approach.
• Engine-specific cyber risk modeling implementations: Tools that embed assumptions and simulation logic directly in proprietary model formats can be more tightly integrated, but often require rewrites when switching quant engines or updating mappings.
• General-purpose declarative configuration formats (for example, model configuration files): You can use generic formats to externalize parameters, but they typically won’t provide CRML’s cyber-risk-specific structure for telemetry mapping, simulation pipelines, and standardized outputs.
• Other “Risk as Code” modeling approaches: Approaches that version assumptions and parameters can improve reviewability, but may not be designed specifically for cyber risk modeling across control/attack and engine contexts.