archsight 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 464d36ecbae64b55e25554f9d60d9c208fb2477ba1910f2318c415eef2cea018
-  data.tar.gz: e423de1798a1a0fc99f16220051139800780e6bd9f01b096bce378dda1ccb25e
+  metadata.gz: b601281c3dc26c95647876457b96e590146aee23b762d14034ed2ae5f0953710
+  data.tar.gz: 7c271d26e8def3f7e85d82210ebda0d45628e280c1bb58832b81f2900c3e1097
 SHA512:
-  metadata.gz: 0eb109e3f462b8ec1a23a17ab8c95d5d8bc176a5b54d038e47fa9dcf383e2597c9cc4a540efb1bd876714b279486dfd5a74d1bf1adc8c435a64db07913128890
-  data.tar.gz: 7ce31438036e3addcc8bda4e3587165f13b31399bd7a416323747d1552d9ae910c3e53191f8f7689f7b01a3d84508b9a32cf6cf7486fbb9bde3c0920560283bd
+  metadata.gz: 416c904c7b8ecc1c44527b226fe7e6c7697c03d905d855db532bb80f1bd5ff0ff1277c770947eed411a6ca7cae7dafd8e32085690d72a4235c73bd4c1f35950b
+  data.tar.gz: 9c22b78187060cdc3606b4f423a38b79f84edcee6cb1d6f1446348a9da46dc088bedb4f537c809aad28c2db33f875d490637c4dcc13b57b4ee0ccc76822a0193

data/docs/icons.md

@@ -11,25 +11,51 @@ Current icon assignments for each resource type:
 | ApplicationInterface | `usb` | <i class="iconoir-usb"></i> |
 | ApplicationService | `cube` | <i class="iconoir-cube"></i> |
 | BusinessActor | `community` | <i class="iconoir-community"></i> |
+| ApplicationEvent | `bell-notification` | <i class="iconoir-bell-notification"></i> |
 | BusinessControl | `shield-search` | <i class="iconoir-shield-search"></i> |
+| BusinessEvent | `flash` | <i class="iconoir-flash"></i> |
+| BusinessRole | `user-badge-check` | <i class="iconoir-user-badge-check"></i> |
 | BusinessProcess | `kanban-board` | <i class="iconoir-kanban-board"></i> |
 | BusinessProduct | `box-iso` | <i class="iconoir-box-iso"></i> |
 | ComplianceEvidence | `shield-check` | <i class="iconoir-shield-check"></i> |
 | DataObject | `database` | <i class="iconoir-database"></i> |
 | ApplicationComponent | `component` | <i class="iconoir-component"></i> |
 | TechnologySystemSoftware | `terminal-tag` | <i class="iconoir-terminal-tag"></i> |
+| MotivationAssessment | `stats-up-square` | <i class="iconoir-stats-up-square"></i> |
+| MotivationDriver | `fire-flame` | <i class="iconoir-fire-flame"></i> |
+| ImplementationDeliverable | `package` | <i class="iconoir-package"></i> |
+| ImplementationEvent | `calendar-check` | <i class="iconoir-calendar-check"></i> |
+| ImplementationGap | `git-compare` | <i class="iconoir-git-compare"></i> |
+| ImplementationPlateau | `packages` | <i class="iconoir-packages"></i> |
+| ImplementationWorkPackage | `hammer` | <i class="iconoir-hammer"></i> |
 | MotivationGoal | `archery` | <i class="iconoir-archery"></i> |
 | MotivationOutcome | `badge-check` | <i class="iconoir-badge-check"></i> |
+| MotivationPrinciple | `book` | <i class="iconoir-book"></i> |
 | MotivationRequirement | `task-list` | <i class="iconoir-task-list"></i> |
 | MotivationConstraint | `prohibition` | <i class="iconoir-prohibition"></i> |
 | MotivationStakeholder | `user-crown` | <i class="iconoir-user-crown"></i> |
 | TechnologyNode | `server-connection` | <i class="iconoir-server-connection"></i> |
 | StrategyCapability | `strategy` | <i class="iconoir-strategy"></i> |
 | TechnologyArtifact | `puzzle` | <i class="iconoir-puzzle"></i> |
