From 3e0fb5acd5c590c96aeb18f5941002aea4e0dbcd Mon Sep 17 00:00:00 2001 From: Andrew <46836330+andrewg-xyz@users.noreply.github.com> Date: Wed, 2 Oct 2024 01:03:14 -0600 Subject: [PATCH] docs: introduce badging levels (#242) Co-authored-by: Brandt Keller <43887158+brandtkeller@users.noreply.github.com> Co-authored-by: Jon Schulman <25127543+jonnyborbs@users.noreply.github.com> Co-authored-by: Wayne Starr --- README.md | 2 +- docs/made-for-uds-bronze.svg | 142 +++++++++++++++++ docs/made-for-uds-gold.svg | 142 +++++++++++++++++ docs/made-for-uds-silver.svg | 142 +++++++++++++++++ docs/package_integration/guide.md | 8 +- docs/package_integration/oscal-guidelines.md | 23 +++ .../package_integration/testing-guidelines.md | 37 +++-- .../uds-package-practices.md | 148 +++++++++--------- 8 files changed, 544 insertions(+), 100 deletions(-) create mode 100644 docs/made-for-uds-bronze.svg create mode 100644 docs/made-for-uds-gold.svg create mode 100644 docs/made-for-uds-silver.svg create mode 100644 docs/package_integration/oscal-guidelines.md diff --git a/README.md b/README.md index 84f7034d..fffd5bbe 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # UDS Common -This repository contains common configuration and tasks used in UDS Packages for management, setup, creation, deployment, and publishing of packages and bundles. It is useful to help implement [UDS package practices](./docs/package_integration/uds-package-practices.md). +This repository contains common configuration and tasks used in UDS Packages for management, setup, creation, deployment, and publishing of packages and bundles. It also includes [UDS package practices](./docs/package_integration/uds-package-practices.md) defining requirements and standards to obtain the [Made for UDS](https://github.com/defenseunicorns/uds-core) Badges. ## Task Usage diff --git a/docs/made-for-uds-bronze.svg b/docs/made-for-uds-bronze.svg new file mode 100644 index 00000000..d6612cb9 --- /dev/null +++ b/docs/made-for-uds-bronze.svg @@ -0,0 +1,142 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/made-for-uds-gold.svg b/docs/made-for-uds-gold.svg new file mode 100644 index 00000000..b55e7452 --- /dev/null +++ b/docs/made-for-uds-gold.svg @@ -0,0 +1,142 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/made-for-uds-silver.svg b/docs/made-for-uds-silver.svg new file mode 100644 index 00000000..c22d205c --- /dev/null +++ b/docs/made-for-uds-silver.svg @@ -0,0 +1,142 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/package_integration/guide.md b/docs/package_integration/guide.md index eab339eb..9deeed7a 100644 --- a/docs/package_integration/guide.md +++ b/docs/package_integration/guide.md @@ -5,7 +5,7 @@ This guide is intended for developers integrating applications with UDS (Unicorn Delivery Service). It provides an overview of the integration process, key considerations, and resources to ensure a smooth integration. Integrating a Package fundamentally means: -1. Creating a repository `uds-package-` +1. Creating a repository `uds-package-` from [uds-package-template](https://github.com/defenseunicorns/uds-package-template) 2. Integrating the upstream helm chart as a zarf package `zarf.yaml` to build a declarative OCI artifact 3. Adding a UDS package Custom Resource `uds-package.yaml` to integrate with UDS Core via Pepr 4. Build a 'zero CVE' package by replacing images with a `*-unicorn` flavored image @@ -28,9 +28,9 @@ Integrating a Package fundamentally means: Before beginning the integration process, familiarize yourself with the following resources: 1. [UDS Capabilities Documentation](https://uds.defenseunicorns.com/capabilities/): Provides information about UDS, UDS CLI, UDS Core, and UDS Bundles. -2. [Zarf Documentation](https://docs.zarf.dev): Zarf is a tool for declarative creation & distribution of software. +2. [Zarf Documentation](https://docs.zarf.dev): Zarf is a tool for declarative creation & distribution of software packages. 3. [UDS Common Repository](https://github.com/defenseunicorns/uds-common): Contains information and best practices for UDS integration. -4. [UDS Applications Tracker](https://coda.io/d/Product_dGmk3eNjmm8/Applications_sux6H#_luFRc): Lists many backlogged and completed applications for UDS integration. +4. [UDS Applications Tracker](https://coda.io/d/Product_dGmk3eNjmm8/Applications_suCbOWqL#_lu8fEKSc): Lists many backlogged and completed applications for UDS integration. 5. Briefly review [Pepr Documentation](https://docs.pepr.dev/): it may become useful when you begin integrating with UDS Core. ## Integration Checklist @@ -68,4 +68,4 @@ Your repository has a `uds-package.yaml` manifest added to the appropriate helm For reference, consider these well-maintained UDS package examples: - [UDS Package GitLab](https://github.com/defenseunicorns/uds-package-gitlab) (More complex example) - [UDS Package Mattermost](https://github.com/defenseunicorns/uds-package-mattermost) (Simpler example) -- [UDS Common NGINX](https://github.com/defenseunicorns/uds-common) \ No newline at end of file +- [UDS Common NGINX](https://github.com/defenseunicorns/uds-common) diff --git a/docs/package_integration/oscal-guidelines.md b/docs/package_integration/oscal-guidelines.md new file mode 100644 index 00000000..2557dfaa --- /dev/null +++ b/docs/package_integration/oscal-guidelines.md @@ -0,0 +1,23 @@ +# OSCAL: the Open Security Controls Assessment Language + + +[OSCAL](https://pages.nist.gov/OSCAL/) is a set of standards for describing security and privacy controls for information systems. It is developed by the National Institute of Standards and Technology (NIST) and is intended to be used by organizations to automate the exchange of security and privacy control information. + +UDS Packages will include an `oscal-component.yaml` file that describes the security and privacy controls that the package implements. In combination with uds-core, this file will be used to accelerate Authorizations and contribute to control response and mapping. [Lula](https://github.com/defenseunicorns/lula) is here to help us! + +Gold packages will include a baseline set of [NIST 800-53 controls](https://csrc.nist.gov/pubs/sp/800/53/r5/upd1/final), specifically: +- AC-6.9 +- AU-2 +- AU-3 +- AU-3.1 +- AU-8 +- AU-12 +- SC-13 + +This command will generate an `oscal-component.yaml` file for a package that implements these controls. Once generated you can add specific responses to the controls. +``` +lula generate component -c https://raw.githubusercontent.com/GSA/fedramp-automation/refs/tags/fedramp-2.0.0-oscal-1.0.4/dist/content/rev5/baselines/json/FedRAMP_rev5_MODERATE-baseline-resolved-profile_catalog.json --framework il4 --requirements ac-6.9,au-2,au-3,au-3.1,au-8,au-12,sc-13 --remarks assessment-objective -o oscal-component.yaml --component 'app-name' +``` + +> [!TIP] +> The baseline controls are a starting point, you should explore additional controls relevant to your package. \ No newline at end of file diff --git a/docs/package_integration/testing-guidelines.md b/docs/package_integration/testing-guidelines.md index 35bbd957..51954c77 100644 --- a/docs/package_integration/testing-guidelines.md +++ b/docs/package_integration/testing-guidelines.md @@ -2,24 +2,23 @@ ## Table of Contents -1. [Introduction](#introduction) -2. [Journey Testing](#journey-testing) - - [Definition](#definition) - - [Key Principles](#key-principles) - - [Implementation Guidelines](#implementation-guidelines) - - [Tools](#tools) -3. [Upgrade Testing](#upgrade-testing) - - [Key Considerations](#key-considerations) -4. [Linting and Static Analysis](#linting-and-static-analysis) - - [Recommended Tools](#recommended-tools) -5. [Best Practices](#best-practices) -6. [Best Practice Examples](#best-practice-examples) - - [Journey Tests](#journey-tests) - - [Upgrade Tests](#upgrade-tests-1) - - [Test Execution](#test-execution) -7. [Consistency Across Packages](#consistency-across-packages) -8. [Contribution and Maintenance](#contribution-and-maintenance) -9. [Related Resources](#related-resources) +- [Testing Guidelines for UDS Marketplace Apps](#testing-guidelines-for-uds-marketplace-apps) + - [Table of Contents](#table-of-contents) + - [Introduction](#introduction) + - [Journey Testing](#journey-testing) + - [**Definition**](#definition) + - [**Key Principles**](#key-principles) + - [**Implementation Guidelines**](#implementation-guidelines) + - [**Tools**](#tools) + - [Upgrade Testing](#upgrade-testing) + - [**Key Considerations**](#key-considerations) + - [Linting and Static Analysis](#linting-and-static-analysis) + - [**Recommended Tools**](#recommended-tools) + - [**Best Practices**](#best-practices) + - [**Best Practice Examples**](#best-practice-examples) + - [Consistency Across Packages](#consistency-across-packages) + - [Contribution and Maintenance](#contribution-and-maintenance) + - [Related Resources](#related-resources) ## Introduction @@ -44,7 +43,7 @@ A **Journey** in the context of UDS package testing is defined as: - Handle limitations due to licensing or other constraints by documenting them and implementing what testing is possible. ### **Tools** -- UI Testing: Playwright, Cypress +- UI Testing: Playwright - Non-UI Testing: Jest - Custom Scripts: Bash or other scripting languages as needed diff --git a/docs/package_integration/uds-package-practices.md b/docs/package_integration/uds-package-practices.md index d01e3199..cd0921d3 100644 --- a/docs/package_integration/uds-package-practices.md +++ b/docs/package_integration/uds-package-practices.md @@ -1,102 +1,91 @@ # UDS Package Practices -This document describes the practices that a UDS package _**must**_, _**should**_ and _**may**_ follow to be considered officially supported as a UDS package. +This document describes the standards for [Made for UDS](https://github.com/defenseunicorns/uds-core) badging. It is not a comprehensive guide to creating UDS Packages and assumes familiarity with the UDS ecosystem and UDS Package Custom Resource. If you are unfamiliar with these concepts, please first refer to the [package integration guide](guide.md) providing more detailed information. -_and most importantly..._ -> Earning the [Made for UDS](https://github.com/defenseunicorns/uds-core) badge and leveraging UDS Core. +Made for UDS Packages integrate with services and features of [UDS Core](https://github.com/defenseunicorns/uds-core), through the [UDS `Package` custom resource](https://github.com/defenseunicorns/uds-core/blob/main/src/pepr/operator/README.md#example-uds-package-cr). These packages can be one of three tiers: -> [!NOTE] -> This badge should link to the `uds-core` repo and should match the height of any other badges (i.e. `20px`). - -> [!TIP] -> This document follows [RFC-2119](https://datatracker.ietf.org/doc/html/rfc2119) for definitions of requirement levels (e.g. **must**, **should** and **may**) - -Integrating a Package fundamentally means: -1. Creating a repository `uds-package-` -2. Integrating the upstream helm chart as a zarf package `zarf.yaml` to build a declarative OCI artifact -3. Adding a UDS package Custom Resource `uds-package.yaml` to integrate with UDS Core via Pepr -4. Build a 'zero CVE' package by replacing images with a `*-unicorn` flavored image - -This document is intentionally lightweight for quick reference. A more detailed guide can be found [here](guide.md). - -## Integrations - -Below are the minimal services that a UDS package **must** integrate with, using the [UDS `Package` custom resource](https://github.com/defenseunicorns/uds-core/blob/main/src/pepr/operator/README.md#example-uds-package-cr). These integrations **must** be declarative and automated without requiring click-ops from the person deploying the package. Packages also **should** consider integrations with any additional UDS services that are relevant to that application. - -> [!NOTE] -> Additional services will be added and integration requirements will change as `uds-core` continues to evolve. UDS Package implementers **should** keep up with `uds-core` releases and changes to this document. The "Made for UDS" badge **may** be requested to be removed if a package is not updated in a timely fashion. - -### Istio - -- **Must** define any external interfaces under the `expose` key. -- **Must** deploy and operate successfully with Istio injection enabled in the namespace. -- **Should** avoid workarounds such as disabling strict mTLS peer authentication. +[Gold](https://github.com/defenseunicorns/uds-core), [Silver](https://github.com/defenseunicorns/uds-core), or [bronze](https://github.com/defenseunicorns/uds-core). -### Network Policies +> [!IMPORTANT] +> Packages should aim for Gold by default and only _SETTLE_ for lesser tiers of Bronze and Silver. -- **Must** define network policies under the `allow` key as required. -- **Should** minimize network policies to specific selectors needed for Ingress/Egress traffic. -- **May** template network policy keys to provide flexibility for delivery customers to configure. +> [!TIP] +> As a package creator navigates the badging levels, they may encounter scenarios that can't be resolved without changes to the upstream application. It is recommended to document these scenarios to alleviate the challenge of maintaining the package. It will not change the badging level. -### Keycloak -- **Must** use and create a Keycloak client through the `sso` key if the application provides an end-user login. -- **Should** consider security options during implementation to provide the most secure default possible (i.e. SAML w/SCIM vs OIDC). -- **Should** name the client ` Login` (i.e. `Mattermost Login`) to provide login UX consistency. -- **Should** clearly mark the client id with the group and app name `uds--` (i.e. `uds-swf-mattermost`) to provide consistency in the Keycloak UI. -- **May** end any generated secrets with `-sso` to easily locate them when querying the cluster. -- **May** template Keycloak fields to provide flexibility for delivery customers to configure. - -### Prometheus +> [!TIP] +> This document follows [RFC-2119](https://datatracker.ietf.org/doc/html/rfc2119) for definitions of requirement levels (e.g. **must**, **should** and **may**) -- **Must** implement monitors for each application metrics endpoint using it's built-in chart monitors, the `Package` CR `monitor` key, or manual monitors in the config chart. +## Gold -## Exemptions +_a Gold UDS Package implements best-effort 0-cve images, configuration hardening, and meets the unicorn guarantee out of the box with zero additional effort._ -UDS Packages **may** make use of the [UDS `Exemption` custom resource](https://github.com/defenseunicorns/uds-core/blob/main/src/pepr/operator/README.md#example-uds-exemption-cr) for exempting any Pepr policies, but in doing so they: +Gold Packages: +- **Must** satisfy all the requirements of [Silver](#silver) packages +- **Must** include OSCAL-component control mapping and responses for the application. see [OSCAL Guidelines](oscal-guidelines.md) - **Must** minimize the scope and number of the exemptions to only what is absolutely required by the application -- **Must** have documented rationale for any exemptions present - -## Structure + - UDS Packages **may** make use of the [UDS `Exemption` custom resource](https://github.com/defenseunicorns/uds-core/blob/main/src/pepr/operator/README.md#example-uds-exemption-cr) for exempting any Pepr policies, but in doing so they **Must** document rationale for the exemptions +- **Must** declaratively implement any available application hardening guidelines by default (Example: [GitLab Hardening guidelines](https://docs.gitlab.com/ee/security/hardening.html)) +- **Must** release a unicorn flavor package, providing a minimal CVE baseline -Packages also follow structural guidelines to ensure consistency and flexibility for configuration, they: +## Silver -- **Must** contain documentation under a `docs` folder at the root that describes how to configure the package and outlines package dependencies. - > This allows users of the package to learn more about exposed configuration - it is recommended to make the entrypoint for configuration `configuration.md`. +_a Silver UDS Package integrates with the main features of the UDS Operator, is documented, maintained, and can be confidently operated in production._ +- **Must** satisfy all the requirements of [Bronze](#bronze) Packages +- **Must** define network policies under the `allow` key as required in the [UDS Package Custom Resource](https://github.com/defenseunicorns/uds-core/blob/main/docs/configuration/uds-operator.md) +- **Must** (except if the application provides no end user login) use and create a Keycloak client through the `sso` key. [UDS Package Custom Resource](https://github.com/defenseunicorns/uds-core/blob/main/docs/configuration/uds-operator.md) +- **Must** (except if the application provides no application metrics) implement monitors for each application metrics endpoint using it's built-in chart monitors, `monitor` key, or manual monitors in the config chart. +- **Must** integrate declaratively (i.e. no clickops) with the UDS Operator - **Should** expose all configuration (`uds.dev` CRs, additional `Secrets`/`ConfigMaps`, etc) through a Helm chart (ideally in a `chart` or `charts` directory). > This allows UDS bundles to override configuration with Helm overrides and enables downstream teams to fully control their bundle configurations. - -- **Should** limit the use of Zarf variable templates and prioritize configuring packages via Helm value overrides. - > This ensures that the package is configured the same way that the bundle would be and avoids any side effect issues of Zarf's `###` templating. - - **Should** implement or allow for multiple flavors (ideally with common definitions in a `common` directory). > This allows for different images or configurations to be delivered consistently to customers. +- **Should** avoid workarounds with Istio such as disabling strict mTLS peer authentication. +- **Should** minimize network policies to specific selectors needed for Ingress/Egress traffic. +- **Should** consider security options during implementation to provide the most secure default possible (i.e. SAML w/SCIM vs OIDC). +- **Should** name the Keycloak client ` Login` (i.e. `Mattermost Login`) to provide login UX consistency. +- **Should** clearly mark the Keycloak client id with the group and app name `uds--` (i.e. `uds-swf-mattermost`) to provide consistency in the Keycloak UI. +- **Should** limit the use of Zarf variable templates and prioritize configuring packages via Helm value overrides. + > This ensures that the package is configured the same way that the bundle would be and avoids any side effect issues of Zarf's `###` templating. +- **May** template network policy keys to provide flexibility for delivery customers to configure. +- **May** end any generated Keycloak client secrets with `-sso` to easily locate them when querying the cluster. +- **May** template Keycloak fields to provide flexibility for delivery customers to configure. -## Testing - -A UDS Package will also have testing and quality checks to ensure that updates / changes to them result in minimal churn. Packages: - -- **Must** implement Journey Testing to cover the basic user flows and features of the application, especially where an application interacts with an external service / interface. - > This can by something like Playwright / [Cypress](https://github.com/defenseunicorns/uds-identity-config/tree/main/src/test/cypress) tests for services with a Web UI or something like [Jest](https://github.com/defenseunicorns/uds-package-gitlab-runner/tree/main/test) tests for headless services. - -- **Must** implement Upgrade Testing to ensure that the current development package works when deployed over the previously released one. - -- **Should** lint their configurations with appropriate tooling such as [`yamllint`](https://github.com/adrienverge/yamllint) and [`zarf dev lint`](https://docs.zarf.dev/commands/zarf_dev_lint/). +## Bronze -For more detailed guidelines on implementing these testing practices, please refer to the [Testing Guidelines for UDS Packages](./testing-guidelines.md). +_a Bronze UDS Package meets the minimum requirements and becomes compatible, but not optimal or fully integrated, with UDS. It is not ready to run in production without significant caveats._ +Bronze packages: -## Maintenance +- **Should** be created from the [UDS Package Template](https://github.com/defenseunicorns/uds-package-template) +- **Must** be declaratively bundled in a [Zarf package](https://docs.zarf.dev/ref/create/) +- **Must** define any external interfaces under the `expose` key in the [UDS Package Custom Resource](https://github.com/defenseunicorns/uds-core/blob/main/docs/configuration/uds-operator.md) +- **Must** deploy and operate successfully with Istio injection enabled in the namespace. +- **Must** implement Journey testing, covering the basic user flows and features of the application (see [Testing Guidelines](./testing-guidelines.md)) +- **Must** implement Upgrade Testing to ensure that the current development package works when deployed over the previously released one. (see [Testing Guidelines](./testing-guidelines.md)) +- **Must** be capable of operating within an internet-disconnected (air-gapped) environment +- **Must** be actively maintained by the package maintainers identified in CODEOWNERS [see #CODEOWNERS section for more information](#codeowners) +- **Must** be versioned using the UDS Package [Versioning scheme](#versioning) +- **Must** contain documentation under a `docs` folder at the root that describes how to configure the package and outlines package dependencies. + > This allows users of the package to learn more about exposed configuration - it is recommended to make the entrypoint for configuration `configuration.md`. +- **Must** have a dependency management bot (such as renovate) configured to open PRs to update the core package and support dependencies. +- **Must** release its package to the `ghcr.io/defenseunicorns/packages/` namespace as the application's name (i.e. `ghcr.io/defenseunicorns/packages/uds/mattermost`). +- **Must** not make the assumption that the `expose` interfaces are accessible to the bastion or pipeline deploying the package (i.e. `*.uds.dev`). + > If web requests need to be made they should be done through a `Job` or `./uds zarf tools kubectl exec` as appropriate. +- **Should** lint their configurations with appropriate tooling, such as [`yamllint`](https://github.com/adrienverge/yamllint) and [`zarf dev lint`](https://docs.zarf.dev/commands/zarf_dev_lint/). -To help maintain a UDS Package, it: +## Badging -- **Must** have a dependency management bot (such as renovate) configured to open PRs to update core package and support dependencies. +> [!NOTE] +> The badge should link to the `uds-core` repo and should match the height of any other badges (i.e. `20px`). -- **Must** release its package to the `ghcr.io/defenseunicorns/packages/` namespace as the application's name (i.e. `ghcr.io/defenseunicorns/packages/uds/mattermost`). +> [!NOTE] +> Additional services will be added and integration requirements will change as `uds-core` continues to evolve. UDS Package implementers **should** keep up with `uds-core` releases and changes to this document. The "Made for UDS" badge **may** be removed if a package is not updated in a timely fashion. ## Versioning + Use this section to decide how best to version a UDS Package. - **Must** be versioned using the below example versioning scheme, or if this scheme doesn't make sense for the use case (i.e. a monorepo like [uds core](https://github.com/defenseunicorns/uds-core)) fall back to using [semantic versioning](https://semver.org/) @@ -104,7 +93,9 @@ Use this section to decide how best to version a UDS Package. - **Should** prepend `git` tags representing versions with a `v` to distinguish them from other tags with OCI tags left as the raw version. #### Example Versioning Scheme + When A UDS Package is clearly representing a single overarching application, even if it consists of many, and that application contains a canonical app version to track, use this scheme. + ``` -uds. ``` @@ -120,12 +111,17 @@ In practice, this results in the following for the second release of a package f 17.2.1-uds.1 ``` -## General +## CODEOWNERS -And in addition to the above, packages generally: +The CODEOWNERS file should address two key concerns: +1. The package is guaranteed to be maintained by a resourced team +2. During creation, the package can be built with speed - without waiting for the 'maintenance' team -- **Must** be capable of operating within an internet-disconnected (air-gapped) environment. - -- **Must** not make the assumption that the `expose` interfaces are accessible to the bastion or pipeline deploying the package (i.e. `*.uds.dev`). If web requests need to be made they should be done through a `Job` or `./uds zarf tools kubectl exec` as appropriate. +Template CODEOWNERS file: +``` +/* @defenseunicorns/uds-package-maintainers +# /* @name-of-creator/s #optional during package creation to enable velocity +# /* @name-of-established-known-team #optional addition to "uds-package-maintainers" -- **Must** be maintained by a resourced team that is explicitly defined as maintaining the project (i.e. in `CODEOWNERS`). +/CODEOWNERS @defenseunicorns/uds-package-maintainers +```