archsight 0.3.1 → 0.3.3

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

data/lib/archsight/resources/motivation_assessment.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# MotivationAssessment represents the outcome of an analysis: a risk, a vulnerability, a finding
+class Archsight::Resources::MotivationAssessment < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
+
+  description <<~MD
+    Represents the outcome of an analysis of some aspect of the architecture with respect to a driver: a risk, a
+    vulnerability, an audit finding, a supplier or protection-need assessment.
+
+    ## ArchiMate Definition
+
+    **Layer:** Motivation
+    **Aspect:** Behavior
+
+    An assessment is the outcome of an analysis of the state of affairs of the enterprise with respect to some
+    driver. In the risk and security overlay of the Open Group paper (*Modeling Enterprise Risk Management and
+    Security with the ArchiMate Language*) a **risk** is a quantification of a threat and a **vulnerability** is
+    the result of analysing weaknesses of architecture elements; both are assessments with a type. Set
+    `assessment/type` to say which.
+
+    ## Usage
+
+    Use MotivationAssessment to represent:
+
+    - Risks (`risk`) with an initial and a residual profile and a treatment decision
+    - Vulnerabilities (`vulnerability`), also the results of a scan or penetration test
+    - Audit and review findings (`finding`)
+    - Supplier assessments (`supplier`) and protection-need analyses (`protection-need`)
+
+    ## Risk profile
+
+    Initial risk is the risk before mitigation, residual risk the one after. Describe both with likelihood and
+    impact (`risk/initial-*`, `risk/residual-*`) and record the decision in `risk/treatment` (avoid, transfer,
+    mitigate, accept).
+
+    ## How it connects
+
+    - A `MotivationDriver` (the threat) `influences` the risk
+    - The assessment `assesses` the assets it is about (applications, nodes, processes, data, suppliers)
+    - A vulnerability `influences` the loss events it makes possible; a risk `influences` other risks
+    - It is `mitigatedBy` a `MotivationGoal` (control objective), a `MotivationRequirement` (control measure), a
+      `BusinessControl` or an `ImplementationWorkPackage` (remediation); read top-down: risk, objective, measure,
+      control
+    - It is `ownedBy` the accountable actor or role
+  MD
+
+  icon "stats-up-square"
+  layer "motivation"
+
+  likelihood = %w[very-low low medium high very-high]
+
+  annotation "assessment/id",
+             description: "Identifier of the assessment in its register (risk id, CVE, finding number)",
+             title: "Assessment ID"
+
+  annotation "assessment/type",
+             description: "What kind of assessment this is (specialization of the assessment)",
+             enum: %w[risk vulnerability finding supplier protection-need],
+             filter: :word,
+             summary: true
+
+  annotation "assessment/status",
+             description: "Where the assessment is in its life cycle",
+             enum: %w[open treating accepted closed],
+             filter: :word,
+             summary: true
+
+  annotation "assessment/severity",
+             description: "Severity of a vulnerability or finding",
+             enum: %w[info low medium high critical],
+             filter: :word
+
+  annotation "assessment/assessed",
+             description: "When the assessment was made (ISO 8601 date or time)",
+             title: "Assessed",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  annotation "risk/initial-likelihood",
+             description: "Likelihood of the loss before mitigation",
+             enum: likelihood,
+             filter: :word
+
+  annotation "risk/initial-impact",
+             description: "Impact of the loss before mitigation",
+             enum: likelihood,
+             filter: :word
+
+  annotation "risk/residual-likelihood",
+             description: "Likelihood of the loss after mitigation",
+             enum: likelihood,
+             filter: :word
+
+  annotation "risk/residual-impact",
+             description: "Impact of the loss after mitigation",
+             enum: likelihood,
+             filter: :word
+
+  annotation "risk/treatment",
+             description: "How the risk is treated",
+             enum: %w[avoid transfer mitigate accept],
+             filter: :word,
+             summary: true
+
+  relation :ownedBy, :businessActors, :BusinessActor
+  relation :ownedBy, :businessRoles, :BusinessRole
+  relation :assesses, :businessProcesses, :BusinessProcess
+  relation :assesses, :businessActors, :BusinessActor
+  relation :assesses, :applicationComponents, :ApplicationComponent
+  relation :assesses, :applicationServices, :ApplicationService
+  relation :assesses, :technologyNodes, :TechnologyNode
+  relation :assesses, :dataObjects, :DataObject
+  relation :influences, :businessEvents, :BusinessEvent
+  relation :influences, :applicationEvents, :ApplicationEvent
+  relation :influences, :technologyEvents, :TechnologyEvent
+  relation :influences, :motivationAssessments, :MotivationAssessment
+  relation :mitigatedBy, :goals, :MotivationGoal
+  relation :mitigatedBy, :motivationRequirements, :MotivationRequirement
+  relation :mitigatedBy, :businessControls, :BusinessControl
+  relation :mitigatedBy, :implementationWorkPackages, :ImplementationWorkPackage
+end