+| TechnologyEvent | `warning-triangle` | <i class="iconoir-warning-triangle"></i> |
 | TechnologyInterface | `data-transfer-both` | <i class="iconoir-data-transfer-both"></i> |
 | TechnologyService | `cloud` | <i class="iconoir-cloud"></i> |
 | View | `view-grid` | <i class="iconoir-view-grid"></i> |
 
+## Layer Colours
+
+Icons and graph nodes take the colour of their layer.
+
+| Layer | Colour | Graph (light) | Icon |
+|-------|--------|---------------|------|
+| Strategy | orange | `#F4A261` | `#D4824A` |
+| Motivation | purple | `#CE93D8` | `#AB47BC` |
+| Business | yellow | `#F9DC5C` | `#D4B83C` |
+| Application | blue | `#6CBEED` | `#4A9ECD` |
+| Technology | green | `#8AC926` | `#7AB316` |
+| Implementation & Migration | rose | `#F48FB1` | `#E0527F` |
+| Other | gray | `#CCCCCC` | `#999999` |
+
 ## Icon Categories
 
 ### Technology & Development

data/docs/index.md.erb

@@ -31,15 +31,20 @@ Resources representing stakeholders, goals, outcomes, requirements, and constrai
 - [MotivationOutcome](/doc/resources/motivation_outcome) - End results or consequences
 - [MotivationRequirement](/doc/resources/motivation_requirement) - Compliance, legal and functional requirements
 - [MotivationConstraint](/doc/resources/motivation_constraint) - Limitations and restrictions
+- [MotivationDriver](/doc/resources/motivation_driver) - Threats, opportunities and other drivers
+- [MotivationAssessment](/doc/resources/motivation_assessment) - Risks, vulnerabilities and findings
+- [MotivationPrinciple](/doc/resources/motivation_principle) - Policies and principles
 
 ### Business Layer
 
 Resources representing business processes, actors, products, and the controls that guide processes.
 
 - [BusinessActor](/doc/resources/business_actor) - Teams and organizations
+- [BusinessRole](/doc/resources/business_role) - Responsibilities that actors take on
 - [BusinessProcess](/doc/resources/business_process) - Structured business workflows
 - [BusinessProduct](/doc/resources/business_product) - Products offered to customers
 - [BusinessControl](/doc/resources/business_control) - Controls that guide business processes
+- [BusinessEvent](/doc/resources/business_event) - Threat events, loss events and triggers
 
 ### Strategy Layer
 
@@ -54,6 +59,7 @@ Resources representing application services, components, and interfaces.
 - [ApplicationService](/doc/resources/application_service) - High-level application services
 - [ApplicationComponent](/doc/resources/application_component) - Logical parts of services
 - [ApplicationInterface](/doc/resources/application_interface) - APIs and interfaces between components
+- [ApplicationEvent](/doc/resources/application_event) - Threat events, loss events and triggers of applications
 - [DataObject](/doc/resources/data_object) - Data structures and schemas
 
 ### Technology Layer
@@ -63,9 +69,20 @@ Resources representing technology infrastructure and artifacts.
 - [TechnologyService](/doc/resources/technology_service) - Infrastructure services
 - [TechnologyArtifact](/doc/resources/technology_artifact) - Source code repositories
 - [TechnologyInterface](/doc/resources/technology_interface) - Technical interfaces
+- [TechnologyEvent](/doc/resources/technology_event) - Infrastructure events, scan findings and outages
 - [TechnologySystemSoftware](/doc/resources/technology_system_software) - Logical infrastructure components
 - [TechnologyNode](/doc/resources/technology_node) - Physical infrastructure
 
+### Implementation & Migration Layer
+
+Resources representing change: work, results, milestones and the states of the architecture between them.
+
+- [ImplementationWorkPackage](/doc/resources/implementation_work_package) - Projects, measures and remediation
+- [ImplementationDeliverable](/doc/resources/implementation_deliverable) - Results of work packages
+- [ImplementationEvent](/doc/resources/implementation_event) - Milestones, go-lives and deadlines
+- [ImplementationPlateau](/doc/resources/implementation_plateau) - Baseline, transition and target states
+- [ImplementationGap](/doc/resources/implementation_gap) - Differences between plateaus
+
 ### Other
 
 - [ComplianceEvidence](/doc/resources/compliance_evidence) - Evidence for compliance requirements

data/docs/modeling.md

