diff --git a/.github/ISSUE_TEMPLATE/release_proposal.md b/.github/ISSUE_TEMPLATE/release_proposal.md index 19ed066c..a8fd6017 100644 --- a/.github/ISSUE_TEMPLATE/release_proposal.md +++ b/.github/ISSUE_TEMPLATE/release_proposal.md @@ -23,7 +23,7 @@ assignees: "damienjburks" - [ ] Modify the `metadata.yaml` files to include the latest release details. This can be accomplished in an automated form by running the following command: ```text - cd delivery-tooling + cd delivery-toolkit go run . release-notes -t /services/storage/object ``` diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index eed1c4f0..87ef6041 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -17,7 +17,7 @@ jobs: runs-on: ubuntu-latest defaults: run: - working-directory: ./delivery-tooling + working-directory: ./delivery-toolkit steps: - uses: actions/checkout@v4 name: Build @@ -65,7 +65,7 @@ jobs: uses: actions/upload-artifact@v4.4.0 with: name: ccc-catalogs - path: ./delivery-tooling/artifacts/* + path: ./delivery-toolkit/artifacts/* if-no-files-found: error retention-days: 1 # Maximum Retention diff --git a/.github/workflows/sonatype_scan.yaml b/.github/workflows/sonatype_scan.yaml index 3d2e10ee..4e0aa212 100644 --- a/.github/workflows/sonatype_scan.yaml +++ b/.github/workflows/sonatype_scan.yaml @@ -9,7 +9,7 @@ on: env: SonatypeUrl: "https://finos.sonatype.app/platform/" SonatypeAppId: "ccc-delivery" - SonatypeScanTarget: "delivery-tooling/" + SonatypeScanTarget: "delivery-toolkit/" ExcludeDirectory: "" jobs: diff --git a/.gitignore b/.gitignore index cdc67bc0..bca159a7 100644 --- a/.gitignore +++ b/.gitignore @@ -3,5 +3,5 @@ build/oscal-cli # VS Code .DS_Store # Delivery Tooling -delivery-tooling/artifacts +delivery-toolkit/artifacts .env/ \ No newline at end of file diff --git a/.prettierignore b/.prettierignore index d74cda5b..f31b1f48 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1 +1 @@ -delivery-tooling/* \ No newline at end of file +delivery-toolkit/* \ No newline at end of file diff --git a/delivery-tooling/catalog-compiler.go b/delivery-toolkit/catalog-compiler.go similarity index 100% rename from delivery-tooling/catalog-compiler.go rename to delivery-toolkit/catalog-compiler.go diff --git a/delivery-tooling/gen-markdown.go b/delivery-toolkit/gen-markdown.go similarity index 100% rename from delivery-tooling/gen-markdown.go rename to delivery-toolkit/gen-markdown.go diff --git a/delivery-tooling/gen-release-notes.go b/delivery-toolkit/gen-release-notes.go similarity index 100% rename from delivery-tooling/gen-release-notes.go rename to delivery-toolkit/gen-release-notes.go diff --git a/delivery-tooling/gen-yaml.go b/delivery-toolkit/gen-yaml.go similarity index 100% rename from delivery-tooling/gen-yaml.go rename to delivery-toolkit/gen-yaml.go diff --git a/delivery-tooling/go.mod b/delivery-toolkit/go.mod similarity index 100% rename from delivery-tooling/go.mod rename to delivery-toolkit/go.mod diff --git a/delivery-tooling/go.sum b/delivery-toolkit/go.sum similarity index 100% rename from delivery-tooling/go.sum rename to delivery-toolkit/go.sum diff --git a/delivery-tooling/logos/logo_wall.svg b/delivery-toolkit/logos/logo_wall.svg similarity index 100% rename from delivery-tooling/logos/logo_wall.svg rename to delivery-toolkit/logos/logo_wall.svg diff --git a/delivery-tooling/main.go b/delivery-toolkit/main.go similarity index 98% rename from delivery-tooling/main.go rename to delivery-toolkit/main.go index e4294fb3..a192c4dd 100644 --- a/delivery-tooling/main.go +++ b/delivery-toolkit/main.go @@ -35,7 +35,7 @@ var ( }, Run: func(cmd *cobra.Command, args []string) { fmt.Println(divider) - fmt.Println("Welcome to the CCC Delivery Tooling CLI v" + Version) + fmt.Println("Welcome to the CCC Delivery Toolkit CLI v" + Version) fmt.Print(logo) fmt.Println(divider) fmt.Println("You appear to be exploring!") diff --git a/delivery-tooling/templates/catalog.md b/delivery-toolkit/templates/catalog.md similarity index 100% rename from delivery-tooling/templates/catalog.md rename to delivery-toolkit/templates/catalog.md diff --git a/delivery-tooling/templates/release-notes.md b/delivery-toolkit/templates/release-notes.md similarity index 100% rename from delivery-tooling/templates/release-notes.md rename to delivery-toolkit/templates/release-notes.md diff --git a/delivery-tooling/update-metadata.go b/delivery-toolkit/update-metadata.go similarity index 100% rename from delivery-tooling/update-metadata.go rename to delivery-toolkit/update-metadata.go diff --git a/delivery-tooling/utils.go b/delivery-toolkit/utils.go similarity index 100% rename from delivery-tooling/utils.go rename to delivery-toolkit/utils.go diff --git a/docs/community-guidelines/content-standards-and-practices/control-definitions.md b/docs/community-guidelines/content-standards-and-practices/control-definitions.md index 9408b126..fc86fcd0 100644 --- a/docs/community-guidelines/content-standards-and-practices/control-definitions.md +++ b/docs/community-guidelines/content-standards-and-practices/control-definitions.md @@ -8,7 +8,7 @@ Each service category in the CCC Taxonomy should have its own set of control def To streamline maintenance, the CCC project maintains a list of [common controls]. -Each service category’s `controls.yaml` file references these by listing their IDs under the top-level `common_controls` value. During the release pipeline, our [delivery tooling] compiles these common controls into the final document alongside any specific controls. In the final output, both types of controls are presented consistently, with the unique identifier being the only difference. +Each service category’s `controls.yaml` file references these by listing their IDs under the top-level `common_controls` value. During the release pipeline, our [Delivery Toolkit] compiles these common controls into the final document alongside any specific controls. In the final output, both types of controls are presented consistently, with the unique identifier being the only difference. ### Common Controls @@ -56,7 +56,7 @@ A control family refers to a group of related security controls that are organiz The list of control families is maintained in the [common controls] data. [common controls]: /services/common-controls.yaml -[delivery tooling]: /delivery-tooling +[Delivery Toolkit]: /delivery-toolkit [threats]: ./threat-definitions.md [ref]: https://www.cisa.gov/sites/default/files/2023-02/tlp-2-0-user-guide_508c.pdf diff --git a/docs/community-guidelines/content-standards-and-practices/feature-definitions.md b/docs/community-guidelines/content-standards-and-practices/feature-definitions.md index 0a2f4ee6..8620de54 100644 --- a/docs/community-guidelines/content-standards-and-practices/feature-definitions.md +++ b/docs/community-guidelines/content-standards-and-practices/feature-definitions.md @@ -8,7 +8,7 @@ Each feature definition should be created for a service in the CCC Taxonomy, wit To streamline maintenance, the CCC project maintains a list of [common features]. -Each service category’s `features.yaml` file references common features by listing their IDs under the top-level `common_features` value. During the release pipeline, our [delivery tooling] compiles these common features into the final document alongside any specific features. In the final output, both types of features are presented consistently, with the unique identifier being the only difference. +Each service category’s `features.yaml` file references common features by listing their IDs under the top-level `common_features` value. During the release pipeline, our [Delivery Toolkit] compiles these common features into the final document alongside any specific features. In the final output, both types of features are presented consistently, with the unique identifier being the only difference. ### Common Features @@ -47,4 +47,4 @@ Although a review from the [Communications WG] is optional, it may be useful if [common features]: /services/common-features.yaml [Communications WG]: ../../governance/working-groups/communications/charter.md -[delivery tooling]: /delivery-tooling +[Delivery Toolkit]: /delivery-toolkit diff --git a/docs/community-guidelines/content-standards-and-practices/threat-definitions.md b/docs/community-guidelines/content-standards-and-practices/threat-definitions.md index 282f5cf7..c4c4618c 100644 --- a/docs/community-guidelines/content-standards-and-practices/threat-definitions.md +++ b/docs/community-guidelines/content-standards-and-practices/threat-definitions.md @@ -8,7 +8,7 @@ Each threat definition corresponds to a service in the CCC Taxonomy, with every To streamline maintenance, the CCC project maintains a list of [common threats]. -Each service category’s `threats.yaml` file references these common threats by listing their IDs under the top-level `common_threats` value. During the release pipeline, our [delivery tooling] compiles these common threats into the final document alongside any service-specific threats. In the final output, both types of threats are presented consistently, with the unique identifier being the only difference. +Each service category’s `threats.yaml` file references these common threats by listing their IDs under the top-level `common_threats` value. During the release pipeline, our [Delivery Toolkit] compiles these common threats into the final document alongside any service-specific threats. In the final output, both types of threats are presented consistently, with the unique identifier being the only difference. ### Common Threats @@ -89,5 +89,5 @@ This structure ensures that threats are standardized and can be consistently ide [common threats]: /services/common-threats.yaml [Communications WG]: ../../governance/working-groups/communications/charter.md -[delivery tooling]: /delivery-tooling +[Delivery Toolkit]: /delivery-toolkit [threats template]: ../../resources/templates/threats.yaml diff --git a/docs/resources/training/Readme.md b/docs/resources/training/Readme.md index 0bb37533..b278fecc 100644 --- a/docs/resources/training/Readme.md +++ b/docs/resources/training/Readme.md @@ -3,5 +3,6 @@ ## Links - [OSCAL](https://github.com/finos/common-cloud-controls/blob/main/docs/resources/training/oscal/oscal.md) -- [Markdown Linting and Formatting - End User Guide](./lint_format_user_guide.md) +- [Markdown Linting and Formatting - End User Guide](user_guides/linting_and_formatting.md) - [FINOS CCC Primer](./FINOS-CCC-Primer-June-2024.pdf) +- [Delivery Toolkit - User Guide](user_guides/delivery_toolkit.md) diff --git a/docs/resources/training/user_guides/delivery_toolkit.md b/docs/resources/training/user_guides/delivery_toolkit.md new file mode 100644 index 00000000..df0e289a --- /dev/null +++ b/docs/resources/training/user_guides/delivery_toolkit.md @@ -0,0 +1,173 @@ +# Delivery Toolkit - User Guide + +Welcome to the **Delivery Toolkit** user guide—a powerful solution built with Go, GitHub Actions, and GitHub Releases to automate the creation and compilation of artifacts for public release. + +Before contributing to the codebase, we highly recommend reviewing the [Releases] documentation. The development process is aligned with the strategies outlined there, ensuring consistency and quality across all contributions. + +## Overview + +The Delivery Toolkit consists of several Go files, each serving a specific purpose in the release process. Below is an overview of these files: + +1. **`catalog-compiler.go`** + Compiles YAML-based controls, features, threats, and metadata into a unified catalog with autogenerated links. + +2. **`gen-markdown.go`** + Generates a styled omnibus Markdown file by compiling YAML-based data and rendering it with customizable templates. + +3. **`gen-release-notes.go`** + Produces release notes by compiling catalog data and rendering them into Markdown via customizable templates. + +4. **`gen-yaml.go`** + Converts catalog data into a YAML file and saves it in the specified output directory. + +5. **`update-metadata.go`** + Updates metadata YAML files, including commit history, contributors, and changelogs, using the GitHub API. + +6. **`utils.go`** + Provides shared utility functions to streamline development across the toolkit. + +## Local Setup and Configuration + +### Prerequisites + +Before you begin, ensure the following tools are installed: + +1. [**Golang**](https://go.dev/doc/install) - The primary language of the project. +2. [**VS Code**](https://code.visualstudio.com/download) - A versatile code editor. +3. [**Git**](https://git-scm.com/downloads) - For version control and repository management. +4. [**Docker**](https://docs.docker.com/engine/install/) - Used for PDF generation. + +Additionally, install the **Go VS Code Extension** for a better development experience: +[Install here](https://marketplace.visualstudio.com/items?itemName=golang.go). +![VS Code Extensions](imgs/delivery_toolkit/image-6.png) + +### Installing Dependencies + +1. Clone the repository locally: + + ```bash + git clone + ``` + + If you're new to Git, follow this guide: [How to Git Clone](https://www.geeksforgeeks.org/how-to-git-clone-a-remote-repository/). + +2. Open the repository in VS Code and run the following commands in the terminal: + + ```bash + cd delivery-toolkit + go get # Install required dependencies + ``` + +3. Verify the setup: + + ```bash + go run . + ``` + + **Expected Output**: + + ```bash + ---------------------------------------- + _______________ + / ___/ ___/ ___/ + / / / / / / + / /__/ /__/ /___ + \____/____/____/ + + ---------------------------------------- + + Welcome to the CCC Delivery Toolkit CLI v0.0.0-dev + Use the 'help' command (-h) to explore available options. + ---------------------------------------- + ``` + +4. Pull the Docker image required for PDF generation: + + ```bash + docker pull jmaupetit/md2pdf + ``` + +## Testing Locally + +Here are some example commands for testing the toolkit locally: + +- **Generate an Omnibus Markdown File** + + ```bash + go run . "md" -t ../services/storage/object/ + ``` + + **Output Example**: + + ```text + File generated successfully: artifacts/CCC.ObjStor_2025.01.md + ``` + +- **Generate a YAML File** + + ```bash + go run . "yaml" -t ../services/storage/object/ + ``` + + **Output Example**: + + ```text + File generated successfully: ./artifacts/CCC.ObjStor_2025.01.yaml + ``` + +- **Generate Release Notes** + + ```bash + go run . "release-notes" -t ../services/storage/object/ + ``` + + **Output Example**: + + ```text + File generated successfully: artifacts/release_notes.md + ``` + +- **Update Metadata** + + ```bash + go run . "update-metadata" -t ../services/storage/object/ + ``` + + **Output Example**: + + ```text + Metadata updated successfully: ../services/storage/object/metadata.yaml + ``` + + > **NOTE**: This command modifies metadata files and should only be used during release preparation. + +## Triggering the Artifact Pipeline + +The Artifact Pipeline is the backbone of the Delivery Toolkit, leveraging GitHub Actions to: + +- Compile version-controlled catalog data. +- Create a release candidate using GitHub Releases. +- Generate release notes with appropriate tagging. + +### Steps to Execute + +1. Log in to GitHub and navigate to the `common-cloud-controls` repository. +2. Click **Actions** in the repository menu. + ![Actions Tab](imgs/delivery_toolkit/image.png) +3. Select the **Release Workflow** on the left-hand side. + ![Release Workflow](imgs/delivery_toolkit/image-1.png) +4. Click **Run workflow**, specify the target service and tag, and then confirm. + ![Run Workflow Example](imgs/delivery_toolkit/image-2.png) + + > **Note**: The process may take a few minutes to complete. + +5. Verify the release under [Common Cloud Controls Releases](https://github.com/finos/common-cloud-controls/releases) and ensure it aligns with the [Release Guidelines](../../../community-guidelines/content-standards-and-practices/release-assets.md). + +6. Once verified, update the release title and tag by removing the `-rc` designation. + + Example: + + - **Title**: Release v2025.01.VPC + - **Tag**: v2025.01.VPC + + ![Edit Release Example](imgs/delivery_toolkit/image-5.png) diff --git a/docs/resources/training/user_guides/imgs/delivery_toolkit/image-1.png b/docs/resources/training/user_guides/imgs/delivery_toolkit/image-1.png new file mode 100644 index 00000000..d36f46d8 Binary files /dev/null and b/docs/resources/training/user_guides/imgs/delivery_toolkit/image-1.png differ diff --git a/docs/resources/training/user_guides/imgs/delivery_toolkit/image-2.png b/docs/resources/training/user_guides/imgs/delivery_toolkit/image-2.png new file mode 100644 index 00000000..2d95edfd Binary files /dev/null and b/docs/resources/training/user_guides/imgs/delivery_toolkit/image-2.png differ diff --git a/docs/resources/training/user_guides/imgs/delivery_toolkit/image-3.png b/docs/resources/training/user_guides/imgs/delivery_toolkit/image-3.png new file mode 100644 index 00000000..62a11d1d Binary files /dev/null and b/docs/resources/training/user_guides/imgs/delivery_toolkit/image-3.png differ diff --git a/docs/resources/training/user_guides/imgs/delivery_toolkit/image-4.png b/docs/resources/training/user_guides/imgs/delivery_toolkit/image-4.png new file mode 100644 index 00000000..b03207dc Binary files /dev/null and b/docs/resources/training/user_guides/imgs/delivery_toolkit/image-4.png differ diff --git a/docs/resources/training/user_guides/imgs/delivery_toolkit/image-5.png b/docs/resources/training/user_guides/imgs/delivery_toolkit/image-5.png new file mode 100644 index 00000000..08cbc8ea Binary files /dev/null and b/docs/resources/training/user_guides/imgs/delivery_toolkit/image-5.png differ diff --git a/docs/resources/training/user_guides/imgs/delivery_toolkit/image-6.png b/docs/resources/training/user_guides/imgs/delivery_toolkit/image-6.png new file mode 100644 index 00000000..f49c9c2e Binary files /dev/null and b/docs/resources/training/user_guides/imgs/delivery_toolkit/image-6.png differ diff --git a/docs/resources/training/user_guides/imgs/delivery_toolkit/image.png b/docs/resources/training/user_guides/imgs/delivery_toolkit/image.png new file mode 100644 index 00000000..c6b6dc67 Binary files /dev/null and b/docs/resources/training/user_guides/imgs/delivery_toolkit/image.png differ diff --git a/docs/resources/training/lint_format_user_guide.md b/docs/resources/training/user_guides/linting_and_formatting.md similarity index 97% rename from docs/resources/training/lint_format_user_guide.md rename to docs/resources/training/user_guides/linting_and_formatting.md index d39779c6..d52d5240 100644 --- a/docs/resources/training/lint_format_user_guide.md +++ b/docs/resources/training/user_guides/linting_and_formatting.md @@ -72,4 +72,4 @@ Thanks for reading. At this point, you have now successfully installed and confi If you have any issues, please do not hesistate to reach out to the [Delivery WG] for more assistance. -[Delivery WG]: ../../governance/working-groups/delivery/charter.md +[Delivery WG]: ../../../governance/working-groups/delivery/charter.md diff --git a/services/storage/object/metadata.yaml b/services/storage/object/metadata.yaml index 4a0ca67a..a967d541 100644 --- a/services/storage/object/metadata.yaml +++ b/services/storage/object/metadata.yaml @@ -1,12 +1,12 @@ title: Object Storage id: CCC.ObjStor description: | - Object storage is a data storage architecture that manages data as objects, - rather than as files or blocks. Each object contains the data itself, - metadata, and a unique identifier, making it ideal for storing large amounts - of unstructured data such as multimedia files, backups, and archives. It is - highly scalable and often used in cloud environments due to its flexibility - and accessibility. + Object storage is a data storage architecture that manages data as objects, + rather than as files or blocks. Each object contains the data itself, + metadata, and a unique identifier, making it ideal for storing large amounts + of unstructured data such as multimedia files, backups, and archives. It is + highly scalable and often used in cloud environments due to its flexibility + and accessibility. release_details: - version: "2025.01" assurance_level: None @@ -27,25 +27,52 @@ release_details: continue to build on this foundation. A huge thanks to everyone who has brought us to this point! change_log: - - | - This initial release contains a variety of commits designed to capture - all of the features, threats, and controls for this service category. + - VPC Networking Release - 2025.01 (#584) + - Object Storage Release - 2025.01 (#581) + - Formatting changes for VPC and Object Storage (#578) + - Polished ObjStor Test Requirements (#577) + - Add in fixes to control definitions (#570) + - "#534: Add yaml linter (#543)" + - Add in updates to soft and hard delete bucket controls (#528) + - October Release Candidate - Object Storage (#445) + - Add in fixes to object storage threats, controls, features (#436) + - Typofix on control IDs (#432) + - Object storage final polish (#419) + - Adding Contributors key to metadata schema (#409) + - Object Storage Controls Revision (#394) + - GenAI taxonomy (#393) + - Updates to the structure of the metadata yaml (#383) + - Schema updates (#377) + - Handling common entries for features, threats, & controls (#327) + - Convert Object Storage development files from MD to YAML (#325) + - Add in new object storage controls on encryption for impact and replication to untrusted destinations (#305) + - Convert existing taxonomies to the new yaml format (#319) + - Fix broken links (#317) + - Added CCC.OS.C6 Control (#298)Looks good + - Extend Object Storage Controls (#263) + - Creation of Global Markdown Formatting and Linting GitHub Actions (#223) + - Draft Proposal for Threat Catalog and Control Catalog Taxonomy (#153) + - Signed URLs added + - addressed review comments by @rgriffiths-scottlogic + - address review comments by stevie from scott logic and further improvements + - updates + - initial version of the object store taxonomy contributors: + - name: Damien Burks + github_id: damienjburks + company: REPLACE_ME - name: Sonali Mendis github_id: smendis-scottlogic - company: Scott Logic + company: REPLACE_ME - name: Eddie Knight github_id: eddie-knight - company: Sonatype + company: REPLACE_ME - name: Michael Lysaght github_id: mlysaght2017 - company: Citi + company: REPLACE_ME - name: Dave Ogle github_id: dogle-scottlogic - company: Scott Logic - - name: Damien Burks - github_id: damienjburks - company: Citi + company: REPLACE_ME - name: Naseer Mohammad github_id: nas-hub - company: Google + company: REPLACE_ME