archsight 0.3.2 → 0.4.0

data/lib/archsight/resources/import.rb

@@ -35,26 +35,52 @@ class Archsight::Resources::Import < Archsight::Resources::Base
   icon "download"
   layer "other"
 
-  # Handler selection
+  # Handler selection: a built-in handler or one the resources repository registers (import/handlerPath)
   annotation "import/handler",
-             description: "Handler class name to execute this import",
+             description: "Name of the handler that executes this import: a built-in one or one registered by the file " \
+                          "in import/handlerPath",
              title: "Handler",
              summary: true,
-             enum: %w[
-               gitlab github repository
-               rest-api rest-api-index
-               jira-discover jira-metrics
-               go-grapher go-dep-resolver
-               cpp-grapher ruby-grapher python-grapher
-               java-grapher javascript-grapher
-               rust-grapher crystal-grapher elixir-grapher
-             ]
+             filter: :word,
+             validator: lambda { |value|
+               require "archsight/import/handler_loader"
+               Archsight::Import::HandlerLoader.load_builtin!
+               next if Archsight::Import::Registry[value]
+
+               "unknown import handler '#{value}'. Registered: #{Archsight::Import::Registry.handlers.sort.join(", ")}; " \
+                 "a handler of the resources repository needs import/handlerPath"
+             }
+
+  annotation "import/handlerPath",
+             description: "Ruby file of a handler that lives in the resources repository, relative to the resources " \
+                          "root (e.g., 'importers/deployments.rb'). It registers the name used in import/handler.",
+             title: "Handler Path"
+
+  annotation "import/dependsOn",
+             description: "Imports that must run first, by name or glob pattern (e.g., 'Import:Repo:*'), comma " \
+                          "separated. Adds to the dependency on the import that generated this one.",
+             title: "Depends On",
+             filter: :list,
+             sidebar: false
 
   # Output configuration
   annotation "import/outputPath",
              description: "Output file path relative to resources root (e.g., 'imports/generated/gitlab.yaml')",
              title: "Output Path"
 
+  annotation "generated/inputsHash",
+             description: "Hash of the files matched by import/config/inputs at the last run (for change detection)",
+             title: "Inputs Hash",
+             sidebar: false,
+             editor: false
+
+  annotation "generated/outputs",
+             description: "Files the last run wrote, relative to the resources root",
+             title: "Outputs",
+             filter: :list,
+             sidebar: false,
+             editor: false
+
   # Control flags
   annotation "import/enabled",
              description: "Whether this import is enabled",

data/lib/archsight/resources/location.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Location represents a geographic or conceptual place
+class Archsight::Resources::Location < Archsight::Resources::Base
+  include_annotations :git, :architecture
+
+  description <<~MD
+    Represents a place: a country, a metro area, a region or any other geographic or conceptual position.
+
+    ## ArchiMate Definition
+
+    **Layer:** Other (ArchiMate: composite element)
+    **Aspect:** Composite
+
+    A location is a conceptual or physical place or position where concepts are located (structure elements)
+    or performed (behavior elements). In archsight it is the coarse place that facilities sit in.
+
+    ## Usage
+
+    Use Location to represent:
+
+    - Countries and regions (Germany, EU)
+    - Metro areas and cities (Frankfurt)
+    - Conceptual places (a cloud region, a jurisdiction)
+
+    ## Not this kind
+
+    - A building, campus or hall is a `TechnologyFacility` that is `locatedAt` the location
+    - A cloud region that is really a set of data centers: a location, with the data centers as facilities in it
+
+    Which kind to pick: "Choosing the Kind: Infrastructure" in the modeling guide.
+
+    ## How it connects
+
+    - A `TechnologyFacility` is `locatedAt` a location (many facilities, one location)
+    - Everything located at a facility of the location is found through the facility; the location page lists the
+      facilities that are located there, grouped by kind
+
+    Model the sites themselves as `TechnologyFacility`, not as locations: a data center is a physical structure.
+  MD
+
+  icon "map-pin"
+  layer "other"
+
+  annotation "location/country",
+             description: "Country of the location (name or ISO 3166 code)",
+             title: "Country",
+             filter: :word,
+             summary: true
+
+  annotation "location/city",
+             description: "City or metro area of the location",
+             title: "City",
+             filter: :word,
+             summary: true
+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/motivation_constraint.rb