@@ -18,6 +18,34 @@ Application Layer   What software supports the business
 Technology Layer    How software is built and deployed
 ```
 
+## Direction of Relations
+
+Model and read the architecture **top-down**: Motivation, Strategy, Business, Application, Technology; the
+Implementation & Migration layer describes change across all of them. A relation is written on an element and points
+to what that element depends on, is served by, or is answered by. Following relations from a high-level element
+therefore walks down to people, code and infrastructure, and the relations form a DAG: nothing may lead back to where
+it started. `archsight lint` reports every cycle (only `dependsOn` is exempt, because components may depend on each
+other at runtime).
+
+There are two families of verbs:
+
+| Family | Verbs | Written on | Points to |
+|--------|-------|------------|-----------|
+| Responsibility and provider (down) | `performedBy`, `ownedBy`, `executedBy`, `servedBy`, `guidedBy`, `maintainedBy`, `contributedBy`, `hasConcern`, `realizedThrough`, `exposes`, `mitigatedBy`, `influences`, `triggers`, `affects`, `assesses`, `contains`, `closedBy`, `compares` | the element that needs, uses or is concerned with something | what provides it or is responsible for it |
+| Realization (up) | `realizes`, `partiallyRealizes`, `plans`, `satisfies`, `evidencedBy` (on the evidenced element), `provides` | the concrete element | the abstract element it answers to (requirement, goal, capability, plateau) |
+
+Rules:
+
+- A pair of kinds never has the same relation in both directions: a goal `realizes` a requirement, a requirement does not
+  `realize` a goal. Reverse relations are shown for free as incoming relations.
+- Responsibility ends at the actor: process, control, risk, policy, work package point to a `BusinessRole`, the role
+  points to the `BusinessActor` that holds it, and the actor points to nothing further.
+- The docs draw realization chains top-down ("Requirement, down to Service") while the data is stored on the concrete
+  element, so the file of a service says what it realizes.
+- `mentions` and `depicts` are not part of this structure. They are derived from the text and diagrams of a resource
+  (never written in a file) and show how things are linked sideways, in prose and pictures. They neither follow nor
+  contradict the direction above and are left out of the cycle check.
+
 ## Starting Points
 
 ### Top-Down Modeling
@@ -54,6 +82,9 @@ Model **why** the architecture exists.
 | MotivationOutcome | For measurable results ("99.9% availability", "Sub-100ms response") |
 | MotivationRequirement | For must-have capabilities (compliance, functional needs) |
 | MotivationConstraint | For limitations (budget, regulations, technical debt) |
+| MotivationDriver | For threats, opportunities, regulation and market forces that motivate action (`driver/type`) |
+| MotivationAssessment | For risks, vulnerabilities, findings and supplier or protection-need analyses (`assessment/type`) |
+| MotivationPrinciple | For policies, guidelines and architecture principles (`principle/type`) |
 
 **Example chain:** Stakeholder "Security Team" → hasConcern → Goal "Achieve Compliance" → realizes → Requirement "Encrypt data at rest"
 
@@ -64,13 +95,33 @@ Model **who** does **what** in business terms.
 | Resource | When to Use |
 |----------|-------------|
 | BusinessActor | For teams, departments, or organizations |
+| BusinessRole | For responsibilities held by actors: control owner, risk owner, information security officer (`role/type`) |
 | BusinessProcess | For workflows that produce business value |
 | BusinessProduct | For offerings to customers (cloud services, APIs) |
 | BusinessControl | For controls that guide a process (access review, change approval), with an owner and executors |
+| BusinessEvent | For things that happen in the business: threat events, loss events, incidents, triggers (`event/type`) |
+
+**Example chain:** Process "Incident Response" → performedBy → Actor "Platform Team"; Process "Incident Response" → servedBy → Service "Monitoring"
+
+**Roles:** Process "Incident Response" → performedBy → Role "Incident Manager" → performedBy → Actor "Platform Team". Controls, risks, policies and work packages use `ownedBy` (and controls `executedBy`) the same way. Use a role where the responsibility has a name of its own and should survive a change of team; pointing straight at an actor stays valid.
+
+**Controls:** Process "Incident Response" → guidedBy → Control "Escalation Review" → ownedBy / executedBy → Role or Actor. How controls, requirements and evidence fit together is described under Relation Patterns below.
 
-**Example chain:** Actor "Platform Team" → performedBy → Process "Incident Response" → servedBy → Service "Monitoring"
+### Implementation & Migration Layer
+
+Model **change**: what is done, what it delivers and how the architecture looks before and after.
+
+| Resource | When to Use |
+|----------|-------------|
+| ImplementationWorkPackage | For projects, measures, remediation of risks and findings, audit programmes (`workpackage/type`, status, due date) |
+| ImplementationDeliverable | For the results of work packages: documents, systems, process changes, evidence (`deliverable/type`) |
+| ImplementationEvent | For milestones, go-lives and deadlines (`event/type`) |
+| ImplementationPlateau | For a state of the architecture: baseline, transition, target (`plateau/type`) |
+| ImplementationGap | For the difference between two plateaus (`gap/status`, `gap/impact`) |
 
-**Controls:** Process "Incident Response" → guidedBy → Control "Escalation Review" → ownedBy / executedBy → Actor "Platform Team". How controls, requirements and evidence fit together is described under Relation Patterns below.
+**Migration path:** Plateau "Baseline" → triggers → Plateau "Target"; Gap → compares → both plateaus; Work Package → realizes → Deliverable → realizes → Plateau "Target"; Gap → closedBy → Work Package.
+
+**Remediation:** Assessment "Risk" → mitigatedBy → Work Package → realizes → Deliverable (type `evidence`) → realizes → ComplianceEvidence. Group by `risk/domain` to see the plan of one domain, filter by `workpackage/status` and `workpackage/due` for what is open or late.
 
 ### Strategy Layer
 
@@ -189,6 +240,100 @@ spec:
   evidencedBy: { complianceEvidences: [Evidence:DeploymentAuditLog] }
 ```
 
