Community and Contribution

• 1: Dependency Updates
• 2: Lula Release
• 3: Roadmap
• 4: Schema Updates
• 5: Testing
• 6: Triage

1 - Dependency Updates

Responsibility

Dependency updates are a responsibility of all project maintainers. All maintainers must be accountable for the updates they introduce and proper review provides a mechanism for reducing the potential for negative impact to the project.

Objectives

• Ensuring that all dependencies are updated to their latest versions
• Understanding the implications of updated dependency code
• Validating the provenance of the updated dependency
• Annotation of the reviewed dependency updates

Guidance

Through the use of Renovate, we can automate the process of updating our dependencies to their latest versions. With this automation comes the responsibility to review considerations and implications to the updates the changes introduce. Review of the dependency updates will begin as renovate creates a pull request with the dependency update. Review should then include the following:

• Review the dependency release notes included in the Pull Request
• Compare the source code changes between tagged versions of the dependency
  • Isolate and annotate any potential updates that may impact the project code
  • Review updates for new features or processes that may be positively consumed by the project
• Validate the integrity / provenance of the updated dependency
  • Golang checksums
    • go.mod and project checksums
  • NPM integrity
    • tarball integrity validation
  • Workflow Integrity
    • Tag Commit checksum
• Annotation of the reviewed dependency updates for approval
  • Include any relevant notes or considerations
  • Include steps to validate the dependency updates

Examples

Golang Dependencies

Given a dependency in the go.mod file, the following steps are taken to validate the dependency:

1. Identify the dependency source - IE github.com/open-policy-agent/opa
2. Identify the tagged version - IE v0.62.1
3. Curl the checksum of the tagged version - IE curl https://sum.golang.org/lookup/${source}@${tag}

The following should be returned for use in validation:

github.com/open-policy-agent/opa v0.62.1 h1:UcxBQ0fe6NEjkYc775j4PWoUFFhx4f6yXKIKSTAuTVk=
github.com/open-policy-agent/opa v0.62.1/go.mod h1:YqiSIIuvKwyomtnnXkJvy0E3KtVKbavjPJ/hNMuOmeM=

NPM Dependencies

Given a dependency in the package-lock.json file, the following steps are taken to validate the dependency:

1. Identify the resolved dependency archive - IE https://registry.npmjs.org/autoprefixer/-/autoprefixer-10.4.19.tgz
2. Curl the archive locally - IE curl -LO https://registry.npmjs.org/autoprefixer/-/autoprefixer-10.4.19.tgz
3. Perform a SHA512 hash on the archive - IE cat ./autoprefixer-10.4.19.tgz | openssl dgst -sha512 -binary | openssl base64 -A
4. Compare results against the integrity field in the package-lock.json file

GitHub Action Dependencies

Review the updated commit hash of the tagged action against the tag of the action in the source git repository.

Notes

• Validation of the checksums is currently a manual process and a byproduct of not yet capturing the provenance of Renovates checksum process. Given that no single version of Renovate is being used (this is the non-self-hosted GitHub application), we do not track updates to the renovate runtime itself.

2 - Lula Release

This document provides guidance on how to create Lula releases, address release issues, and other helpful tips.

Creating releases

This project uses goreleaser for releasing binaries and release-please for creating release PR’s.

How should I write my commits?

We use conventional commit messages Conventional Commit messages.

The most important prefixes you should have in mind are:

• fix: which represents bug fixes, and correlates to a SemVer patch.
• feat: which represents a new feature, and correlates to a SemVer minor.
• feat!:, or fix!:, refactor!:, etc., which represent a breaking change (indicated by the !) and will result in a SemVer major.

How can I influence the version number for a release?

PR titles should also follow this pattern and are linted using commitlint. The PR title will determine the version bump. When a PR is merged (squashed) release-please will kick off a release PR. When that release PR is approved and merged, release-please will create a draft release. Once that draft release is published go-releaser with build and publish the assets, including creating a release in our Homebrew tap repository: https://github.com/defenseunicorns/homebrew-tap

• Pre-v1.0.0 release-please is configured to bump minors on breaking changes and patches otherwise. per release-please-config

How do I fix a release issue?

There are some different ways that something could go wrong with a release, below are some example scenarios and how to fix them.

A release is “broken” and should not be used

Rather than removing a release that is deemed to be broken in some fashion, it should be noted as a broken release in the release notes as soon as possible, and a new release created that fixes the issue(s).

The CHANGELOG is not required to be updated, only the release notes must be updated either manually or with CI automation.

• Manual approach: Find the impacted release, edit the release notes, and put this warning at the top:

>[!WARNING]
>PLEASE USE A NEWER VERSION (there are known issues with this release)

Other issues and helpful tips

• Manual approach: Confirm that the goreleaser configuration is valid by using the goreleaser cli.

goreleaser check .goreleaser.yaml [flags]