data/lib/archsight/resources/{business_constraint.rb → motivation_constraint.rb}

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-# BusinessConstraint represents restrictions or limitations on architecture
-class Archsight::Resources::BusinessConstraint < Archsight::Resources::Base
-  include_annotations :git, :architecture
+# MotivationConstraint represents restrictions or limitations on architecture
+class Archsight::Resources::MotivationConstraint < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
 
   description <<~MD
     Represents a factor that limits the realization of goals or influences architecture decisions.
@@ -18,15 +18,21 @@ class Archsight::Resources::BusinessConstraint < Archsight::Resources::Base
 
     ## Usage
 
-    Use BusinessConstraint to represent:
+    Use MotivationConstraint to represent:
 
     - Regulatory requirements (GDPR, SOX, PCI-DSS)
     - Security policies
     - Organizational standards
     - Technical limitations
     - Budget or resource constraints
+
+    ## Security and risk modelling
+
+    Use a constraint for rules that only restrict and are not a design statement: regulation, contractual duties,
+    operational policy (the overlay paper has no element for operational policy). Policies stated as principles
+    belong in `MotivationPrinciple`.
   MD
 
   icon "prohibition"
-  layer "business"
+  layer "motivation"
 end

data/lib/archsight/resources/motivation_driver.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# MotivationDriver represents an external or internal condition that motivates the enterprise to act
+class Archsight::Resources::MotivationDriver < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
+
+  description <<~MD
+    Represents an external or internal condition that motivates the enterprise to define its goals and act.
+
+    ## ArchiMate Definition
+
+    **Layer:** Motivation
+    **Aspect:** Active Structure
+
+    A driver is something that creates, motivates and fuels the change of an organization. In the risk and
+    security overlay of the Open Group paper (*Modeling Enterprise Risk Management and Security with the ArchiMate
+    Language*) the general notion of a **threat** (a threatening circumstance) is a driver; opportunities,
+    regulations and market forces are drivers too. Set `driver/type` to say which.
+
+    ## Usage
+
+    Use MotivationDriver to represent:
+
+    - Threats ("machines may fail", "attackers target customer data")
+    - Opportunities
+    - Regulation and legal change
+    - Market and customer demand
+
+    ## How it connects
+
+    - A driver `influences` the assessments (risks) it leads to and other drivers
+    - A threat driver `triggers` threat or loss events
+    - A `MotivationStakeholder` `hasConcern` for it
+  MD
+
+  icon "fire-flame"
+  layer "motivation"
+
+  annotation "driver/type",
+             description: "What kind of driver this is (specialization of the driver)",
+             enum: %w[threat opportunity regulation market internal],
+             filter: :word,
+             summary: true
+
+  relation :influences, :motivationAssessments, :MotivationAssessment
+  relation :influences, :motivationDrivers, :MotivationDriver
+  relation :triggers, :businessEvents, :BusinessEvent
+  relation :triggers, :applicationEvents, :ApplicationEvent
+  relation :triggers, :technologyEvents, :TechnologyEvent
+end