@@ -2,7 +2,7 @@
 
 # MotivationConstraint represents restrictions or limitations on architecture
 class Archsight::Resources::MotivationConstraint < Archsight::Resources::Base
-  include_annotations :git, :architecture
+  include_annotations :git, :architecture, :risk
 
   description <<~MD
     Represents a factor that limits the realization of goals or influences architecture decisions.
@@ -25,6 +25,12 @@ class Archsight::Resources::MotivationConstraint < Archsight::Resources::Base
     - 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"

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,11 +26,23 @@ 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, :motivationRequirements, :MotivationRequirement

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

data/lib/archsight/resources/motivation_requirement.rb

@@ -2,7 +2,7 @@
 
 # MotivationRequirement represents functional or non-functional requirements
 class Archsight::Resources::MotivationRequirement < Archsight::Resources::Base
-  include_annotations :git, :architecture
+  include_annotations :git, :architecture, :risk
 
   description <<~MD
     Represents a statement of need that must be realized by the architecture.
@@ -35,6 +35,21 @@ class Archsight::Resources::MotivationRequirement < Archsight::Resources::Base
       which `satisfies` it
 
     Both show as incoming relations on the requirement's page.
+
+    ## Where it comes from
+
+    The source of a requirement is the `MotivationStakeholder` that `hasConcern` for it, directly or through the goal
+    the requirement answers. The stakeholder is `representedBy` the actor or role behind it, so the chain reaches the
+    actual organisation that asked for the requirement.
+
+    ## Security and risk modelling
+
+    - **Control measure:** `requirement/type` `control-measure` is a measure that a control objective
+      (`MotivationGoal`) `realizes`; the risk is `mitigatedBy` the objective or directly by the measure, and the
+      asset or control that implements the measure `realizes` or `satisfies` it.
+    - **Control requirement / catalogue control:** a control of a standard (C5, ISO 27001) is a requirement of type
+      `compliance`, listed in `requirement/reference`.
+    - **Policy:** a requirement can `realize` a `MotivationPrinciple` (the policy it implements).
   MD
 
   icon "task-list"
@@ -42,7 +57,7 @@ class Archsight::Resources::MotivationRequirement < Archsight::Resources::Base
 
   annotation "requirement/type",
              description: "Type of requirement (business or legal)",
-             enum: %w[business legal compliance functional non-functional],
+             enum: %w[business legal compliance functional non-functional control-measure],
              summary: true
 
   annotation "requirement/reference",
@@ -64,4 +79,5 @@ class Archsight::Resources::MotivationRequirement < Archsight::Resources::Base
              format: :markdown
 
   relation :realizes, :outcomes, :MotivationOutcome
+  relation :realizes, :motivationPrinciples, :MotivationPrinciple
 end

data/lib/archsight/resources/motivation_stakeholder.rb

@@ -26,6 +26,23 @@ class Archsight::Resources::MotivationStakeholder < Archsight::Resources::Base
     - Customer representatives
     - Regulatory bodies
     - Technical leadership
+
+    ## How it connects
+
+    - It `hasConcern` for the capabilities, goals, drivers, assessments, constraints and requirements it cares about.
+      That makes it the **source** of those requirements: the requirement's page shows the stakeholder as incoming.
+    - It is `representedBy` the `BusinessActor` (the actual organisation or person, e.g. the customer organisation,
+      not "customer") or `BusinessRole` that holds this interest. A stakeholder is a role; the actor is the party
+      behind it.
+
+    In ArchiMate a stakeholder is associated with the business actor or role that plays it; in TOGAF the stakeholder
+    map of Phase A links stakeholders and their concerns to organisation units and actors, and the requirements
+    repository records each requirement's source.
+
+    ## Security and risk modelling
+
+    A stakeholder (CISO, risk committee, data protection officer) can `hasConcern` for threats
+    (`MotivationDriver`) and risks (`MotivationAssessment`) in addition to goals and requirements.
   MD
 
   icon "user-crown"
@@ -35,4 +52,8 @@ class Archsight::Resources::MotivationStakeholder < Archsight::Resources::Base
   relation :hasConcern, :motivationRequirements, :MotivationRequirement
   relation :hasConcern, :motivationConstraints, :MotivationConstraint
   relation :hasConcern, :goals, :MotivationGoal
