archsight 0.3.2 → 0.3.3

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

@@ -2,7 +2,7 @@
 
 # BusinessControl represents a control that guides a business process
 class Archsight::Resources::BusinessControl < Archsight::Resources::Base
-  include_annotations :git, :architecture
+  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.
@@ -27,7 +27,7 @@ class Archsight::Resources::BusinessControl < Archsight::Resources::Base
     ## How it connects
 
     - A `BusinessProcess` is `guidedBy` the control
-    - The control is `ownedBy` the actor that is accountable for it and `executedBy` the actors that carry it out
+    - 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
@@ -36,6 +36,12 @@ class Archsight::Resources::BusinessControl < Archsight::Resources::Base
     `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"
@@ -75,6 +81,8 @@ class Archsight::Resources::BusinessControl < Archsight::Resources::Base
 
   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,6 +25,12 @@ 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"
@@ -34,5 +40,6 @@ class Archsight::Resources::BusinessProcess < Archsight::Resources::Base
   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_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
@@ -32,6 +32,12 @@ class Archsight::Resources::ComplianceEvidence < Archsight::Resources::Base
       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"
@@ -44,7 +50,7 @@ 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
 
   # The structured answer to "how does the evidenced resource meet the requirement": one markdown field per

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"

data/lib/archsight/resources/implementation_deliverable.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# ImplementationDeliverable represents a precisely defined result of a work package
+class Archsight::Resources::ImplementationDeliverable < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
+
+  description <<~MD
+    Represents a precisely defined result of a work package.
+
+    ## ArchiMate Definition
+
+    **Layer:** Implementation & Migration
+    **Aspect:** Passive Structure
+
+    A deliverable is a tangible or intangible result that a work package produces: a document, a system, a changed
+    process. It realizes requirements, goals and plateaus.
+
+    ## Usage
+
+    Use ImplementationDeliverable to represent:
+
+    - Documents and reports produced by a project or an audit
+    - Systems and process changes that go live
+    - The artefact that becomes compliance evidence once it exists
+
+    ## How it connects
+
+    - A `ImplementationWorkPackage` `realizes` it
+    - It is `ownedBy` an actor and `realizes` plateaus, requirements, goals, outcomes and `ComplianceEvidence`
+
+    ## Security and risk modelling
+
+    A deliverable of type `evidence` that `realizes` a `ComplianceEvidence` ties the plan (work package) to the proof
+    (evidence) of a control measure.
+  MD
+
+  icon "package"
+  layer "implementation"
+
+  annotation "deliverable/type",
+             description: "What kind of result this is (specialization of the deliverable)",
+             enum: %w[document system process-change report evidence],
+             filter: :word,
+             summary: true
+  annotation "deliverable/status",
+             description: "Where the result is",
+             enum: %w[planned in-progress delivered accepted],
+             filter: :word,
+             summary: true
+  annotation "deliverable/due",
+             description: "When the result is due (ISO 8601 date or time)",
+             title: "Due",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  relation :ownedBy, :businessActors, :BusinessActor
+  relation :ownedBy, :businessRoles, :BusinessRole
+  relation :realizes, :implementationPlateaus, :ImplementationPlateau
+  relation :realizes, :motivationRequirements, :MotivationRequirement
+  relation :realizes, :goals, :MotivationGoal
+  relation :realizes, :outcomes, :MotivationOutcome
+  relation :realizes, :complianceEvidences, :ComplianceEvidence
+end

data/lib/archsight/resources/implementation_event.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# ImplementationEvent represents a state change related to implementation or migration
+class Archsight::Resources::ImplementationEvent < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
+
+  description <<~MD
+    Represents a state change related to implementation or migration.
+
+    ## ArchiMate Definition
+
+    **Layer:** Implementation & Migration
+    **Aspect:** Behavior
+
+    An implementation event is something that happens during implementation or migration and may trigger work: a
+    milestone reached, a go-live, a decommissioning, a review date or a deadline.
+
+    ## Usage
+
+    Use ImplementationEvent to represent:
+
+    - Milestones and go-lives of a roadmap
+    - Deadlines (certification audit, end of a transition period)
+    - Reviews and decommissioning dates
+
+    ## How it connects
+
+    - `ownedBy` an actor
+    - `triggers` work packages and plateaus
+
+    Events of the running architecture (threat and loss events, incidents) are `BusinessEvent`, `ApplicationEvent`
+    and `TechnologyEvent`.
+  MD
+
+  icon "calendar-check"
+  layer "implementation"
+
+  annotation "event/type",
+             description: "What kind of event this is (specialization of the implementation event)",
+             enum: %w[milestone go-live decommission review deadline],
+             filter: :word,
+             summary: true
+  annotation "event/occurred",
+             description: "When the event happens or happened (ISO 8601 date or time)",
+             title: "Occurred",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  relation :ownedBy, :businessActors, :BusinessActor
+  relation :ownedBy, :businessRoles, :BusinessRole
+  relation :triggers, :implementationWorkPackages, :ImplementationWorkPackage
+  relation :triggers, :implementationPlateaus, :ImplementationPlateau
+end

data/lib/archsight/resources/implementation_gap.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# ImplementationGap represents the difference between two plateaus
+class Archsight::Resources::ImplementationGap < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
+
+  description <<~MD
+    Represents a statement of difference between two plateaus.
+
+    ## ArchiMate Definition
+
+    **Layer:** Implementation & Migration
+    **Aspect:** Passive Structure
+
+    A gap is what is missing between a baseline and a target plateau: elements to add, change or remove. It is
+    the starting point of gap analysis in the TOGAF ADM.
+
+    ## Usage
+
+    Use ImplementationGap to represent:
+
+    - The difference between today's and the target architecture
+    - Requirements of a standard that are not met yet (compliance gap)
+    - The part of a plateau transition that a work package still has to deliver
+
+    ## How it connects
+
+    - A gap `compares` the plateaus it lies between (baseline and target)
+    - It is `closedBy` the work packages and deliverables that remove it
+  MD
+
+  icon "git-compare"
+  layer "implementation"
+
+  annotation "gap/status",
+             description: "Whether the gap is being closed",
+             enum: %w[open closing closed],
+             filter: :word,
+             summary: true
+  annotation "gap/impact",
+             description: "How much the gap matters",
+             enum: %w[low medium high critical],
+             filter: :word,
+             summary: true
+
+  relation :compares, :implementationPlateaus, :ImplementationPlateau
+  relation :closedBy, :implementationWorkPackages, :ImplementationWorkPackage
+  relation :closedBy, :implementationDeliverables, :ImplementationDeliverable
+end

data/lib/archsight/resources/implementation_plateau.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# ImplementationPlateau represents a relatively stable state of the architecture
+class Archsight::Resources::ImplementationPlateau < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
+
+  description <<~MD
+    Represents a relatively stable state of the architecture that exists during a limited period of time.
+
+    ## ArchiMate Definition
+
+    **Layer:** Implementation & Migration
+    **Aspect:** Composite
+
+    A plateau is a coherent set of architecture elements as they exist (or will exist) in one period. Plateaus
+    are the points of a migration path: baseline, transition states, target.
+
+    ## Usage
+
+    Use ImplementationPlateau to represent:
+
+    - The baseline (today's architecture) and the target architecture
+    - Transition architectures of a roadmap
+    - The state of the ISMS scope at a certification date
+
+    ## How it connects
+
+    - A plateau `contains` the components, services, nodes, processes and requirements that belong to it
+    - It `triggers` the next plateau (migration path)
+    - A `ImplementationDeliverable` `realizes` it; a `ImplementationGap` `compares` two plateaus
+  MD
+
+  icon "packages"
+  layer "implementation"
+
+  annotation "plateau/type",
+             description: "Position on the migration path",
+             enum: %w[baseline transition target],
+             filter: :word,
+             summary: true
+  annotation "plateau/status",
+             description: "Where the plateau is",
+             enum: %w[planned current past],
+             filter: :word,
+             summary: true
+  annotation "plateau/from",
+             description: "When the plateau starts (ISO 8601 date or time)",
+             title: "From",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+  annotation "plateau/until",
+             description: "When the plateau ends (ISO 8601 date or time)",
+             title: "Until",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  relation :contains, :applicationComponents, :ApplicationComponent
+  relation :contains, :applicationServices, :ApplicationService
+  relation :contains, :technologyNodes, :TechnologyNode
+  relation :contains, :businessProcesses, :BusinessProcess
+  relation :contains, :motivationRequirements, :MotivationRequirement
+  relation :triggers, :implementationPlateaus, :ImplementationPlateau
+end

data/lib/archsight/resources/implementation_work_package.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# ImplementationWorkPackage represents a series of actions that achieves a result within a time frame
+class Archsight::Resources::ImplementationWorkPackage < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
+
+  description <<~MD
+    Represents a series of actions identified and designed to achieve specific results within specified time and resource constraints.
+
+    ## ArchiMate Definition
+
+    **Layer:** Implementation & Migration
+    **Aspect:** Behavior
+
+    A work package is a piece of work with a defined start and end that produces deliverables. It is how the
+    architecture changes: projects, measures, remediation of findings, roadmap items.
+
+    ## Usage
+
+    Use ImplementationWorkPackage to represent:
+
+    - Projects and roadmap items that move the architecture from one plateau to the next
+    - Measures and realisation plans of an ISMS (due date, status, owner)
+    - Remediation of a risk, vulnerability or audit finding (the `MotivationAssessment` is `mitigatedBy` the work package)
+    - Audit programmes and recurring reviews
+
+    ## How it connects
+
+    - `ownedBy` the accountable actor or role, `performedBy` the actors or roles that carry it out
+    - `realizes` deliverables (its results), requirements and goals
+    - `affects` the assets it changes; the assessments (risks, findings) it treats are `mitigatedBy` it (written on the assessment)
+    - `triggers` the work packages that follow it; an `ImplementationEvent` can trigger it
+    - A `ImplementationGap` is `closedBy` it
+
+    ## Security and risk modelling
+
+    Set `workpackage/type` `remediation` and list the work package under `mitigatedBy` of the risk or finding to see what is open; filter
+    by `workpackage/status`, `workpackage/due` and `risk/domain` for the plan of one domain.
+  MD
+
+  icon "hammer"
+  layer "implementation"
+
+  annotation "workpackage/type",
+             description: "What kind of work this is (specialization of the work package)",
+             enum: %w[project measure remediation audit-programme change],
+             filter: :word,
+             summary: true
+  annotation "workpackage/status",
+             description: "Where the work is",
+             enum: %w[planned in-progress done cancelled],
+             filter: :word,
+             summary: true
+  annotation "workpackage/priority",
+             description: "How urgent the work is",
+             enum: %w[low medium high critical],
+             filter: :word
+  annotation "workpackage/start",
+             description: "When the work starts (ISO 8601 date or time)",
+             title: "Start",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+  annotation "workpackage/due",
+             description: "When the work is due (ISO 8601 date or time)",
+             title: "Due",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+  annotation "workpackage/completed",
+             description: "When the work was completed (ISO 8601 date or time)",
+             title: "Completed",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  relation :ownedBy, :businessActors, :BusinessActor
+  relation :performedBy, :businessActors, :BusinessActor
+  relation :ownedBy, :businessRoles, :BusinessRole
+  relation :performedBy, :businessRoles, :BusinessRole
+  relation :realizes, :implementationDeliverables, :ImplementationDeliverable
+  relation :realizes, :motivationRequirements, :MotivationRequirement
+  relation :realizes, :goals, :MotivationGoal
+  relation :affects, :businessProcesses, :BusinessProcess
+  relation :affects, :applicationComponents, :ApplicationComponent
+  relation :affects, :applicationServices, :ApplicationService
+  relation :affects, :technologyNodes, :TechnologyNode
+  relation :triggers, :implementationWorkPackages, :ImplementationWorkPackage
+end