The format, field by field.

Status: draft (v0.1). Sections are specified one layer at a time.

#Conventions

• Dates use ISO 8601 YYYY-MM-DD.
• Enumerated values are lowercase.
• TLP values follow TLP 2.0: CLEAR, GREEN, AMBER, AMBER+STRICT, RED.

#Root

#meta

#Identifier rules

CIR-YYYY-CODE-NNNN

• Public record: ^CIR-\d{4}-0[A-Z0-9]{0,7}-\d{4,}$. CODE must be listed in authorities.yml. 00 is the root authority.
• Internal record: ^CIR-\d{4}-[A-Z1-9][A-Z0-9]{1,7}-\d{4,}$. Managed freely by the organization, not globally unique.

Whether a record is public is derived from the code (first character is 0); there is no separate field for it.

#TLP rules

• Each layer carries its own tlp.
• meta.tlp, when set, is a ceiling: no layer may be less restrictive than it.
• Restriction order: CLEAR < GREEN < AMBER < AMBER+STRICT < RED.
• Exporting a record to an audience means dropping every layer whose tlp is more restrictive than what that audience may receive.

#Validation

• id matches one of the two patterns above.
• Public id → CODE exists in authorities.yml.
• updated >= created.
• based_on, when set, matches a valid id pattern and differs from id.
• No layer tlp is less restrictive than meta.tlp.

#Authorities registry

Each entry of authorities.yml:

The key is the one the authority signs its public records with. Rotating a key or extending its expiration goes through a pull request, like adding an authority.

#Layers: common rules

• Every layer present in a record must have a tlp.
• A layer can be omitted entirely.
• A record with meta.based_on inherits the core and threat_intel layers of its parent when it omits them. This is the normal shape of an internal record adding posture and/or context to a public one.

#core (layer 1)

What the issue is. core references existing standards and never redefines them. Products and versions follow the OSV model so records can be imported from and exported to OSV.

#identifiers[]

internal identifiers (ticket, pentest report ID...) are forbidden in public records and dropped by any export to a public audience.

#references[]

Exploits and PoCs are not references: they belong to threat_intel.

#affected[]

At least one of ranges or versions is required.

#ranges[]

Event semantics follow OSV: a version is affected if it is at or after an introduced and before the next fixed (or at or before the next last_affected). introduced: "0" means "since the first version". Several introduced / fixed pairs in one range describe disjoint affected intervals. For git ranges, events are commit hashes.

#severity[]

#remediations[]

#core validation

• cve / ghsa identifiers match their patterns.
• No internal identifier in a public record.
• Each affected[] has ranges or versions.
• Each range has at least one introduced event; git ranges have a repo.
• severity[].score matches the score computed from vector.

#threat_intel (layer 2)

Who exploits the issue, how, and since when. Two principles: everything is dated and sourced, and entities (actors, malware, campaigns) are references, not descriptions.

#Confidence

Every assertion that carries a confidence uses: low, medium, high, critical.

#exploitation

#signals

Values from external feeds are stored, not resolved live, so a record stays usable offline. They are a snapshot taken at threat_intel.updated: refreshing any signal means bumping threat_intel.updated.

#Entities (actors[], malware[], campaigns[])

A mitre ref for an actor must match ^G\d{4}$, for malware ^S\d{4}$, for a campaign ^C\d{4}$.

#attack[]

#targeting

#iocs[] and ioc_bundles[]

Inline iocs are meant for a handful of key indicators (about 50 at most). Large sets go to ioc_bundles.

#detections[]

Public detection rules only. What an organization actually deploys never goes here (see posture).

#timeline[] and sources[]

#threat_intel validation

• Every sources reference points to an existing sources[].id.
• sources[].id values are unique.
• mitre refs and attack[] values match their patterns.
• exploitation.first_seen and timeline[].date are <= updated.

#posture (layer 3)

The state of one entity facing the issue, expressed in generic terms only. This layer is designed to be shared with a group or sector CERT, which can aggregate it across entities without learning anything about their assets.

Hard rule: posture contains no free text, no numbers and no names. Every value is an enum, a boolean, a date, or an identifier matching a pattern. If a need doesn't fit the enums, the enum is extended in the specification, not worked around in the record.

posture has no score field: its contribution to scoring (the exposure bucket) is derived, see Scoring.

#status

Aligned with VEX, so a posture can be exported as a VEX statement.

mitigated has no direct VEX equivalent and exports as affected with the controls as action statement.

#prerequisites

What exploitation actually requires at this entity. It differs from CVSS, which describes the issue in the abstract (e.g. a network vulnerability only exploitable with a non-default feature enabled).

#exposure

#controls[]

#detection

#impact

#remediation

#posture validation

• No field outside this specification (unknown keys are rejected, so no free text can be added).
• All values match their enum, type or pattern.
• status.justification is present if and only if status.state is not_affected.
• chained_with entries match a CIR or CVE pattern.

#context (layer 4)

What the issue means for one organization: affected assets, business impact, decisions, remediation and communication. This layer never leaves the organization (RED by default). Unlike posture, free text and names are allowed, but structured fields come first.

#assets[]

#asset_selectors[]

#exploitation

#business_impact

#decision

#remediation

#communication[]

The communication log is what makes a CIR a shared reference across teams: who was informed, when and through which channel.

#score

#notes[]

#context validation

• decision.review_on is required when decision.action is accept, transfer or monitor, and must be after decided_on.
• exploitation.incident_ref is required when exploitation.status is suspected or confirmed.
• remediation.verified_on is required when remediation.status is verified.

#Scoring

Method: cir-risk/0.1.

Principles:

• Deterministic: scores are computed from the record fields only, never typed in.
• Explainable: additive points that a human can recompute in a meeting.
• Versioned: a stored score names its method; validators recompute it and reject mismatches.
• Comparable: the method is fixed, so a high means the same thing in every organization. An organization may store its own score under another method name, but cir-risk remains the comparable reference.

 core          threat_intel        posture            context
   |                |                 |                  |
 SEVERITY       EXPLOITATION       EXPOSURE            IMPACT
   0-3              0-3               0-3                0-3
   +-------+--------+                 |                  |
           |                          |                  |
   PUBLIC PRIORITY (0-6)              |                  |
           +--------------+-----------+------------------+
                          |
                   ORG RISK (0-12) + overrides

Inherited layers (meta.based_on) count as present.

#Inputs

Severity (from core.severity). The retained score is chosen by source (issuer > vendor > nvd), then by version (cvss_v4.0 > cvss_v3.1).

Exploitation (from threat_intel).

An unknown exploitation is treated as public, not active: internal issues rarely have threat intelligence, and an internal finding (e.g. pentest) implies a working proof of concept.

Exposure (from posture). The first matching bucket applies.

Impact (from context). The highest value among assets[].criticality, business_impact.confidentiality, business_impact.integrity and business_impact.availability.

Unknown severity, exposure and impact default to the worst case: an unknown risk is treated as a dangerous one, which also pushes organizations to fill their layers.

#Public priority

Computable without any organizational data. Stored in threat_intel.priority.

points = severity + exploitation        (0 to 6)
value  = round(points / 6 * 10, 1)

#Organizational risk

Stored in context.score.

points = severity + exploitation + exposure + impact     (0 to 12)
value  = round(points / 12 * 10, 1)

Overrides, applied in order:

1. Exposure bucket none → level none, value 0.
2. context.exploitation.status is confirmed → level critical (value unchanged). The issue is an incident.
3. signals.kev.listed is true and exposure bucket is open → level at least high.

#Worked examples