+### Security and Risk
+
+Security and risk are modelled with the elements above, following the risk and security overlay of the Open Group
+white paper [Modeling Enterprise Risk Management and Security with the ArchiMate Language](#reference). There is no
+separate security layer: a concept is an ordinary element that carries a **type** (a specialization, the paper's
+"stereotype") plus profile annotations. The type is a filterable annotation, so views, queries and lists can group by it.
+
+| Security concept | Kind | Type annotation | Notes |
+|------------------|------|-----------------|-------|
+| Threat (circumstance) | `MotivationDriver` | `driver/type: threat` | also opportunity, regulation, market |
+| Threat agent | `BusinessActor`, `ApplicationComponent`, `TechnologyNode` | none | the `causedBy` of an event |
+| Threat event | `BusinessEvent`, `ApplicationEvent`, `TechnologyEvent` | `event/type: threat-event` or `attack` | `attack` = intentional |
+| Loss event, incident | the three event kinds | `event/type: loss-event` or `incident` | the layer says where it happens |
+| Risk | `MotivationAssessment` | `assessment/type: risk` | initial and residual profile, `risk/treatment` |
+| Vulnerability | `MotivationAssessment` | `assessment/type: vulnerability` | `assesses` the assets it is found on |
+| Control objective | `MotivationGoal` | `goal/type: control-objective` | the risk is `mitigatedBy` it |
+| Control measure | `MotivationRequirement` | `requirement/type: control-measure` | a goal `realizes` it; the risk can be `mitigatedBy` it |
+| Control implementation | `BusinessControl`, applications, nodes, processes | none | `satisfies` / `realizes` the measure |
+| Proof of the control | `ComplianceEvidence` | `evidence/type` | `evidence/status: not-applicable` where the requirement does not apply |
+| Asset at risk | any application, technology, data or process kind | `asset/value`, `asset/confidentiality`, `asset/integrity`, `asset/availability` | the protection need (BSI Schutzbedarf) |
+| Policy (design level) | `MotivationPrinciple` | `principle/type: security-policy` or `risk-policy` | status, validity, framework mapping |
+| Operational policy, regulation | `MotivationConstraint` | none | the paper has no element for operational policy |
+| Risk domain | none; annotation `risk/domain` | `risk/domain`, `risk/category` | group by it with a query or a `View` |
+
+The chain, as in the paper's Coldhard Steel example:
+
+```
+MotivationDriver (threat) ──influences──→ MotivationAssessment (risk) ──mitigatedBy──→ MotivationGoal (control objective)
+        │ triggers                                  │ assesses                                      │ realizes
+        ↓                                           ↓                                               ↓
+BusinessEvent (loss event) ←──influences── MotivationAssessment (vulnerability)      MotivationRequirement (control measure)
+        ↑ triggers                                                                                  ↑ satisfies / realizes
+TechnologyEvent / ApplicationEvent (threat event, attack)                         BusinessControl / asset ──evidencedBy──→ ComplianceEvidence
+```
+
+```yaml
+kind: MotivationDriver
+metadata: { name: Threat:Intrusion, annotations: { driver/type: threat } }
+spec:
+  influences: { motivationAssessments: [Risk:Intrusion] }
+  triggers:   { businessEvents: [Loss:DataLeak] }
+---
+kind: MotivationAssessment
+metadata:
+  name: Risk:Intrusion
+  annotations:
+    assessment/type: risk
+    risk/initial-likelihood: high
+    risk/residual-likelihood: low
+    risk/treatment: mitigate
+    risk/domain: customer-data
+spec:
+  ownedBy: { businessRoles: [Role:RiskOwner] }
+  assesses: { technologyNodes: [Node:Web1] }
+  mitigatedBy: { goals: [Objective:ReduceExposure], businessControls: [Control:FirewallReview] }
+---
+kind: MotivationGoal
+metadata: { name: Objective:ReduceExposure, annotations: { goal/type: control-objective } }
+spec:
+  realizes: { motivationRequirements: [Measure:Firewall] }
+---
+kind: MotivationRequirement
+metadata: { name: Measure:Firewall, annotations: { requirement/type: control-measure } }
+spec: {}
+---
+kind: BusinessControl
+metadata: { name: Control:FirewallReview }
+spec:
+  ownedBy: { businessRoles: [Role:ControlOwner] }
+  satisfies: { motivationRequirements: [Measure:Firewall] }
+```
+
+How to model it:
+
+- **Events and their types.** A threat event `triggers` a loss event; the three event kinds (business, application,
+  technology) say on which level it happens and a technology event may trigger an application or business event. Use
+  `event/type` to tell threat events, attacks, loss events, incidents, opportunity events, audits, scans and changes apart.
+- **Vulnerability scan.** One `MotivationAssessment` of type `vulnerability` per finding, `assesses` every node it was
+  found on, `influences` the loss events and risks it makes possible. Business impact follows from the model: the node
+  serves services, services serve processes.
+- **Grouping (risk domains).** ArchiMate has no domain element; set `risk/domain` (and `risk/category`: hazard,
+  financial, operational, strategic, compliance, security) on events, assessments, drivers, requirements, controls and
+  assets, and query or build a `View` per domain to see its threats, risks, measures and assets together.
+- **Policies.** The text of a policy is a `Page`; the structured statement (owner, validity, status, framework) is a
+  `MotivationPrinciple` that links to the page with `[[Page]]`.
+- **Initial and residual risk.** Record both on the assessment (`risk/initial-*`, `risk/residual-*`) and the decision
+  in `risk/treatment`.
+
+<a id="reference"></a>
+**Reference:** Band, Engelsman, Feltus, González Paredes, Hietala, Jonkers, Massart,
+[Modeling Enterprise Risk Management and Security with the ArchiMate Language](https://pure.unamur.be/ws/files/12366722/Modeling_Enterprise_Risk_Management_and_Secutity_with_the_ArchiMate_Language.pdf),
+The Open Group white paper (ArchiMate 2.1). For the NIST OSCAL vocabulary used for names of assessment and evidence
+fields see [OSCAL](https://pages.nist.gov/OSCAL/learn/concepts/layer/).
+
 ### Compliance Chain
 
 Shows how requirements are satisfied:

data/docs/togaf.md

@@ -122,12 +122,15 @@ The metamodel defines architectural entities and their relationships across all
 
 **Cross-Cutting:**
 
-- **Principle**, **Constraint**, **Requirement**, **Gap**, **Work Package**, **Location**
+- **Principle**, **Constraint**, **Requirement**, **Location**
+- **Gap**, **Work Package**, **Deliverable**, **Plateau**, **Implementation Event**: the Implementation & Migration layer (`ImplementationGap`, `ImplementationWorkPackage`, `ImplementationDeliverable`, `ImplementationPlateau`, `ImplementationEvent`)
 
 **Governance:**
 
 - **Control**: a decision-making step with accountability and authority, applied to a process or function. ArchiMate has no element for it; Archsight models it as `BusinessControl`, which a `BusinessProcess` is `guidedBy`
 
+**Risk and security:** the Open Group overlay (*Modeling Enterprise Risk Management and Security with the ArchiMate Language*) maps threats to **Driver** (`MotivationDriver`), threat and loss events to **Business/Application/Technology Event**, risks and vulnerabilities to **Assessment** (`MotivationAssessment`), control objectives to **Goal**, control measures to **Requirement** and policies to **Principle** (`MotivationPrinciple`), each with a type annotation. See [Modeling Guide](modeling.md#security-and-risk). How relations are directed (top-down, DAG) is described under [Direction of Relations](modeling.md#direction-of-relations).
+
 ### Critical Relationships
 
 1. **Traceability**: Drivers → Goals → Objectives → Course of Action → Business Elements → Applications → Technology

data/lib/archsight/annotations/asset_annotations.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Asset module adds the asset profile of an asset at risk: its value and its protection need (BSI "Schutzbedarf")
+module Archsight::Annotations::Asset
+  NEED = %w[normal high very-high].freeze
+
+  def self.included(base)
+    base.class_eval do
+      annotation "asset/value",
+                 description: "Value of the asset to the organization",
+                 title: "Asset value",
+                 enum: %w[low medium high critical],
+                 filter: :word
+
+      annotation "asset/confidentiality",
+                 description: "Protection need for confidentiality",
+                 title: "Confidentiality need",
+                 enum: Archsight::Annotations::Asset::NEED,
+                 filter: :word
+
+      annotation "asset/integrity",
+                 description: "Protection need for integrity",
+                 title: "Integrity need",
+                 enum: Archsight::Annotations::Asset::NEED,
+                 filter: :word
+
+      annotation "asset/availability",
+                 description: "Protection need for availability",
+                 title: "Availability need",
+                 enum: Archsight::Annotations::Asset::NEED,
+                 filter: :word
+    end
+  end
+end

data/lib/archsight/annotations/risk_annotations.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Risk module adds the annotations that group security and risk resources: the paper's "risk domain" and the
+# classification of the risk
+module Archsight::Annotations::Risk
+  def self.included(base)
+    base.class_eval do
+      annotation "risk/domain",
+                 description: "Risk domain(s) the resource belongs to (comma-separated); groups threats, risks, " \
+                              "vulnerabilities, measures and assets that share a context",
+                 title: "Risk domain",
+                 filter: :list
+
+      annotation "risk/category",
+                 description: "Classification of the risk (CAS enterprise risk classification, plus compliance and security)",
+                 title: "Risk category",
+                 enum: %w[hazard financial operational strategic compliance security],
+                 filter: :word
+    end
+  end
+end

data/lib/archsight/documentation.rb

@@ -7,7 +7,7 @@ module Archsight
   # Documentation generates markdown documentation for architecture resources
   class Documentation
     # Layer display order (top to bottom)
-    LAYER_ORDER = %w[motivation strategy business application technology].freeze
+    LAYER_ORDER = %w[motivation strategy business application technology implementation].freeze
 
     # Layer display names
     LAYER_NAMES = {
@@ -15,7 +15,8 @@ module Archsight
       "strategy" => "Strategy Layer",
       "business" => "Business Layer",
       "application" => "Application Layer",
-      "technology" => "Technology Layer"
+      "technology" => "Technology Layer",
+      "implementation" => "Implementation & Migration Layer"
     }.freeze
 
     # Resource kinds to exclude from the diagram

data/lib/archsight/linter.rb

@@ -8,6 +8,12 @@ module Archsight
     # Valid @component references in View annotations
     VALID_COMPONENTS = %w[activity git jira languages owner repositories status].freeze
 
+    # Relations the cycle check leaves out. Relations are followed from the dependent to what it relies on, so
+    # the declared ones form a DAG; `dependsOn` is the exception because components may depend on each other at
+    # runtime. The derived relations (`mentions`, `depicts`) are sideways views and are not declared, so they
+    # never enter the check.
+    CYCLE_EXEMPT_VERBS = %i[dependsOn].freeze
+
     def initialize(database)
       @database = database
       @errors = []
@@ -22,6 +28,7 @@ module Archsight
           validate_menu(instance) if instance.klass == "PageMenu"
         end
       end
+      validate_relation_cycles
 
       @errors
     end
@@ -79,6 +86,103 @@ module Archsight
       nil
     end
 
+    # Declared relations must not lead back to where they started (see the "Direction of Relations" modeling guide)
+    def validate_relation_cycles
+      graph = relation_graph
+      strongly_connected_groups(graph).each do |group|
+        cycle = cycle_through(group.first, group, graph)
+        names = cycle.map { |step| step[:to].name }
+        start = group.first
+        path = ([start.name] + names).zip(cycle.map { |step| step[:verb] }).flat_map { |name, verb| [name, verb && "-#{verb}->"] }.compact
+        @errors << "#{start.path_ref}: #{start.klass} '#{start.name}' is part of a relation cycle (#{path.join(" ")})"
+      end
+    end
+
+    # { instance => [{ verb:, to: }] } over the declared relations
+    def relation_graph
+      graph = {}
+      @database.instances.each_value do |instances_hash|
+        instances_hash.each_value do |instance|
+          graph[instance] = instance.class.declared_relations.flat_map do |verb, key, _kind|
+            next [] if CYCLE_EXEMPT_VERBS.include?(verb)
+
+            instance.relations(verb, key).map { |target| { verb: verb, to: target } }
+          end
+        end
+      end
+      graph
+    end
+
+    # Groups of instances that reach each other (iterative Tarjan, the graph can be deep); a single instance counts
+    # only when it points at itself
+    def strongly_connected_groups(graph)
+      index = {}
+      lowlink = {}
+      on_stack = {}
+      stack = []
+      groups = []
+      counter = 0
+
+      graph.each_key do |root|
+        next if index.key?(root)
+
+        work = [[root, 0]]
+        until work.empty?
+          node, edge = work.last
+          if edge.zero?
+            index[node] = lowlink[node] = counter
+            counter += 1
+            stack << node
+            on_stack[node] = true
+          end
+
+          edges = graph[node] || []
+          if edge < edges.length
+            work.last[1] += 1
+            target = edges[edge][:to]
+            if !index.key?(target)
+              work << [target, 0]
+            elsif on_stack[target]
+              lowlink[node] = [lowlink[node], index[target]].min
+            end
+          else
+            work.pop
+            lowlink[work.last.first] = [lowlink[work.last.first], lowlink[node]].min unless work.empty?
+            next unless lowlink[node] == index[node]
+
+            group = []
+            loop do
+              member = stack.pop
+              on_stack[member] = false
+              group << member
+              break if member.equal?(node)
+            end
+            groups << group if group.length > 1 || edges.any? { |e| e[:to].equal?(node) }
+          end
+        end
+      end
+      groups
+    end
+
+    # One concrete cycle through `start` inside its group: [{ verb:, to: }, ...] ending at `start`
+    def cycle_through(start, group, graph)
+      members = group.to_h { |member| [member, true] }
+      queue = [[start, []]]
+      seen = { start => true }
+      until queue.empty?
+        node, path = queue.shift
+        graph[node].each do |edge|
+          next unless members[edge[:to]]
+          return path + [edge] if edge[:to].equal?(start)
+          next if seen[edge[:to]]
+
+          seen[edge[:to]] = true
+          queue << [edge[:to], path + [edge]]
+        end
+      end
+      []
+    end
+
     def validate_instance_annotations(instance)
       instance.annotations.each do |key, value|
         # Find matching annotation definition (handles both exact and pattern matches)

data/lib/archsight/resources/application_component.rb

@@ -2,7 +2,7 @@
 
 # ApplicationComponent a part of the ApplicationService
 class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
-  include_annotations :git, :architecture, :generated, :backup
+  include_annotations :git, :architecture, :generated, :backup, :asset, :risk
 
   description <<~MD
     Represents a logical part of an application service that can be deployed independently.
@@ -24,6 +24,13 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
     - Backend components
     - Frontend applications
     - Background workers
+
+    ## Security and risk modelling
+
+    - **Asset at risk:** set `asset/value` and the protection needs; `assesses` from a vulnerability or risk.
+    - **Control implementation:** a component that implements a control measure `realizes` the requirement and is
+      `evidencedBy` evidence.
+    - **Threat agent:** a component can be the `causedBy` of an event (a compromised service).
   MD
 
   icon "component"

data/lib/archsight/resources/application_event.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# ApplicationEvent represents an application event: something that happens in an application and triggers or interrupts application behavior
+class Archsight::Resources::ApplicationEvent < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
+
+  description <<~MD
+    Represents an application event: something that happens in an application and triggers or interrupts application behavior.
+
+    ## ArchiMate Definition
+
+    **Layer:** Application
+    **Aspect:** Behavior
+
+    An event is something that happens and influences behavior. It does not last: it triggers or interrupts
+    processes and services. In the risk and security overlay of the Open Group paper (*Modeling Enterprise Risk
+    Management and Security with the ArchiMate Language*) a threat event and a loss event are events that carry a
+    type; set `event/type` to say which.
+
+    ## Usage
+
+    Use ApplicationEvent for events on the application level:
+
+    - Threat events and loss events of applications (an exploit of a service, a burst of failed logins, a data leak)
+    - Security alerts raised by an application
+    - Triggers of application services (a message arrives, a job is scheduled)
+
+    ## Event types
+
+    - `threat-event`: an event with the potential to harm an asset; it can trigger a loss event
+    - `attack`: a threat event caused by intentional malicious activity
+    - `loss-event`: an event that harms an asset (a hazard materialises, a vulnerability is exploited)
+    - `incident`: a loss event that has happened
+    - `opportunity-event`: an event that can add value
+    - `audit`, `scan`, `change`: events that produce assessments or alter the architecture
+    - `other`
+
+    Filter, group and query by `event/type`, `risk/domain` and `risk/category` to see, for example, every loss
+    event of a risk domain.
+
+    ## How it connects
+
+    - A threat event `triggers` a loss event or a process or service; threat and loss events may sit on different
+      layers (a technology event triggers an application or business event)
+    - `causedBy` the threat agent (an actor, component or node)
+    - `affects` the assets it harms
+    - A `MotivationDriver` (the threat) `triggers` it; a vulnerability `MotivationAssessment` `influences` it
+  MD
+
+  icon "bell-notification"
+  layer "application"
+
+  annotation "event/type",
+             description: "What kind of event this is (specialization of the event, see the risk and security overlay)",
+             enum: %w[threat-event attack loss-event incident opportunity-event audit scan change other],
+             filter: :word,
+             summary: true
+
+  annotation "event/severity",
+             description: "Severity of the event",
+             enum: %w[info low medium high critical],
+             filter: :word,
+             summary: true
+
+  annotation "event/occurred",
+             description: "When the event happened or is expected (ISO 8601 date or time)",
+             title: "Occurred",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  relation :triggers, :applicationServices, :ApplicationService
+  relation :triggers, :applicationEvents, :ApplicationEvent
+  relation :triggers, :businessEvents, :BusinessEvent
+  relation :causedBy, :businessActors, :BusinessActor
+  relation :causedBy, :applicationComponents, :ApplicationComponent
+  relation :causedBy, :technologyNodes, :TechnologyNode
+  relation :affects, :applicationServices, :ApplicationService
+  relation :affects, :applicationComponents, :ApplicationComponent
+  relation :affects, :dataObjects, :DataObject
+end

data/lib/archsight/resources/application_service.rb

@@ -2,7 +2,7 @@
 
 # ApplicationService represents the high level application service that implements capabilities
 class Archsight::Resources::ApplicationService < Archsight::Resources::Base
-  include_annotations :git, :architecture, :generated, :backup
+  include_annotations :git, :architecture, :generated, :backup, :asset, :risk
 
   description <<~MD
     Represents a high-level application service that implements business capabilities.
@@ -24,6 +24,11 @@ class Archsight::Resources::ApplicationService < Archsight::Resources::Base
     - Logical groupings of application components
     - Services exposed to business processes
     - APIs and their implementations as a cohesive unit
+
+    ## Security and risk modelling
+
+    A service is an asset at risk (`asset/*` profile, protection needs) that loss events `affects`, a trigger target
+    for `ApplicationEvent`s, and the place where requirements are realized and evidenced.
   MD
 
   icon "cube"