|
| 1 | += Conforma Workflow Diagram |
| 2 | + |
| 3 | +The Conforma workflow operates within the Konflux supply chain security ecosystem, where it validates build artifacts and enforces security policies at critical checkpoints throughout the CI/CD process. Each numbered step in the diagram represents a key phase in this validation workflow. |
| 4 | + |
| 5 | +[mermaid] |
| 6 | +.... |
| 7 | +flowchart TD |
| 8 | + |
| 9 | + subgraph s6["IT PipelineRun"] |
| 10 | + n7["Conforma task"]:::conforma |
| 11 | + end |
| 12 | +
|
| 13 | + subgraph s7["Release PipelineRun"] |
| 14 | + n10["Conforma task"]:::conforma |
| 15 | + end |
| 16 | +
|
| 17 | + subgraph s2["Openshift build cluster"] |
| 18 | + n1["Build PipelineRun"]:::pipeline |
| 19 | + n6["Snapshot"]:::cluster_res |
| 20 | + n9["KNative Conforma Controller"]:::cluster_res |
| 21 | + decisionId{"VSA present?"}:::white |
| 22 | + s6:::pipeline |
| 23 | + s7:::pipeline |
| 24 | + end |
| 25 | + s2:::openshift |
| 26 | +
|
| 27 | + subgraph s5["Build artifacts"] |
| 28 | + n3["SBOM"]:::artifact |
| 29 | + n4["Provenance Attestation"]:::artifact |
| 30 | + n5["Component manifest"]:::artifact |
| 31 | + end |
| 32 | + s5:::artifacts_group |
| 33 | +
|
| 34 | + subgraph s3["Quay.io"] |
| 35 | + s5 |
| 36 | + end |
| 37 | + s3:::instance |
| 38 | +
|
| 39 | + subgraph s4["Rekor"] |
| 40 | + n8["VSA Attestation"]:::artifact |
| 41 | + end |
| 42 | + s4:::instance |
| 43 | +
|
| 44 | + subgraph s1["Konflux"] |
| 45 | + n2["Component"]:::component |
| 46 | + s2 |
| 47 | + s3 |
| 48 | + s4 |
| 49 | + end |
| 50 | + s1:::konflux |
| 51 | +
|
| 52 | + n2 -- "1 - CI events trigger build" --> n1 |
| 53 | + n1 -- "2 - Pipeline produces artifacts" --> s5 |
| 54 | + n1 -- "3 - Pipeline completion triggers Snapshot creation" --> n6 |
| 55 | + n6 -- "4 - Snapshot creation triggers Conforma Controller" --> n9 |
| 56 | + n9 -. "5 - Controller validates Snapshot and build artifacts" .-> s5 |
| 57 | + n9 -- "6 - Controller produces VSA" --> n8 |
| 58 | + n6 -- "7 - Snapshot creation triggers Integration Tests" --> s6 |
| 59 | + decisionId -. NO: validate Snapshot and build artifacts .-> s5 |
| 60 | + decisionId -. YES: return output from VSA .-> n8 |
| 61 | + n7 -- "8 - Conforma validates the Build artifacts" --> decisionId |
| 62 | + n2 -- "9 - Trigger release" --> s7 |
| 63 | + n10 -- "10 - Conforma gates the Release" --> decisionId |
| 64 | +
|
| 65 | + subgraph s8["Legend"] |
| 66 | + n11["Pipeline"]:::pipeline |
| 67 | + n12["Openshift resource / Manifest / Artifact"]:::artifact |
| 68 | + n13["Instance"]:::instance |
| 69 | + n14["Conforma"]:::conforma |
| 70 | + n15[" "] |
| 71 | + n16[" "] |
| 72 | + n17[" "] |
| 73 | + n18[" "] |
| 74 | + end |
| 75 | + s8:::white |
| 76 | +
|
| 77 | + n15 -- "Next step" --> n16 |
| 78 | + n17 -. "Step run against artifact" .-> n18 |
| 79 | +
|
| 80 | + classDef konflux stroke:#000000,fill:#b0a3c4 |
| 81 | + classDef openshift stroke:#000000,fill:#ffffff |
| 82 | + classDef pipeline stroke:#000000,fill:#dbd0ea |
| 83 | + classDef instance stroke:#000000,fill:#ffffff |
| 84 | + classDef cluster_res stroke:#000000,fill:#ab1e35,color:white |
| 85 | + classDef artifact stroke:#000000,fill:#ab1e35,color:white |
| 86 | + classDef conforma stroke:#000000,fill:#614d89,color:white |
| 87 | + classDef white stroke:#000000,fill:#ffffff |
| 88 | + classDef artifacts_group stroke:#000000,fill:#f8c6c9 |
| 89 | + classDef component stroke:#000000,fill:#ffffff |
| 90 | +.... |
| 91 | + |
| 92 | +== 1 - CI events trigger build |
| 93 | + |
| 94 | +The workflow begins when continuous integration events occur within a Konflux Component. These events include code commits, pull requests, or manual triggers that initiate the build process. When a developer pushes code changes to a repository that is configured as a Konflux Component, the system automatically detects these changes and triggers a Build PipelineRun. This pipeline is responsible for compiling the source code into container images and other distributable artifacts. The Component represents the logical unit of software being built, while the Build PipelineRun is the actual execution context that will orchestrate all the build tasks, including compilation, testing, and artifact generation. |
| 95 | + |
| 96 | +== 2 - Pipeline produces artifacts |
| 97 | + |
| 98 | +During the Build PipelineRun execution, the pipeline generates several critical build artifacts that will later be used for security validation. The primary artifacts include the Software Bill of Materials (SBOM), which is a comprehensive inventory of all software components and dependencies used in the build; the Provenance Attestation, which provides cryptographic proof of how the software was built, including build environment details, source code references, and build parameters; and the Component manifest, which describes the metadata and configuration of the built component. These artifacts are automatically generated by approved Konflux build tasks and are stored in Quay.io, Red Hat's container registry. The SBOM uses the CycloneDX format and contains detailed information about all packages, libraries, and dependencies, while the provenance attestation follows the SLSA (Supply-chain Levels for Software Artifacts) specification to ensure build integrity and traceability. |
| 99 | + |
| 100 | +== 3 - Pipeline completion triggers Snapshot creation |
| 101 | + |
| 102 | +Once the Build PipelineRun completes successfully, the system automatically creates a Snapshot resource. The Snapshot represents a point-in-time capture of all components within an Application, including the newly built component and its associated artifacts. This Snapshot serves as an immutable reference to the specific versions of all components that will undergo testing and potentially be released together. The Snapshot creation is a crucial step because it establishes the exact artifact versions that will be validated by Conforma and other security tools. It includes references to the container images stored in Quay.io, along with their cryptographic digests, ensuring that the artifacts cannot be tampered with after this point. |
| 103 | + |
| 104 | +== 4 - Snapshot creation triggers Conforma Controller |
| 105 | + |
| 106 | +The creation of a new Snapshot automatically triggers the KNative Conforma Controller, which is a Kubernetes controller running within the OpenShift build cluster. This controller is responsible for orchestrating the security validation process for all artifacts referenced in the Snapshot. The controller monitors Snapshot creation events and initiates the Conforma validation workflow whenever new artifacts need to be evaluated. |
| 107 | + |
| 108 | +== 5 - Controller validates Snapshot and build artifacts |
| 109 | + |
| 110 | +The Conforma Controller performs a comprehensive validation of the Snapshot and its associated build artifacts by executing the 'ec validate image' command from the Conforma CLI tool. This validation process involves downloading and inspecting the SBOM, provenance attestations, and container images from Quay.io. The controller verifies the cryptographic signatures on these artifacts using Cosign and validates that they were produced by trusted build processes. It checks the SBOM for known vulnerabilities, validates that all dependencies come from approved sources, and ensures that the provenance attestation correctly describes the build process. The controller also verifies that all required build tasks were executed and that the build environment met the necessary security requirements, such as running in a hermetic (network-isolated) environment when required for release builds. |
| 111 | + |
| 112 | +== 6 - Controller produces VSA |
| 113 | + |
| 114 | +Upon validation of the build artifacts, the Conforma Controller generates a Verification Summary Attestation (VSA). The VSA is a cryptographically signed document that contains the complete output of the policy bundle evaluation, including all successes, warnings, and violations found during the validation process. It includes comprehensive information about which policies were evaluated, all validation results regardless of their severity, and references to the specific artifacts that were validated. This attestation is stored in Rekor, the transparency log component of Sigstore, ensuring that the validation results are tamper-evident and publicly verifiable. The VSA serves as a complete record of the security evaluation that can be processed by downstream validation tasks. |
| 115 | + |
| 116 | +== 7 - Snapshot creation triggers Integration Tests |
| 117 | + |
| 118 | +In parallel with the Conforma validation process, the creation of the Snapshot also triggers Integration Test PipelineRuns. These integration tests are designed to validate the functional correctness and compatibility of the components in the Snapshot. Integration Test Scenarios are automatically created for every Application and include both functional tests and policy validation tests. The integration test pipeline executes various test suites to ensure that the software works correctly in realistic deployment scenarios and that it integrates properly with other system components. |
| 119 | + |
| 120 | +== 8 - Conforma validates the Build artifacts |
| 121 | + |
| 122 | +During the Integration Test PipelineRun, a dedicated Conforma task is executed that includes a decision point to check whether a VSA attestation already exists for the current Snapshot. If a VSA is present from the earlier controller validation (step 6), the task processes the VSA content and applies the current policy configuration to determine which results (successes, warnings, violations) are relevant for this specific validation context. If the VSA contains relevant violations based on the applied policy configuration, the Conforma task fails. If no VSA is present, the task executes the same 'ec validate image' command that the controller uses, but applies the policy configuration to consider only the relevant subset of results for the final pass/fail determination. This approach ensures consistent validation while allowing different policy configurations to focus on different aspects of the security evaluation. |
| 123 | + |
| 124 | +== 9 - Trigger release |
| 125 | + |
| 126 | +When a development team is ready to release their software, they initiate a release process by creating a Release resource that references the validated Snapshot. This action triggers a Release PipelineRun, which is responsible for promoting the validated artifacts from the development environment to production or customer-facing registries. The release process is only initiated for Snapshots that have successfully passed all integration tests and security validations, ensuring that only high-quality, secure software is released. |
| 127 | + |
| 128 | +== 10 - Conforma gates the Release |
| 129 | + |
| 130 | +The final step in the workflow occurs during the Release PipelineRun, where Conforma acts as a security gate that must be passed before the release can proceed. Similar to step 8, this involves a Conforma task that checks for the presence of a VSA attestation. If a VSA exists, the task processes the VSA content and applies the release policy configuration to determine if there are any relevant violations that would block the release. If the VSA contains violations that are relevant to the release policy configuration, the release process is blocked. If no VSA is present, the task performs the same validation as the controller by executing 'ec validate image', but only considers the subset of results that are relevant according to the release policy configuration. If this validation reveals relevant violations, the release process is blocked, preventing potentially insecure or non-compliant software from being released to customers. This final validation step ensures that all released software meets the specific security and compliance requirements defined for the release process. |
0 commit comments