-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: adding ADR for selection of trivy for the keycloak pipeline (#15)
* docs: adding ADR for selection of trivy for the keycloak pipeline Signed-off-by: Ian Dunbar-Hall <[email protected]> * addessing @djmoch's feedback Signed-off-by: Ian Dunbar-Hall <[email protected]> --------- Signed-off-by: Ian Dunbar-Hall <[email protected]>
- Loading branch information
Showing
2 changed files
with
135 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| { | ||
| "Architecture Decision Record": { | ||
| "prefix": "adr", | ||
| "isFileTemplate": true, | ||
| "description": "Decision record template by Michael Nygard", | ||
| "scope": "markdown", | ||
| "body": [ | ||
| "<!--", | ||
| "This is a template for [Documenting Architecture Decisions - Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).", | ||
| "", | ||
| "You can use [adr-tools](https:/npryce/adr-tools) for managing the ADR files.", | ||
| "", | ||
| "In each ADR file, write the following sections.", | ||
| "-->", | ||
| "# ${TM_FILENAME_BASE/^\\d+?(\\d)-(\\w+).*$/$1. ${2:/capitalize}/}${TM_FILENAME_BASE/(?:^\\d+-\\w+-)|-([^-]+)/ $1/g}", | ||
| "", | ||
| "Date: $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE", | ||
| "", | ||
| "## Status", | ||
| "<!--", | ||
| "A decision may be \"proposed\" if the project stakeholders haven't agreed with it yet, or \"accepted\" once it is agreed.", | ||
| "If a later ADR changes or reverses a decision, it may be marked as \"deprecated\" or \"superseded\" with a reference to", | ||
| "its replacement.", | ||
| "-->", | ||
| "${1|Proposed,Accepted,Rejected,Deprecated,Superseded|}", | ||
| "", | ||
| "## Context", | ||
| "<!--", | ||
| "This section describes the forces at play, including technological, political, social, and project local. These forces", | ||
| "are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply", | ||
| "describing facts.", | ||
| "-->", | ||
| "${2:> What is the issue that we're seeing that is motivating this decision or change?}", | ||
| "", | ||
| "## Decision", | ||
| "<!--", | ||
| "This section describes our response to these forces. It is stated in full sentences, with active voice. \"We will …\"", | ||
| "-->", | ||
| "${3:> What is the change that we're proposing and/or doing?}", | ||
| "", | ||
| "## Consequences", | ||
| "<!--", | ||
| "This section describes the resulting context, after applying the decision. All consequences should be listed here, not", | ||
| "just the \"positive\" ones. A particular decision may have positive, negative, and neutral consequences, but all of them", | ||
| "affect the team and project in the future.", | ||
| "-->", | ||
| "${4:> What becomes easier or more difficult to do because of this change?}", | ||
| "" | ||
| ] | ||
| } | ||
| } |
84 changes: 84 additions & 0 deletions
84
phase-1-keycloak/architecture-decision-records/001-sbom-generation-tool.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,84 @@ | ||
| <!-- | ||
| This is a template for [Documenting Architecture Decisions - Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions). | ||
| You can use [adr-tools](https:/npryce/adr-tools) for managing the ADR files. | ||
| In each ADR file, write the following sections. | ||
| --> | ||
| # 1. Sbom Generation Tool Selection | ||
|
|
||
| Date: 2024-08-09 | ||
|
|
||
| ## Status | ||
| <!-- | ||
| A decision may be "proposed" if the project stakeholders haven't agreed with it yet, or "accepted" once it is agreed. | ||
| If a later ADR changes or reverses a decision, it may be marked as "deprecated" or "superseded" with a reference to | ||
| its replacement. | ||
| --> | ||
| Proposed | ||
|
|
||
| ## Context | ||
| <!-- | ||
| This section describes the forces at play, including technological, political, social, and project local. These forces | ||
| are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply | ||
| describing facts. | ||
| --> | ||
| > What is the issue that we're seeing that is motivating this decision or change? | ||
| For phase 1, the Tiger Team selected [keycloak](https:/keycloak/keycloak) as a java open source project to create a SBOM for. Since different ecosystems have different support by different tools, we did an un-official | ||
| trade study of different SBOM generation tools to decide what was best to use for this first project. | ||
|
|
||
| ## Decision | ||
| <!-- | ||
| This section describes our response to these forces. It is stated in full sentences, with active voice. "We will …" | ||
| --> | ||
| > What is the change that we're proposing and/or doing? | ||
| The tiger team is proposing we use [trivy](https:/aquasecurity/trivy) and analyze source of the keycloak project. | ||
|
|
||
| - [Un-official Trade Study](https:/CISA-SBOM-Community/SBOM-Generation/issues/7) | ||
|
|
||
| This decision is based on the following factors: | ||
|
|
||
| - Analysis of the components discovered in comparison of other tools | ||
| - Ability to generate both CycloneDX and SPDX SBOMs | ||
| - Completness of the depenency graph | ||
| - Compliance with the NTIA Minimum Elements | ||
|
|
||
| ### Honorable Mentions | ||
|
|
||
| #### Syft | ||
|
|
||
| [Syft](https:/anchore/syft) met most of the requirements but ultimated decided against for three reasons. | ||
|
|
||
| - Number of duplicate components | ||
| - We found Syft generated a lot of duplicate componets in the sbom which increases it size and complexity without adding value | ||
| - Source code scanning maven build variables | ||
| - Some build variables for component names were not expanded resulting in variable names being used for component identification | ||
| - Jar scanning dependency graph incomplete | ||
| - Syft Jar scanning added hashes to the sboms, but lacked the dependency graph information | ||
|
|
||
| #### cyclonedx-maven-plugin | ||
|
|
||
| [cyclonedx-maven-plugin](https:/CycloneDX/cyclonedx-maven-plugin) definitely produced the best "per component" completeness of the NTIA Minimum Elements, but was decided against for two reasons. | ||
|
|
||
| - No SPDX Support | ||
| - A requirement for this tiger team is to support both major SBOM formats. [cyclonedx-maven-plugin](https:/CycloneDX/cyclonedx-maven-plugin) only supports CycloneDX | ||
| - Needs to be added to all project `pom.xml` files | ||
| - We want to avoid directly modifying the configuration files of Keycloak for the purpose of this example workflow. If this were to be incorporated directly into the project this would not be an issue. | ||
|
|
||
| :note: If you only need CycloneDX sboms for a java project, we'd recommend teams investigate this tool. | ||
|
|
||
| ## Consequences | ||
| <!-- | ||
| This section describes the resulting context, after applying the decision. All consequences should be listed here, not | ||
| just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them | ||
| affect the team and project in the future. | ||
| --> | ||
| > What becomes easier or more difficult to do because of this change? | ||
| Some information will be harder to enrich later in the SBOM Generation Pipeline. | ||
|
|
||
| Specifically: | ||
|
|
||
| - hashes |