Layout
caution
This is page is work in progress
Introduction
A Layout in Argos Notary dictates the series of steps that need to be carried out in the Software Supply Chain to create the final end product. The layout includes ordered segments and steps, requirements for the steps, and the list of actors (or functionaries) in charge of carrying out every step. The steps within the supply chain are laid out by a project owner.
The Layout is stored in Argos Notary together with its signature(s) in a Metadata object. A Layout is only valid with the required number of authorized signatures.
Layout
A Layout should be signed by one ore more of the authorized persons. A person is authorized if the keyId of the Key of the person is one of the key identifiers in the authorizedKeyIds list.
The Expected End Products is a list of Match Rules which should match all software products delivered by the Software Supply Chain
A Layout Segment is a container of Steps which belong together. e.g all steps in a Jenkins pipeline.
The public keys of all digital signkeys used in the Layout should be in keys list.
Class diagram
LayoutSegment
A Layout has one or more LayoutSegments. A LayoutSegment is a cluster of Steps of wich the Links will get the same runId. As an example all steps in a Jenkins pipeline can belong to the same LayoutSegment and in the pipeline all Link objects will get the same runId.
All segments in the layout together should form a acyclic directed graph with the segments and the expected end products as nodes and the matchrules as edges. The match rules in the expected end products should point to 1 segment which should also be the starting point of the graph.
This constraints are necessary to create contexts used during the verification of end products.
Step
Every Link object created in the Supply Chain will be associated with a Step in the Layout. A Step describes the rules
the materials, files before the execution, and products, files after execution, should follow.
authorizedKeyIds are the keyIds of the Accounts which should be used to create valid Link objects.
requiredNumberOfLinks defines how many Link objects should at least be made by different accounts.
Expected End Products
The expected end products is a list of matchrules pointing to a segment with all the products delivered by this Supply Chain as they are deployed or installed. This can be more than 1 file or type of file. e.g. service jars, client jars or installation packages.
A client can do a request with a list of artifacts matching the expected end products to verify these artifacts.
Artifact Rules
Rules in Argos Notary can be compared with firewall rules. The rules enforce the existence of artifacts before running of a step(expected materials) or after running of the step(expected products). As an example, the "build" step can use the materials from the "checkout-git" step and has a jar artifact in the products.
All rules have a glob pattern equivalent with gitignore pattern
matching. The pattern will be matched against uris reported for materials or products in the link data.
The following rules can be specified:
- MATCH: The MatchRule will be explained in MatchRule.
- ALLOW: indicates that artifacts matched by the pattern are allowed and consumed by this rule.
- DISALLOW: indicates that artifacts matched by the pattern are not allowed.
- REQUIRE: indicates that a pattern must appear and are consumed by this rule.
- CREATE: indicates that products matched by the pattern must not appear as materials of the step.
- CREATE_OR_MODIFY: indicates that products matched are
MODIFIEDorCREATEDcompared to the materials of the step. - DELETE: indicates that materials matched by the pattern must not appear as products of the step.
- MODIFY: indicates that products matched by this pattern must appear as materials of the step, and their hashes must not by the same.
MatchRule
A MatchRule indicates that the artifacts filtered using sourcePathPrefix/pattern must be matched to a destinationType(MATERIALS or PRODUCTS)
from a destinationStep and destinationSegment with the destinationPathPrefix/pattern filter.
For example, match foo with PRODUCTS from the step compilation in the segment jenkins indicates
that the file foo, a product of the step compilation in the segment jenkins,
must correspond to either a material or a product in this step (depending on where
this artifact rule was listed).
The sourcePathPrefix, destinationPathPrefix and destinationSegmentName properties are optional,
The pathPrefixes are used to match products and materials whose path differs from the one presented
in the destination step. This is the case for steps that relocate files as part of their tasks.
For example match foo with sourcePathPrefix lib and destinationPathPrefix build/lib will
ensure that the file lib/foo matches build/lib/foo in the destination step.
If destinationSegmentName isn't defined the destination step should be in the same Layout Segment
as the current step
The MatchRules in the expected end products combined with the MatchRules in the steps refering to other segments should create a directed graph of the Layout Segments.
Rule processing
Artifact rules reside in the expectedProducts and expectedMaterials fields of a step and are applied sequentially on a queue of Artifacts or from the step's corresponding link metadata. They operate in a similar fashion as firewall rules do. This means if an artifact is successfully consumed by a rule, it is removed from the queue and cannot be consumed by subsequent rules. There is an implicit DISALLOW with the pattern ** at the end of each rule list. Argos Notary verification fails if an artifact was not consumed by an earlier rule. Here, we describe an algorithm to illustrate the behavior of the rules being applied:
Match Rule processing
The match rule is used to tie different steps together, by means of their materials and products. The main rationale behind the match rule is to identify the origins of artifacts as they are passed around in the supply chain. In this sense, the match rule will be used to identify which step should be providing a material used in a step, as well as force products to match with products of previous steps.
In order to ensure the correctness of the match rule, it is important to describe the way it operates. To avoid any ambiguities, this will be done with the following pseudocode: