From 2b167c7ea707667ca32957333999e6fcc1f7cbe2 Mon Sep 17 00:00:00 2001 From: Chris Butler Date: Wed, 2 Apr 2025 08:20:09 +0900 Subject: [PATCH 1/3] feat: oscal compass project supported demos Signed-off-by: Chris Butler --- proposals/demonstration-organisation.md | 157 ++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 proposals/demonstration-organisation.md diff --git a/proposals/demonstration-organisation.md b/proposals/demonstration-organisation.md new file mode 100644 index 0000000..db977bb --- /dev/null +++ b/proposals/demonstration-organisation.md @@ -0,0 +1,157 @@ +--- +title: Management of reference demonstration repositories +x-trestle-template-version: 0.0.1 +description: "This proposal proposes " +authors: + - butler54 +begin-design-discussions: 2024-07-31 #Insert +status: accepted #deferred, rejected, withdrawn or replaced - PR's are not accepted. Status is based on main. Rejected is unlikely to exist except where a clear record is required +--- + +**Checklist** + + + Add extra fields for management here + +- [x] Template passes validation with `trestle` +- [x] Proposal cuts across multiple `oscal-compass` projects + + + +## Summary/Abstract + +OSCAL compass is built on the premise of compliance as code and gitops. +This means that Github repositories, and organisations, are used for demonstrations including integration with CICD platforms such as github actions. +The result is that curating this content is key. +This proposal outlines guidelines and processes for managing demonstration content in a consistent and coherent way. + +## Background + +Over time there have been a number of demonstrations built for OSCAL compass. +Many of these demonstrations contain overlapping functionality, however, clear ownership has not been maintained. +Most of these demonstrations have not been reviewed at the community level, whether due to historical creation or lack of process. +The result is we do not have a consistent set of project demonstration content. + +### Motivation and problem space + +- To improve the demonstration content itself. +- To ensure that the primary github organization (e.g. https://github.com/oscal-compass) is a focused and clean as possible. + - This will enable the 'core' to meet standards such as OpenSSF more easily +- To ensure a minimum viable set of processes in place to manage the demo content. + + +### Impact and desired outcome + +- Avoiding creating a dumping zone: Organizations which have 100's or 1000's of garbage projects which have been thrown into the wild. +- W + +### Prior discussion and links + +- Mostly via slack / f2f conversations. + + +## User/User Story (Optional) + +- As an Oscal compass contributor I have a clear process for obtaining and creating 'official' demo repositories +- As an Oscal compass user I have a single place for clear and consistent demonstration content +- As a potential user of Oscal compass the core organization clearly shows the projects + +## Goals + +- Use this *inception* proposal to define a simple template +- Enforce the use of this template by using `trestle` and a GitHub Actions pipeline +- Extend the documentation in the [proposals README.md](./README.md) to cover the use of trestle for proposals +- Minimize the authors effort by using GitHub metadata where appropriate. + +## Non-Goals + +- Demonstrations are not the default for regression tests. Testing should be part of the main project. +- To decide what are the priority demonstrations for oscal-compass + +## Proposal + +1. Reference demonstrations are not included in the [`oscal-compass`](https://github.com/oscal-compass) organization. Demonstrations are confined the `oscal-compass-demos` organization. +2. Due to the nature of Oscal-compass, demonstrations are likely to span multiple repositories. Each demonstration should at least have a descriptive name which is the root repository of the demonstration that includes documentation: + - `https://github.com/oscal-compass-demos/acme-corp-cloud` # An oscal compass demo for 'ACME corps' cloud + - `https://github.com/oscal-compass-demos/trestle-markdown-rendering` # An oscal compass demo repository for markdown rendering +3. Repository should avoid names which are not readily readable or use unnecessary acronyms , shortened, or not contextualized + - `https://github.com/oscal-compass-demos/e2e` # Not specific + - `https://github.com/oscal-compass-demos/ISM` # Bad not everyone knows was the Australian ISM IS + - `https://github.com/oscal-compass-demos/AUGOVISM` # Hard to decipher / search + - `https://github.com/oscal-compass-demos/Australian-govt-ISM` # provides sufficient context. + - `https://github.com/oscal-compass-demos/kubecon-japan-2025` # detailed for an event. +4. Secondary repositories begin with the name of the demonstration + - e.g `https://github.com/oscal-compass-demos/acme-corp-cloud-catalog` + +5. Demonstration content MUST be stable. + - E.g. Owners MUST NOT update the repos under `https://github.com/oscal-compass-demos` in order to run the demo, the demonstration SHOULD be forked. +6. Demonstration repositories can be nominated via an issue in the [`community`](https://github.com/oscal-compass/community) + 1. Demonstrations MUST have at two maintainers nominated. + 2. The name of the demonstration; a description of the intent of the demonstrations; and the repositories are required +7. Demonstrations MUST be actively maintained to the currently supported versions of `oscal-compass` +8. Demonstrations that are not maintained will either be: + 1. Archived, or + 2. Actively document to user why there are limits (e.g. relies on 3rd party content that leverages an old version of OSCAL). +9. Demonstrations must include appropriate blerbs and cross linking from: + 1. Oscal Compass community website + 2. and optionally project websites (e.g. `compliance-trestle` or `compliance-to-policy`) + + +## Design Details + +Sufficient details are above. + +## Impacts / Key Questions + +The proposal is relatively simple. + +The biggest question is how much needs to be recorded in the document itself as opposed to being extracted from the history on GitHub (such as approvers). + + +### Pros + + +### Cons + +- Adoption cost + +## Risks and Mitigations + +Describe the risks of this proposal and how they can be mitigated. This should be broadly scoped and describe how it will impact the larger ecosystem and potentially adopters of the project; such as if adopters need to immediately update, or support a new port or protocol. It should include drawbacks to the proposed solution. + +### Security Considerations + +This proposal relies on the underlying configuration of the underlying GitHub project to maintain security of the process. + +The process is not intended for security-related processes such as responsible disclosure. + + +## Future Milestones (Optional) + +None + +## Implementation Details (Optional) + +In addition to this pull request: + +1. GitHub actions will need to be configured. +2. GitHub project configuration should ensure the required reviewers and actions pipelines are required. + + +### Testing Plan + +Post implementation the first proposal which is not authored by this PR's should examine the workflow. + + +### Update/Rollback Compatibility + +None - this is the starting point. + +### Scalability + +No concerns + +### Implementation Phases/History + +This is self contained to this PR and is net new capability. +Lifecycle management can be conducted using the ability of `trestle author docs` to support multiple template revisions. \ No newline at end of file From 7f94529d75e74fd5f26f81f75beae0a63ad3d9d2 Mon Sep 17 00:00:00 2001 From: Chris Butler Date: Wed, 2 Apr 2025 08:25:32 +0900 Subject: [PATCH 2/3] feat: oscal compass project supported demos Signed-off-by: Chris Butler --- proposals/demonstration-organisation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/demonstration-organisation.md b/proposals/demonstration-organisation.md index db977bb..c722c8f 100644 --- a/proposals/demonstration-organisation.md +++ b/proposals/demonstration-organisation.md @@ -113,7 +113,7 @@ The biggest question is how much needs to be recorded in the document itself as ### Cons -- Adoption cost +TBC BELOW THIS POINT ## Risks and Mitigations From a356f08cac7680bedd688a3c0c2d693c6236f37c Mon Sep 17 00:00:00 2001 From: Chris Butler Date: Fri, 4 Apr 2025 19:11:38 +0900 Subject: [PATCH 3/3] feat: complete first draft Signed-off-by: Chris Butler --- proposals/demonstration-organisation.md | 40 ++++++++++++++----------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/proposals/demonstration-organisation.md b/proposals/demonstration-organisation.md index c722c8f..1817812 100644 --- a/proposals/demonstration-organisation.md +++ b/proposals/demonstration-organisation.md @@ -95,6 +95,10 @@ The result is we do not have a consistent set of project demonstration content. 9. Demonstrations must include appropriate blerbs and cross linking from: 1. Oscal Compass community website 2. and optionally project websites (e.g. `compliance-trestle` or `compliance-to-policy`) +10. Event specific demonstrations (e.g. Kubecon) should follow the following practice + 1. The SHOULD be kept stable with respect to the documentation and videos + 2. If reused in another event they MUST be renamed with another project name + 3. If reused and renamed the events it is used at MUST be referenced in the README.md for traceability ## Design Details @@ -109,43 +113,46 @@ The biggest question is how much needs to be recorded in the document itself as ### Pros - +- Provides clear guidance to curate demonstrations +- Keeps the core organisation clear +- Provides clear expectations for both demo developers and consumers. +- Provides expectations to demo developers and maintainers of required ongoing efforts. ### Cons -TBC BELOW THIS POINT +- It's additional overhead from an OSCAL compass organization perspective which carries the risk of being ignored. + ## Risks and Mitigations -Describe the risks of this proposal and how they can be mitigated. This should be broadly scoped and describe how it will impact the larger ecosystem and potentially adopters of the project; such as if adopters need to immediately update, or support a new port or protocol. It should include drawbacks to the proposed solution. +N/A ### Security Considerations -This proposal relies on the underlying configuration of the underlying GitHub project to maintain security of the process. - -The process is not intended for security-related processes such as responsible disclosure. - +- Github Actions automation carries risks based on how authorization is performed. This proposal will decrease risk as it isolates demo automation further away from core oscal compass projects. +- The ongoing risk with authoritative demonstrations is that it is a larger body of code and projects ## Future Milestones (Optional) None ## Implementation Details (Optional) -In addition to this pull request: - -1. GitHub actions will need to be configured. -2. GitHub project configuration should ensure the required reviewers and actions pipelines are required. - +1. Setup the organization via the CNCF with the correct set of permissions. +2. Create a request workflow for new demo repos in the community github organization. +3. (Optional) create a minimum GitHub template, in the demo to provide organizational minimums. + 1. CNCF references and licenses + 2. Minimum Security workflows for actions + 3. Any other standards deemed necessary +4. Identify and move across existing projects. ### Testing Plan -Post implementation the first proposal which is not authored by this PR's should examine the workflow. - +None ### Update/Rollback Compatibility -None - this is the starting point. +The biggest issue is the movement of projects from a URL perspective. Thankfully most of these issues are managed by Github. ### Scalability @@ -153,5 +160,4 @@ No concerns ### Implementation Phases/History -This is self contained to this PR and is net new capability. -Lifecycle management can be conducted using the ability of `trestle author docs` to support multiple template revisions. \ No newline at end of file +The biggest implementation challenge is (4) above. This will need to be conducted in phases. \ No newline at end of file