data/lib/archsight/resources/motivation_goal.rb

@@ -3,7 +3,7 @@
 # MotivationGoal represents a high-level statement of intent, direction, or desired end state
 # for an organization and its stakeholders (ArchiMate Motivation Layer)
 class Archsight::Resources::MotivationGoal < Archsight::Resources::Base
-  include_annotations :git, :architecture
+  include_annotations :git, :architecture, :risk
 
   description <<~MD
     Represents a high-level statement of intent or desired end state for the organization.
@@ -26,12 +26,24 @@ class Archsight::Resources::MotivationGoal < Archsight::Resources::Base
     - Quality goals
     - Compliance objectives
     - Performance targets
+
+    ## Security and risk modelling
+
+    In the Open Group risk and security overlay a goal with `goal/type` `control-objective` states what a control
+    achieves against a risk. The risk (`MotivationAssessment`) is `mitigatedBy` the goal, and the goal `realizes` the
+    requirements that are the control measures: risk, then objective, then measure, read top-down.
   MD
 
   icon "archery"
   layer "motivation"
 
+  annotation "goal/type",
+             description: "What kind of goal this is (specialization of the goal)",
+             enum: %w[business control-objective],
+             filter: :word,
+             summary: true
+
   relation :realizes, :outcomes, :MotivationOutcome
   relation :refinedBy, :goals, :MotivationGoal
-  relation :realizes, :businessRequirements, :BusinessRequirement
+  relation :realizes, :motivationRequirements, :MotivationRequirement
 end

data/lib/archsight/resources/motivation_principle.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# MotivationPrinciple represents a normative property of all systems in a context, such as a policy
+class Archsight::Resources::MotivationPrinciple < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
+
+  description <<~MD
+    Represents a statement of intent that defines a general property that applies to any system in a context: a
+    principle, and at design level a policy.
+
+    ## ArchiMate Definition
+
+    **Layer:** Motivation
+    **Aspect:** Passive Structure
+
+    A principle is a qualitative statement of intent that should be met by the architecture. In the risk and
+    security overlay of the Open Group paper (*Modeling Enterprise Risk Management and Security with the ArchiMate
+    Language*) a policy maps to a principle; risk policy and security policy are specializations. Set
+    `principle/type` to say which.
+
+    ## Usage
+
+    Use MotivationPrinciple to represent:
+
+    - Security and risk policies (information security policy, access control policy)
+    - Guidelines and procedures that state how a rule is applied
+    - Architecture principles
+
+    Rules that only restrict (regulation, an operational policy that is not a design statement) stay
+    `MotivationConstraint`. The text of a policy belongs in a `Page`; link it with `[[Page]]` in the description.
+
+    ## How it connects
+
+    - A principle is `ownedBy` the actor or role that issued it
+    - A `MotivationRequirement` (control measure) `realizes` the principle
+  MD
+
+  icon "book"
+  layer "motivation"
+
+  annotation "principle/type",
+             description: "What kind of statement this is (specialization of the principle)",
+             enum: %w[principle policy security-policy risk-policy guideline procedure],
+             filter: :word,
+             summary: true
+
+  annotation "principle/status",
+             description: "Whether the statement is in force",
+             enum: %w[draft valid retired],
+             filter: :word,
+             summary: true
+
+  annotation "principle/classification",
+             description: "Confidentiality classification of the statement",
+             enum: %w[public internal confidential strictly-confidential],
+             filter: :word
+
+  annotation "principle/valid-from",
+             description: "When the statement comes into force (ISO 8601 date or time)",
+             title: "Valid from",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  annotation "principle/valid-until",
+             description: "When the statement has to be reviewed or ends (ISO 8601 date or time)",
+             title: "Valid until",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  annotation "principle/framework",
+             description: "Standards the statement maps to (comma-separated, e.g. c5-2020, iso27001-2022)",
+             title: "Framework mapping",
+             filter: :list
+
+  relation :ownedBy, :businessActors, :BusinessActor
+  relation :ownedBy, :businessRoles, :BusinessRole
+end