+  relation :hasConcern, :motivationDrivers, :MotivationDriver
+  relation :hasConcern, :motivationAssessments, :MotivationAssessment
+  relation :representedBy, :businessActors, :BusinessActor
+  relation :representedBy, :businessRoles, :BusinessRole
 end

data/lib/archsight/resources/page.rb

@@ -6,6 +6,8 @@ require "time"
 # Page is a wiki page authored as a markdown file with YAML frontmatter.
 # It is sourced by Archsight::PageLoader and arranged in a tree by PageMenu.
 class Archsight::Resources::Page < Archsight::Resources::Base
+  include_annotations :links
+
   description <<~MD
     Represents a wiki page authored as a markdown file with YAML frontmatter.
 
@@ -18,8 +20,13 @@ class Archsight::Resources::Page < Archsight::Resources::Base
 
     ## Frontmatter
 
-    `title`, `author`, `owner`, `status`, `tags` (comma-separated), `toc` (yes/no), `confluence`
-    (URL of the linked Confluence page) and an optional `name` (defaults to the file path).
+    `title`, `author`, `owner`, `status`, `tags` (comma-separated), `toc` (yes/no), `links` (a mapping of
+    names to URLs, e.g. `confluence`, `jira`) and an optional `name` (defaults to the file path).
+
+    ## Security and risk modelling
+
+    The text of a policy, a risk register narrative or an incident report is a `Page`. Link the structured
+    resources (`MotivationPrinciple`, `MotivationAssessment`, events) to it with `[[Page]]`.
   MD
 
   icon "page"
@@ -54,11 +61,6 @@ class Archsight::Resources::Page < Archsight::Resources::Base
              title: "Table of Contents",
              enum: %w[yes no],
              sidebar: false
-  annotation "page/confluence",
-             description: "URL of the corresponding Confluence page (used for a later export)",
-             title: "Confluence",
-             type: URI,
-             sidebar: false
   annotation "page/created",
              description: "When the page was created (ISO 8601 date or time)",
              title: "Created",

data/lib/archsight/resources/strategy_capability.rb

@@ -25,6 +25,15 @@ class Archsight::Resources::StrategyCapability < Archsight::Resources::Base
     - Organizational abilities
     - Core competencies
     - Value-generating functions
+
+    ## Choosing this kind
+
+    **Question:** What must the organization be *able* to do?
+    **Test:** It survives swapping product, team and technology. It is not a certificate or a quality.
+    **Name:** An ability noun phrase ("Payment Processing"), never a product, team or technology.
+
+    A product `realizes` the capability. Only internal capabilities that no product carries are `servedBy` a service.
+    See the modeling guide, "Choosing the Kind".
   MD
 
   icon "strategy"

data/lib/archsight/resources/technology_artifact.rb

@@ -27,6 +27,15 @@ class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
     - Container images
     - Build artifacts
     - Configuration packages
+    - Images (OS, VM template, disk or boot image, `artifact/type: image`)
+
+    ## Contents and deployment
+
+    An artifact that contains other artifacts `aggregates` them (ArchiMate aggregation): an image contains packages,
+    a chart references container images. A node or system software that runs an artifact `assignedTo` it (ArchiMate
+    assignment, written on the node). The artifact's page shows both as incoming relations ("contained in" and
+    "deployed on"). `ApplicationComponent realizedThrough TechnologyArtifact` says what a component is built from,
+    not where the artifact runs.
   MD
 
   icon "puzzle"
@@ -36,12 +45,9 @@ class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
   annotation "artifact/type",
              description: "Type of technology artifact",
              title: "Artifact Type",
-             enum: %w[repo container chart deb rpm]
+             enum: %w[repo container chart deb rpm image binary archive]
 
   # Dynamic annotations (patterns with *)
-  annotation "link/*",
-             description: "Documentation and resource links",
-             sidebar: false
   annotation "scc/language/*/loc",
              description: "Lines of code per programming language",
              sidebar: false
@@ -240,6 +246,7 @@ class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
   end
 
   relation :servedBy, :technologyComponents, :TechnologyArtifact
+  relation :aggregates, :technologyArtifacts, :TechnologyArtifact
   relation :suppliedBy, :technologyComponents, :TechnologyService
   relation :maintainedBy, :businessActors, :BusinessActor
   relation :contributedBy, :businessActors, :BusinessActor