Minimal (MVP) Controls Domain

[jpgough-ms]

Feature Request

Description of Problem:

@yt-ms and I have had a discussion about creating a minimal domain for capturing controls for nodes (as a starting point). At this stage we are looking to introduce domains discussed in #310. A controls.json to model the domain and an August schema version (to not impact existing uses of CALM).

We are going to follow the approach we used for interfaces: https://github.com/finos/architecture-as-code/blob/main/calm/draft/2024-04/meta/interface.json#L6 and create a control-type.

With this in place we can continue our discussions on what we might centralize into this domain in the future for common control types. This can be the subject of discussion at our regular working group.

Potential Solutions:

• Create an August version of CALM
• Add the general concept of domain (outlined in Generic CALM domain definitions via external schemas #310)
• Create a control-type
• Create a control-type domain (i.e. a list of control-type)

[yt-ms]

I see this in two parts - the controls defined in one file, which set out what data is needed within the system (or other) node, then the data on the nodes themselves.

Example of what the controls file might look like:

{
  "nodes": [
    {
      "uniqueid": "cr-arch-001",
      "type": "Control Requirement",
      "name": "Architectures must be approved to ensure they are fit for purpose",
      "control-registry-id": "ABCDE",    # local ID from the company's control register
    },
    {
      "uniqueId": “ci-arch-001”,
      "type": “Control Instance”,
      "name": “Architecture review pre-production”,
      "control-requirement": "cr-arch-001",    # Reference to the Control Requirement that this is an instance of
      "scope-text": "All workloads going to production",
      "scope-rego": "input.metadata.target-deployment.environment == \"production\"",    # Use rego to support complex rules
      "data-fields": {
        # ... something that works like interfaces to define which fields are needed
        # to be captured in the system as evidence of meeting the control instance
        "review-date": {},
        "reviewed-by": {},
        "docs-link": {}
      }
    }
  ]
}

This defines a single control requirement and the corresponding control instance which describes how the requirement should be met (I'm not an expert, but apparently this is a favoured structure in the industry).

The corresponding CALM architecture model might be:

{
  "nodes": [
    {
      "unique-id": "some-system",
      "node-type": "system",
      "name": "My awesome system",
      "description": "System with fantastic architecture",
      "interfaces": [],
      "domains": {
          "cbom": [    # Control Bill of Materials
              {
                  "control-instance": "ci-arch-001",
                  "review-date": "2024-07-31",
                  "reviewed-by: "yt-ms",
                  "docs-link": "http://jira.example.com/BLAH-1224"
              }
          ]
      }
    }
  ],
  "relationships": [],
  "metadata": [
      {
          "target-deployment": {"environment": "production"}
      }
  ]
}

One thing to look at here is that the Control Instance carries its own data but also acts as a type definition like interfaces do. This probably requires a bit cleaner structure to support properly. Also we'd need to somehow say that control instances are for the "cbom" domain.