archsight 0.3.1 → 0.3.3

data/lib/archsight/requirements.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Archsight
-  # The business requirements of a selection of resources, as the "Business Requirements" table of an instance page
-  # shows them, merged over all resources of the selection: one entry per BusinessRequirement, with the status the
+  # The requirements of a selection of resources, as the "Requirements" table of an instance page
+  # shows them, merged over all resources of the selection: one entry per MotivationRequirement, with the status the
   # resources give it (`realizes` = implemented, `partiallyRealizes` = partial, `plans` = planned).
   #
   #   Requirements.collect(db, of: 'ApplicationService: name =~ "Backup"', priority: ["must"])
@@ -12,7 +12,7 @@ module Archsight
     # Relation verb -> status, best first
     STATUSES = { "realizes" => "implemented", "partiallyRealizes" => "partial", "plans" => "planned" }.freeze
     PRIORITIES = %w[must should may].freeze
-    RELATION = :businessRequirements
+    RELATION = :motivationRequirements
 
     module_function
 
@@ -52,7 +52,7 @@ module Archsight
         row << cell.new(text: e[:by].map { |b| b[:name] }.join("\n")) if with_by
         row
       end
-      ViewTable::Table.new(title: spec[:title].to_s.empty? ? "Business Requirements" : spec[:title],
+      ViewTable::Table.new(title: spec[:title].to_s.empty? ? "Requirements" : spec[:title],
                            columns: ["Status", "Name", "Priority", "Story", ("Realized by" if with_by)].compact, rows: rows, total: entries.length)
     end
 

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"
@@ -346,4 +353,7 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
   relation :exposes, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationComponents, :ApplicationComponent
+  relation :realizes, :motivationRequirements, :MotivationRequirement
+  relation :plans, :motivationRequirements, :MotivationRequirement
+  relation :evidencedBy, :complianceEvidences, :ComplianceEvidence
 end

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_interface.rb

@@ -47,6 +47,6 @@ class Archsight::Resources::ApplicationInterface < Archsight::Resources::Base
              enum: ["none", "hard coded", "pbac", "abac", "rbac"]
 
   relation :servedBy, :technologyComponents, :TechnologyInterface
-  relation :realizes, :businessConstraints, :BusinessConstraint
+  relation :realizes, :motivationConstraints, :MotivationConstraint
   relation :serves, :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"
@@ -214,10 +219,10 @@ class Archsight::Resources::ApplicationService < Archsight::Resources::Base
   relation :realizedThrough, :applicationComponents, :ApplicationComponent
   relation :servedBy, :businessActors, :BusinessActor
   relation :servedBy, :technologyServices, :TechnologyService
-  relation :realizes, :businessConstraints, :BusinessConstraint
-  relation :realizes, :businessRequirements, :BusinessRequirement
-  relation :partiallyRealizes, :businessRequirements, :BusinessRequirement
-  relation :plans, :businessRequirements, :BusinessRequirement
+  relation :realizes, :motivationConstraints, :MotivationConstraint
+  relation :realizes, :motivationRequirements, :MotivationRequirement
+  relation :partiallyRealizes, :motivationRequirements, :MotivationRequirement
+  relation :plans, :motivationRequirements, :MotivationRequirement
   relation :realizes, :dataObjects, :DataObject
   relation :evidencedBy, :complianceEvidences, :ComplianceEvidence
 end

data/lib/archsight/resources/base.rb

@@ -15,12 +15,21 @@ module Archsight
       end
 
       def self.relation(verb, kind, klass_name)
-        @relations ||= [] #: Array[[Symbol, Symbol, String]]
-        @relations << [verb, kind, klass_name]
+        @declared_relations ||= [] #: Array[[Symbol, Symbol, String]]
+        @declared_relations << [verb, kind, klass_name]
+        @relations = nil
       end
 
+      # The relations a resource of this kind may be written with in a file (`spec`)
+      def self.declared_relations
+        @declared_relations || []
+      end
+
+      # Every relation a resource of this kind can have: the declared ones and the derived ones (`mentions`,
+      # `depicts`, see Archsight::References). Everything that follows relations (queries, graphs, impact analysis)
+      # uses this; what lets a user write or choose relations uses declared_relations.
       def self.relations
-        @relations || []
+        @relations ||= (declared_relations + Archsight::Resources::DERIVED_RELATIONS).freeze
       end
 
       # A kind may mark at most this many annotations as summary (see Base.annotation)
@@ -111,6 +120,17 @@ module Archsight
         annotation_matching(key)&.format
       end
 
+      # The formats this kind defines for the given annotation keys, `{ "evidence/gaps" => "markdown" }` (keys without
+      # a format are left out). The frontend shows each value accordingly.
+      def self.annotation_formats(keys)
+        formats = {} #: Hash[String, String]
+        keys.each do |key|
+          format = annotation_format(key)
+          formats[key] = format.to_s if format
+        end
+        formats
+      end
+
       def self.annotation_enum(key)
         annotation_matching(key)&.enum
       end
@@ -231,17 +251,32 @@ module Archsight
       end
 
       def verb_allowed?(verb)
-        self.class.relations.any? { |v, _, _| v.to_s == verb.to_s }
+        self.class.declared_relations.any? { |v, _, _| v.to_s == verb.to_s }
       end
 
       def verb_kind_allowed?(verb, kind)
-        self.class.relations.any? { |v, k, _| v.to_s == verb.to_s && k.to_s == kind.to_s }
+        self.class.declared_relations.any? { |v, k, _| v.to_s == verb.to_s && k.to_s == kind.to_s }
       end
 
       def relations(verb, kind)
         (spec[verb.to_s] || {})[kind.to_s] || []
       end
 
+      # Records a relation that is derived from this resource's text or diagram, not written in its file: the target
+      # goes into `spec` where the relations of this verb are read (so queries and graphs see it like any other) and
+      # learns about this resource as one that refers to it.
+      def add_derived_relation(verb, target)
+        key = Archsight::Resources::DERIVED_KEY.to_s
+        spec_root = (@raw["spec"] ||= {}) #: Hash[String, untyped]
+        by_key = (spec_root[verb.to_s] ||= {}) #: Hash[String, Array[Base]]
+        by_key[key] ||= [] #: Array[Base]
+        targets = by_key.fetch(key)
+        return if targets.any? { |known| known.equal?(target) }
+
+        targets << target
+        target.referenced_by(self, verb.to_sym)
+      end
+
       def set_relations(verb, kind, rels)
         spec[verb.to_s][kind.to_s] = rels
         rels.each { |rel| rel.referenced_by(self, verb) }

data/lib/archsight/resources/business_actor.rb

@@ -2,7 +2,7 @@
 
 # BusinessActor represents teams or organizational units
 class Archsight::Resources::BusinessActor < Archsight::Resources::Base
-  include_annotations :git, :architecture, :generated
+  include_annotations :git, :architecture, :generated, :asset, :risk
 
   description <<~MD
     Represents a team, organizational unit, or external entity that performs business behavior.
@@ -25,6 +25,14 @@ class Archsight::Resources::BusinessActor < Archsight::Resources::Base
     - External vendors or partners
     - Support organizations
     - Cross-functional groups
+
+    ## Security and risk modelling
+
+    - **Threat agent:** an actor (also an external one, such as an attacker group or a supplier) can be the
+      `causedBy` of a threat or loss event.
+    - **Owner and executor:** actors own risks (`MotivationAssessment` `ownedBy`), policies and controls, directly or through a `BusinessRole` they `performedBy`.
+    - **Asset:** a supplier or a team can be an asset at risk; set the `asset/*` profile and `assesses` it from a
+      supplier assessment.
   MD
 
   icon "community"

data/lib/archsight/resources/business_control.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# BusinessControl represents a control that guides a business process
+class Archsight::Resources::BusinessControl < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
+
+  description <<~MD
+    Represents a control: a safeguard or decision step with an owner that guides how a business process is carried out.
+
+    ## ArchiMate / TOGAF Definition
+
+    **Layer:** Business
+    **Aspect:** Behavior (guidance)
+
+    ArchiMate has no control element. TOGAF's content metamodel has one: a decision-making step with
+    accountability and authority, applied to a process or function. A control is therefore modelled as
+    a business-layer kind that a `BusinessProcess` is guided by (`guidedBy`).
+
+    ## Usage
+
+    Use BusinessControl to represent:
+
+    - Security and compliance controls (access review, network documentation, backup verification)
+    - Operational checks that a process must pass (change approval, four-eyes principle)
+    - Controls of a standard or framework (BSI C5, ISO 27001, SOC 2), linked to the requirements they satisfy
+
+    ## How it connects
+
+    - A `BusinessProcess` is `guidedBy` the control
+    - The control is `ownedBy` the actor or role that is accountable for it and `executedBy` the actors or roles that carry it out
+    - The control `satisfies` requirements and is `evidencedBy` compliance evidence
+
+    A control addresses requirements from the **process side**. Whether an application implements a requirement is
+    stated on the application (`realizes`, `plans`, `evidencedBy`), not on the control. Link evidence to a control
+    only for the records the control itself produces (reviews, diagrams, change history, audit logs), and set the
+    `evidence/type` of that evidence to `process`, `documentation` or `audit-log`.
+
+    Put the best practices and the evidence requirements of a control in the description.
+
+    ## Security and risk modelling
+
+    A control is the process-side implementation of a control measure. `satisfies` the requirements (catalogue
+    controls and control measures); a risk it reduces is `mitigatedBy` the control (written on the assessment).
+    Group controls with `risk/domain` and `risk/category`.
+  MD
+
+  icon "shield-search"
+  layer "business"
+
+  annotation "control/id",
+             description: "Identifier of the control in its catalogue (e.g. COS-07)",
+             title: "Control ID",
+             summary: true
+
+  annotation "control/status",
+             description: "Implementation status of the control",
+             enum: %w[implemented partial planned not-implemented],
+             filter: :word,
+             summary: true
+
+  annotation "control/frequency",
+             description: "How often the control is carried out",
+             enum: %w[continuous event-based daily weekly monthly quarterly semi-annually annually],
+             filter: :word,
+             summary: true
+
+  annotation "control/objective",
+             description: "What the control achieves, in one short paragraph",
+             title: "Objective",
+             format: :markdown
+
+  annotation "control/last-review",
+             description: "When the control was last reviewed (ISO 8601 date or time)",
+             title: "Last review",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  annotation "control/next-review",
+             description: "When the control is due for review (ISO 8601 date or time)",
+             title: "Next review",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  relation :ownedBy, :businessActors, :BusinessActor
+  relation :executedBy, :businessActors, :BusinessActor
+  relation :ownedBy, :businessRoles, :BusinessRole
+  relation :executedBy, :businessRoles, :BusinessRole
+  relation :satisfies, :motivationRequirements, :MotivationRequirement
+  relation :evidencedBy, :complianceEvidences, :ComplianceEvidence
+end

data/lib/archsight/resources/business_event.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# BusinessEvent represents a business event: something that happens in the business and triggers or interrupts business behavior
+class Archsight::Resources::BusinessEvent < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
+
+  description <<~MD
+    Represents a business event: something that happens in the business and triggers or interrupts business behavior.
+
+    ## ArchiMate Definition
+
+    **Layer:** Business
+    **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 BusinessEvent for events on the business level:
+
+    - Threat events and loss events of the business (fraud, supplier failure, loss of a facility, a failed audit)
+    - Incidents that stop a process or a service
+    - Triggers of business processes (a customer order, the end of a quarter)
+
+    ## 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 "flash"
+  layer "business"
+
+  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, :businessProcesses, :BusinessProcess
+  relation :triggers, :businessEvents, :BusinessEvent
+  relation :causedBy, :businessActors, :BusinessActor
+  relation :causedBy, :applicationComponents, :ApplicationComponent
+  relation :causedBy, :technologyNodes, :TechnologyNode
+  relation :affects, :businessProcesses, :BusinessProcess
+  relation :affects, :businessProducts, :BusinessProduct
+  relation :affects, :businessActors, :BusinessActor
+  relation :affects, :dataObjects, :DataObject
+end

data/lib/archsight/resources/business_process.rb

@@ -2,7 +2,7 @@
 
 # BusinessProcess represents a structured business workflow or procedure
 class Archsight::Resources::BusinessProcess < Archsight::Resources::Base
-  include_annotations :git, :architecture
+  include_annotations :git, :architecture, :asset, :risk
 
   description <<~MD
     Represents a sequence of business behaviors that achieves a specific outcome.
@@ -25,13 +25,21 @@ class Archsight::Resources::BusinessProcess < Archsight::Resources::Base
     - Change management processes
     - Release deployment pipelines
     - Support escalation processes
+
+    ## Security and risk modelling
+
+    A process is an asset at risk (set `asset/value` and the protection needs `asset/confidentiality`,
+    `asset/integrity`, `asset/availability`), is `guidedBy` the controls that protect it, is hit by loss
+    events and is triggered by events. Group it with `risk/domain`.
   MD
 
   icon "kanban-board"
   layer "business"
 
-  relation :realizes, :businessConstraints, :BusinessConstraint
-  relation :realizes, :businessRequirements, :BusinessRequirement
+  relation :realizes, :motivationConstraints, :MotivationConstraint
+  relation :realizes, :motivationRequirements, :MotivationRequirement
   relation :servedBy, :applicationServices, :ApplicationService
   relation :performedBy, :businessActors, :BusinessActor
+  relation :performedBy, :businessRoles, :BusinessRole
+  relation :guidedBy, :businessControls, :BusinessControl
 end

data/lib/archsight/resources/business_product.rb

@@ -198,8 +198,8 @@ class Archsight::Resources::BusinessProduct < Archsight::Resources::Base
   end
 
   relation :realizes, :strategyCapabilities, :StrategyCapability
-  relation :realizes, :businessConstraints, :BusinessConstraint
-  relation :realizes, :businessRequirements, :BusinessRequirement
+  relation :realizes, :motivationConstraints, :MotivationConstraint
+  relation :realizes, :motivationRequirements, :MotivationRequirement
   relation :servedBy, :businessActors, :BusinessActor
   relation :servedBy, :applicationServices, :ApplicationService
   relation :exposes, :applicationInterfaces, :ApplicationInterface

data/lib/archsight/resources/business_role.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# BusinessRole represents a responsibility that actors take on
+class Archsight::Resources::BusinessRole < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
+
+  description <<~MD
+    Represents the responsibility for performing specific behavior, to which an actor can be assigned.
+
+    ## ArchiMate Definition
+
+    **Layer:** Business
+    **Aspect:** Active Structure
+
+    A business role is the responsibility for performing specific behavior, to which an actor can be assigned. The
+    role is what a process, a control or a risk refers to; the actor (a team) holds the role. Changing who holds the
+    role changes it everywhere it is used.
+
+    ## Usage
+
+    Use BusinessRole to represent:
+
+    - Roles of an ISMS: information security officer, data protection officer, control owner, control executor,
+      risk owner
+    - Roles in a process (incident manager, release approver)
+    - Any responsibility that should not be tied to one team by name
+
+    ## How it connects
+
+    The responsibility edges point down to the role, and the role points down to the actor that holds it:
+
+    ```
+    BusinessProcess ──performedBy──▶ BusinessRole ──performedBy──▶ BusinessActor
+    BusinessControl ──ownedBy / executedBy──▶ BusinessRole
+    ```
+
+    - A `BusinessProcess` is `performedBy` the role, a `BusinessControl` is `ownedBy` and `executedBy` it
+    - Assessments, principles, work packages, deliverables and implementation events are `ownedBy` it
+    - The role is `performedBy` the actors that hold it
+    - Pointing straight at an actor stays valid; use a role where the responsibility has a name of its own
+
+    ## Security and risk modelling
+
+    Roles carry the accountability of the ISMS: the owner and executor roles of controls (BSI C5, ITGS), the owner of
+    a risk, the issuer of a policy. Use `role/type` to tell owners, executors and officers apart and `risk/domain`
+    to group roles by context.
+  MD
+
+  icon "user-badge-check"
+  layer "business"
+
+  annotation "role/id",
+             description: "Identifier of the role in its list (e.g. ISB, DPO)",
+             title: "Role ID",
+             summary: true
+
+  annotation "role/type",
+             description: "What kind of responsibility the role is (specialization of the role)",
+             enum: %w[owner executor officer reviewer operator other],
+             filter: :word,
+             summary: true
+
+  annotation "role/scope",
+             description: "What the role is responsible for, in a short paragraph",
+             title: "Scope",
+             format: :markdown
+
+  relation :performedBy, :businessActors, :BusinessActor
+end

data/lib/archsight/resources/compliance_evidence.rb

@@ -9,7 +9,7 @@ class Archsight::Resources::ComplianceEvidence < Archsight::Resources::Base
 
     ## ArchiMate Definition
 
-    **Layer:** Implementation & Migration
+    **Layer:** Business (as a kind; ArchiMate would place evidence in Implementation & Migration)
     **Aspect:** Passive Structure
 
     Compliance evidence represents tangible proof that a system or process meets specific
@@ -25,6 +25,19 @@ class Archsight::Resources::ComplianceEvidence < Archsight::Resources::Base
     - Test results and reports
     - Configuration documentation
     - Process documentation
+
+    ## Evidence of what
+
+    - **Of an application:** linked with `evidencedBy` from a service, component or technology element; it says how
+      that resource meets the requirement it `satisfies`
+    - **Of a control:** linked with `evidencedBy` from a `BusinessControl`; the records the control produces
+      (reviews, diagrams, change history, audit logs). Use `evidence/type` `process`, `documentation` or `audit-log`
+
+    ## Security and risk modelling
+
+    Evidence is the proof that a control measure works. Use `evidence/status` `not-applicable` when the requirement
+    does not apply (BSI "entbehrlich"). Evidence of risk treatment (a test, a review, an audit report) is linked
+    from the control or application it is about.
   MD
 
   icon "shield-check"
@@ -37,8 +50,36 @@ class Archsight::Resources::ComplianceEvidence < Archsight::Resources::Base
 
   annotation "evidence/status",
              description: "Current status of evidence",
-             enum: %w[implemented partial not-implemented],
+             enum: %w[implemented partial not-implemented not-applicable],
              summary: true
 
-  relation :satisfies, :businessRequirements, :BusinessRequirement
+  # The structured answer to "how does the evidenced resource meet the requirement": one markdown field per
+  # question. `architecture/description` stays a short summary; the fields hold the detail.
+  annotation "evidence/mechanism",
+             description: "How the requirement is implemented: the concrete mechanism and where it lives " \
+                          "(code, chart, configuration), as a short markdown list",
+             format: :markdown
+
+  annotation "evidence/coverage",
+             description: "What the mechanism covers and what it does not (data, flows, tenants, environments)",
+             format: :markdown
+
+  annotation "evidence/operatorView",
+             description: "Whether the mechanism holds against operators (admins, platform staff) or only against " \
+                          "other tenants; names the privileged paths",
+             format: :markdown
+
+  annotation "evidence/verification",
+             description: "How effectiveness is verified: tests, audits, documents; says so when there are none",
+             format: :markdown
+
+  annotation "evidence/gaps",
+             description: "Remaining gaps and open questions, the most important first",
+             format: :markdown
+
+  annotation "evidence/sources",
+             description: "Where the statements come from: repositories and files, wiki pages, tickets",
+             format: :markdown
+
+  relation :satisfies, :motivationRequirements, :MotivationRequirement
 end

data/lib/archsight/resources/data_object.rb

@@ -2,7 +2,7 @@
 
 # DataObject represents data structured for automated processing (ArchiMate Application Layer)
 class Archsight::Resources::DataObject < Archsight::Resources::Base
-  include_annotations :git, :architecture, :generated
+  include_annotations :git, :architecture, :generated, :asset, :risk
 
   description <<~MD
     Represents data structured for automated processing by applications.
@@ -25,6 +25,11 @@ class Archsight::Resources::DataObject < Archsight::Resources::Base
     - Message payloads
     - Configuration structures
     - Domain models
+
+    ## Security and risk modelling
+
+    Data objects carry the information assets: set `asset/value` and the protection needs
+    (`asset/confidentiality`, `asset/integrity`, `asset/availability`, BSI Schutzbedarf), and `risk/domain`.
   MD
 
   icon "database"
@@ -46,5 +51,5 @@ class Archsight::Resources::DataObject < Archsight::Resources::Base
              title: "Schema Variants",
              sidebar: false
 
-  relation :realizes, :businessConstraints, :BusinessConstraint
+  relation :realizes, :motivationConstraints, :MotivationConstraint
 end