• Automated approach: On Push and Pull Request the GoReleaserGitHub Action Workflow will run the goreleaser check command

3 - Roadmap

2024 Annual

Q1 - Foundations & Discovery:

• Release: an initial version of Lula released to enable teams to begin development of validations. Establish process for future releases.
• CI/CD: Establish supported workflows for CI/CD. Structure (Lint) → Assess (validate) → Compare (evaluate)
• Validation Discovery: Create component definition artifacts for use on a variety of apps

Q2 Artifacts & Provenance:

• Artifact Generation: Enable shifting context between OSCAL model artifacts where available to accelerate production of authorization artifacts. Provide reproducible process for component-definition and assessment-results.
• Provenance: Continue to iterate on improving the provenance of artifacts that Lula can process/produce.
• Document: Build and improve documentation to support tool-use with other conceptual patterns required for secure systems.

Q3 Configuration & Coverage:

• Configuration & Templating: Enhance artifacts with optionality to template variables into OSCAL & Validations dynamically. Allowing the use of build-time and run-time templating.
• OSCAL Model Coverage: Increase support of processable OSCAL models to include profile and system-security-plan
• Quality of Life: User Experience improvements to operating with OSCAL and Lula validations

Q4 Data Collection:

• OSCAL Model Coverage: Increase support of processable OSCAL models to include assessment-plan and plan-of-actions-and-milestones (POAM).
• API Domain: Mature the API Domain into a more extensible option for validations.
• Data Collection: Increase domain data collection methods by 1 to enable greater compliance mapping capabilities

2025 Annual (WIP)

Q1 - Benchmarks

• Benchmark: Provide component definition artifacts for various benchmarks/best-practices (CIS etc)

4 - Schema Updates

Any changes type changes effecting one of the schemas in src/pkg/common/schemas should be reflected in the relevant types.go file and vice versa. This will ensure that the schema is kept in sync with the Go type definitions.

5 - Testing

Execution

There are multiple layers of tests that can be run in isolation or collectively as a whole.

• make test will execute the full suite of tests
  • This requires an environment with kind available
• make test-e2e will execute the end-to-end tests for CLI and Kubernetes testing
  • This requires an environment with kind available
• make test-cmd tests the CLI tests
  • Does not require additional infrastructure
• make test-unit runs the unit tests
  • Does not require additional infrastructure

Test Data

Testing artifacts are stored in relation to the tests being run or centralized for access across multiple tests. All .golden files are generated with go test <path> -update and should not be modified manually.

Console Testing

The Lula Console is a text-based terminal user interface that allows users to interact with the OSCAL documents and is written using the Bubble Tea library.

To test the Lula Console, we’ve implemented teatest, which allows us to generate “golden” snapshots of the console output, then ensure the test results match that expected output.

Usage

To update the golden snapshot for the Lula Console, run the following command:

go test ./src/internal/tui/model_test.go -update 

This will update the golden snapshot files in the testdata directory.

6 - Triage

Using the Triage Label for Effective Issue Tracking

Overview

In our efforts to streamline the management and resolution of issues, we introduce the use of the triage label. This label is an integral part of our issue tracking system, aimed at improving the efficiency and effectiveness with which we handle reported issues, feature requests, and other tasks within our projects.

Purpose of the Triage Label

The triage label serves several key purposes:

• Prioritization: It helps in quickly identifying new issues that need to be assessed for their urgency and impact. This initial sorting ensures that critical issues are addressed promptly.
• Clarity: Applying the triage label to new issues clarifies that they are awaiting review. It prevents duplication of work and ensures that every issue is considered by the appropriate team members.
• Efficiency: By categorizing issues into different priorities and types during the triage process, we can allocate our resources more effectively, focusing on what matters most.
• Tracking: The triage process allows us to better track the progress of issues from their inception through to resolution, offering clear visibility into the status and handling of every report.

Process

1. Applying the Triage Label:

   • All newly created issues should automatically receive the triage label. If not, team members are encouraged to manually apply the label when they encounter an unlabelled new issue.

2. Label Adjustment:

   • Following the triage by a dev, the triage label will be replaced or supplemented with additional labels reflecting the issue’s priority, type (bug, feature request, etc.), and the assigned owner, team, or appropriate category.

3. Issue Resolution:

   • As work progresses, the assigned individuals will update the issue with their findings, solutions, and any other relevant labels until the issue is resolved.

Best Practices

• Prompt Labeling: Ensure all new issues are promptly labeled with triage to avoid delays in their review and handling.
• Clear Communication: Use the issue comments to provide clear and concise updates, including any changes in priority or additional labels added post-triage.

Conclusion

The triage label is a cornerstone of our issue tracking system, designed to enhance our team’s ability to manage issues efficiently and effectively. By following this process, we can ensure that all issues receive the attention they need, resources are allocated optimally, and our projects move forward smoothly.