This guide defines writing standards for Project COSMOS ontology content.
Use it when creating or reviewing labels, aliases, short descriptions, long descriptions, and variants for ontology classes and individuals.
The guide is designed to grow over time. Start with the shared rules, then apply the class-specific rules for the individual being written.
Use this guide in order:
The guide separates shared writing conventions from class-specific rules because fields such as rdfs:label, alsoCalled, shortDescription, and longDescription may differ by class.
Class-specific field rules override class-family rules.
Class-family rules override shared field rules.
Shared field rules apply only when no more specific rule is available.
Exact class rule
overrides
Class-family rule
overrides
Shared default rule
Use American English for all descriptions.
Use clear analytic prose.
Avoid marketing language, sensational wording, and unnecessary jargon.
Avoid time-specific incident detail unless it is essential to the stable definition of the entity.
Avoid operational how-to instructions, command-level procedures, and unnecessary indicators of compromise.
Use these default limits unless a class-specific rule says otherwise.
shortDescription: 40 words or less.longDescription: 250 words or less.variant: 40 words or less.These rules apply unless a class-specific section provides different guidance.
rdfs:labelThe label is the preferred human-readable name for the entity.
The label should be concise, recognizable, and suitable for display in lists, diagrams, and ontology browsers.
alsoCalledThe alsoCalled field captures common aliases, alternative names, abbreviations, or ecosystem terms.
Use aliases that are common enough to help readers recognize the entity.
Do not include one-off references, incident-specific names, or speculative aliases.
shortDescriptionThe shortDescription provides a concise summary of the entity.
It should usually be one sentence.
The default maximum length is 40 words.
The purpose is to help a reader quickly decide whether the entity is relevant.
longDescriptionThe longDescription provides the fuller analytic explanation of the entity.
The default maximum length is 250 words.
Use paragraph breaks where they improve readability.
Do not add operational instructions, command-level procedures, indicators of compromise, or unnecessary implementation detail.
variantA variant captures a noteworthy variation on a general entity description.
A variant should describe a recurring variation that is important enough to record, but not common enough to change the core description.
A variant is description text, not a separate entity.
A variant should read like an additional paragraph appended to the end of the longDescription.
Rules for variant:
This section provides class-specific field rules. Add new classes here as the ontology expands.
A Pattern is a structured model representing a recurrent, recognizable manifestation of illicit, adverse, or exploitative cyber-dependent or cyber-enabled activity.
A Pattern encompasses multiple Diamond Events that collectively express a coherent operational or business model.
A Pattern should meet all of the following criteria:
rdfs:labelName the recurring cybercrime pattern or operational model.
Use a concise label that is recognizable outside a single incident or campaign.
alsoCalledInclude widely used alternative names for the Pattern.
Do not include one-off campaign names unless they are commonly used to refer to the Pattern itself.
shortDescriptionSummarize the illicit activity, major operational model, and primary victim impact.
Use one clear sentence where possible.
longDescriptionDescribe the illicit activity, the Diamond Event flow, the role players and ecosystem elements, and the victims and impacts.
Maximum length: 250 words.
variantCapture common Pattern variations that do not justify a separate Pattern.
Maximum length: 40 words per variant.
longDescription GuidanceA Pattern longDescription should include three major parts:
Label:
[Recognizable Pattern name]
alsoCalled:
[Common aliases or alternative names, if any]
shortDescription:
[One-sentence description of the recurring illicit activity and primary victim impact.]
longDescription:
[Paragraph 1: Describe the illicit, adverse, or exploitative activity and the overall operational model.]
[Paragraph 2: Summarize the Diamond Event flow, role players, and ecosystem elements.]
[Paragraph 3: Summarize victim groups and primary harms or impacts.]
variant:
[Optional recurring variation, 40 words or less.]
A Pattern Phase, also described as a Diamond Event, represents a single, recognizable, illicit, adverse, or exploitative cyber-dependent or cyber-enabled activity.
A Diamond Event describes a complete phase in a Pattern.
A Threat Action is a specific technical action that a role player performs during that phase.
A Diamond Event should describe a unique set of four interconnected core elements:
A Diamond Event can describe a distinct phase within a Pattern.
Diamond Events represent the phases or steps taken by an actor to form a Pattern.
One Diamond Event may be associated with one or more Patterns.
A Diamond Event may also be linked to a Market when that Market trades the activity.
Diamond Events may be chained together in sequences when one Diamond Event includes or depends on another Event.
Some Diamond Events, especially technical Events, occur commonly across diverse Patterns. These should be labeled and modeled as reusable Common Events when appropriate.
rdfs:labelUse a short, action-oriented phase name.
Aim for 5 to 12 words.
Name the phase of activity, not a single technical action.
alsoCalledInclude common alternative names for the phase only.
Do not use tool names, campaign names, or overly narrow incident names as aliases.
shortDescriptionUse one sentence.
Maximum length: 40 words.
Make the four core Diamond Model elements explicit at a high level.
longDescriptionUse up to 250 words.
Explain the phase role, the four Diamond Model elements, and relationships to Patterns, Markets, and chained Events.
variantCapture recurring variations in how the Event is performed, without creating a separate Event.
Maximum length: 40 words per variant.
The label should provide a compact, human-readable name for the phase of activity.
It should be recognizable in lists and diagrams without requiring the reader to open the full description.
It should emphasize the illicit or adverse cyber activity and the role of the adversary.
A good Diamond Event label should:
Email campaign.If the Event is reusable across diverse Patterns, make the label generic but specific enough to be useful.
Use the schema to mark or classify Common Events where possible, rather than forcing the word Common into the label unless the data model requires it.
[Pattern or Common] + [adversary action] + [target or goal] + [key vector]
Credential harvesting via cloned webmail portal
Initial access via commodity ransomware affiliate kit
Account takeover using SIM-swap fraud
The shortDescription should provide a single-sentence summary of the Diamond Event as a complete phase.
It should make the linkage between the four core elements explicit at a high level.
It should allow a reader to quickly decide whether this Event is the one they want.
In 40 words or less, the short description should:
A [role player] uses [capability] via [infrastructure] to [impact on victim] as [phase role] in [Pattern or Market context].
The longDescription should provide a multi-dimensional narrative of the phase.
It should explain:
Within 250 words, the long description should:
Paragraph 1: Context and phase role
Identify the activity as a Diamond Event and summarize its purpose and phase within Patterns.
Paragraph 2: Four elements
Describe Adversary, Capability, Infrastructure, Victim, and Impact in an integrated narrative.
Paragraph 3: Relationships and reuse
Explain links to Patterns, Markets, common predecessor or successor Events, and whether the Event is reusable.
Label:
[Pattern or Common] + [phase-level action] + [target or goal] + [key vector]
alsoCalled:
[Common alternative names for the phase, if any]
shortDescription:
A [role player] uses [capability] via [infrastructure] to [impact on victim] as [phase role] in [Pattern or Market context].
longDescription:
[Paragraph 1: Identify the activity as a Diamond Event and explain its phase role.]
[Paragraph 2: Describe the role player, capability, infrastructure, victim, and impact.]
[Paragraph 3: Explain Pattern, Market, chaining, reuse, or Common Event relationships.]
variant:
[Optional recurring variation, 40 words or less.]
A Products and Services entity, also referred to as a commodity, describes a product, service, tool, dataset, credential set, infrastructure service, or other tradable or usable item in the cybercrime ecosystem.
A commodity can be added to any number of Diamond Events for a given Pattern.
A Diamond Event can be linked to any number of commodities.
A commodity can be linked to any number of Diamond Events.
rdfs:labelName the commodity, product, service, or tradable category.
alsoCalledInclude common marketplace names, slang, abbreviations, or ecosystem terms.
shortDescriptionDefine what is traded or used and why it matters operationally.
longDescriptionDescribe the function, buyers and sellers, operational role, and relationship to Patterns, Markets, or Diamond Events.
variantCapture common variations in product form, service model, delivery model, or use context.
Label:
[Product, service, tool, dataset, credential set, or commodity category]
alsoCalled:
[Common marketplace names, slang, or abbreviations]
shortDescription:
[One-sentence explanation of what the commodity is and what it enables.]
longDescription:
[Paragraph 1: Define the commodity and its function.]
[Paragraph 2: Explain how it is obtained, sold, rented, operated, or used.]
[Paragraph 3: Explain its relationship to Patterns, Markets, role players, or Diamond Events.]
variant:
[Optional recurring variation, 40 words or less.]
A Market represents a supply chain, underground service, managed service, or trading context in which products, services, or activities are exchanged.
rdfs:labelName the market, supply chain, or service model.
alsoCalledInclude common market names, ecosystem terms, or abbreviations.
shortDescriptionSummarize what is traded, who participates, and what the Market enables.
longDescriptionDescribe traded commodities, buyers, sellers, platforms, role players, and links to Patterns or Diamond Events.
variantCapture recurring market-model variations.
Label:
[Market, supply chain, or service model name]
alsoCalled:
[Common alternative terms]
shortDescription:
[One-sentence summary of what is traded and what the Market enables.]
longDescription:
[Paragraph 1: Define the Market and the activity or service model.]
[Paragraph 2: Describe buyers, sellers, role players, commodities, and platforms.]
[Paragraph 3: Explain links to Patterns, Diamond Events, or other Markets.]
variant:
[Optional recurring variation, 40 words or less.]
A Role Player describes a functional role in the cybercrime ecosystem.
A Role Player is not a named person, organization, campaign, or incident.
rdfs:labelName the role, not an individual person, group, or campaign.
alsoCalledInclude common role aliases, slang, or ecosystem terms.
shortDescriptionState what the role player does and how they contribute to the activity.
longDescriptionDescribe responsibilities, capabilities, relationships to other roles, and where the role appears in Patterns, Markets, or Diamond Events.
variantCapture recurring variations in role specialization, operating model, or relationship to other roles.
Label:
[Functional role name]
alsoCalled:
[Common role aliases or ecosystem terms]
shortDescription:
[One-sentence description of what the role player does.]
longDescription:
[Paragraph 1: Define the role and its main responsibilities.]
[Paragraph 2: Describe capabilities, resources, and operating context.]
[Paragraph 3: Explain relationships to other roles, Markets, Patterns, or Diamond Events.]
variant:
[Optional recurring role variation, 40 words or less.]
A Platform describes infrastructure, services, environments, or channels that enable activity in Patterns, Markets, or Diamond Events.
rdfs:labelName the platform type or infrastructure category.
alsoCalledInclude common platform labels, ecosystem terms, or slang.
shortDescriptionExplain what the platform enables.
longDescriptionDescribe how the platform is used, who uses it, what it supports, and how it relates to Patterns, Markets, or Diamond Events.
variantCapture recurring variations in platform type, access model, or abuse context.
Label:
[Platform or infrastructure category]
alsoCalled:
[Common alternative terms]
shortDescription:
[One-sentence explanation of what the platform enables.]
longDescription:
[Paragraph 1: Define the platform and its function.]
[Paragraph 2: Explain how it is accessed, operated, or abused.]
[Paragraph 3: Explain links to Patterns, Markets, commodities, or Diamond Events.]
variant:
[Optional recurring platform variation, 40 words or less.]
A Victim entity describes a victim group, target category, or affected population.
rdfs:labelName the victim group or target category.
alsoCalledInclude widely used alternative victim-group names.
shortDescriptionIdentify who is affected and the relevant exposure or harm context.
longDescriptionDescribe why the group is targeted, how it is affected, and which Patterns or Diamond Events commonly involve it.
variantCapture recurring variations in victim type, sector, geography, scale, or exposure.
Label:
[Victim group or target category]
alsoCalled:
[Common alternative victim-group names]
shortDescription:
[One-sentence explanation of who is affected and why the group matters.]
longDescription:
[Paragraph 1: Define the victim group.]
[Paragraph 2: Explain why the group is targeted or exposed.]
[Paragraph 3: Describe common impacts and links to Patterns or Diamond Events.]
variant:
[Optional recurring victim variation, 40 words or less.]
A Harm entity describes an adverse impact or consequence experienced by a victim.
rdfs:labelName the harm or impact type.
alsoCalledInclude recognized alternative terms, not incident-specific phrases.
shortDescriptionDefine the harm in plain language.
longDescriptionExplain how the harm arises, who experiences it, and how it differs from related harms.
variantCapture recurring variations in how the harm manifests.
Label:
[Harm or impact type]
alsoCalled:
[Recognized alternative terms]
shortDescription:
[One-sentence plain-language definition of the harm.]
longDescription:
[Paragraph 1: Define the harm.]
[Paragraph 2: Explain how the harm arises in cybercrime activity.]
[Paragraph 3: Explain who experiences it and how it differs from related harms.]
variant:
[Optional recurring harm variation, 40 words or less.]
A Technique describes a technical or operational action at a level below a Diamond Event.
A Technique should support understanding of what happens within a phase, without replacing the phase-level Diamond Event description.
rdfs:labelUse the recognized technique name where available.
alsoCalledInclude common aliases, ATT&CK-style names, or recognized alternative labels where applicable.
shortDescriptionDefine the technical action at a high level.
longDescriptionExplain the technique purpose, typical use, and relationship to Pattern Phases.
Avoid procedural how-to detail.
variantCapture recurring variations in technique use or implementation.
Label:
[Recognized technique name]
alsoCalled:
[Common aliases or recognized alternative technique names]
shortDescription:
[One-sentence high-level definition of the technique.]
longDescription:
[Paragraph 1: Define the technique and its purpose.]
[Paragraph 2: Explain typical use at phase level.]
[Paragraph 3: Explain links to Pattern Phases, Tactics, or broader activity.]
variant:
[Optional recurring technique variation, 40 words or less.]
Use this when no more specific class template exists.
Label:
[Preferred human-readable entity name]
alsoCalled:
[Common aliases, if any]
shortDescription:
[One-sentence concise summary, 40 words or less unless class-specific guidance differs.]
longDescription:
[Full analytic description, 250 words or less unless class-specific guidance differs.]
variant:
[Optional recurring variation, 40 words or less.]
Use this structure when adding guidance for a new class.
## [Class Name]
### Purpose
[Explain what this class represents.]
### Field Rules
#### `rdfs:label`
[Label rule.]
#### `alsoCalled`
[Alias rule.]
#### `shortDescription`
[Short description rule.]
#### `longDescription`
[Long description rule.]
#### `variant`
[Variant rule.]
### [Class Name] Template
Label:
[...]
alsoCalled:
[...]
shortDescription:
[...]
longDescription:
[...]
variant:
[...]
shortDescription follows the relevant class-specific length and content rule.longDescription follows the relevant class-specific length and content rule.alsoCalled includes only useful, recurring aliases.variant describes a recurring variation, not a separate entity.longDescription covers illicit activity, Diamond Event flow, role players, ecosystem elements, victims, and impacts.shortDescription is one sentence and 40 words or less.shortDescription makes the four core elements explicit at a high level.longDescription explains phase role, four elements, and relationships.The source Word document contains several editorial issues that should be resolved in future revisions.
The Pattern section contains a note indicating a formatting mistake.
The substantive Pattern guidance has been preserved, but the formatting issue should be reviewed in the source material before future publication.
The Diamond Events section notes that compound events should be described.
This guide currently refers to Event chaining and reusable Common Events, but a future section should define Compound or Composite Events explicitly.
Suggested future section:
## Compound or Composite Diamond Events
### Purpose
[Define when a Diamond Event should be modeled as compound or composite.]
### Modeling Rules
[Explain when to chain Events, when to create a CompositePatternPhase, and when to reuse Common Events.]
longDescriptionThe source document contains an unresolved note asking whether a Diamond Event longDescription should include the name of the Diamond Event.
Current working rule:
A Diamond Event shortDescription should not include the Diamond Event name.
A Diamond Event longDescription may include the Diamond Event name when it improves clarity, but should not simply repeat the label without adding analytic value.
This guide should be extended over time with class-specific rules for additional ontology classes and subclasses.
Recommended future sections include:
Market_or_Supply_ChainUnderground_ServiceUnderground_Managed_ServiceCrimewarePayment_InstrumentsCredential_and_Identity_ArtifactsInfrastructure_ServicesSpecific_Victim_GroupsGeneral_Victim_GroupsEconomic_ImpactPsychological_ImpactOperational_ImpactPhysical_ImpactTacticA simple initial structure is:
docs/
index.md
ontology-reference.md
writing-guide.md
As the writing guidance grows, split the guide into child pages.
docs/
writing-guide/
index.md
shared-rules.md
class-specific-rules.md
patterns.md
pattern-phases.md
markets.md
products-and-services.md
role-players.md
platforms.md
victims.md
harms.md
techniques.md
review-checklists.md
For GitHub Pages navigation, the parent page can use this front matter:
---
title: Writing Guide
layout: default
nav_order: 3
has_children: true
---
Child pages can use this front matter:
---
title: Pattern Phases
layout: default
parent: Writing Guide
nav_order: 4
---