Merge branch 'main' into docs/adr-001-cli-framework

.github/actions/setup-poetry/action.yml

@@ -30,5 +30,5 @@ runs:
       shell: bash
 
     - name: Install dependencies
-      run: poetry install --no-interaction --no-root
+      run: poetry install --with tests,dev --no-interaction --no-root
       shell: bash

.github/workflows/scorecard.yml

@@ -0,0 +1,49 @@
+name: Scorecard analysis workflow
+on:
+  push:
+    # Only the default branch is supported.
+    branches:
+    - main
+  schedule:
+    # Weekly on Saturdays.
+    - cron:  '30 1 * * 6'
+
+permissions: read-all
+
+jobs:
+  analysis:
+    if: github.repository == 'RedHatProductSecurity/trestle-bot'
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      # Needed for Code scanning upload
+      security-events: write
+      # Needed for GitHub OIDC token if publish_results is true
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # pin@v4
+        with:
+          persist-credentials: false
+
+      - name: Run analysis
+        uses: ossf/scorecard-action@62b2cac7ed8198b15735ed49ab1e5cf35480ba46 # v2.4.0
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@0b2256b8c012f0828dc542b3febcab082c67f72b # pin@v4
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      # Upload the results to GitHub's code scanning dashboard (optional).
+      # Commenting out will disable upload of results to your repo's Code Scanning dashboard
+      - name: Upload to code-scanning
+        uses: github/codeql-action/upload-sarif@461ef6c76dfe95d5c364de2f431ddbd31a417628 # v3.26.9
+        with:
+          sarif_file: results.sarif

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "0.10.1"
+    ".": "0.11.0"
 }

CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## [0.11.0](https://github.com/RedHatProductSecurity/trestle-bot/compare/v0.10.1...v0.11.0) (2024-09-25)
+
+
+### ⚠ BREAKING CHANGES
+
+* default module entrypoint is now the init command
+* Modifies the existing behavior of the rules transform entrypoint
+
+### Features
+
+* adding init command to entrypoints ([#326](https://github.com/RedHatProductSecurity/trestle-bot/issues/326)) ([868c1fa](https://github.com/RedHatProductSecurity/trestle-bot/commit/868c1fae3bb2fa85df734905aa38b33dc37c9b47))
+* adds markdown generation to the rules transform entrypoint ([#282](https://github.com/RedHatProductSecurity/trestle-bot/issues/282)) ([84dec70](https://github.com/RedHatProductSecurity/trestle-bot/commit/84dec70d7810abf7306b708104b4c7bf682a49ad))
+* removes provider from init and moves CI templates ([#344](https://github.com/RedHatProductSecurity/trestle-bot/issues/344)) ([21b4043](https://github.com/RedHatProductSecurity/trestle-bot/commit/21b40432f446323ded883c248feaa064ea1cabd6))
+* tutorial for GitHub and init command ([#333](https://github.com/RedHatProductSecurity/trestle-bot/issues/333)) ([6334c1f](https://github.com/RedHatProductSecurity/trestle-bot/commit/6334c1f16fffa94bacbb250c95f754ed80abff9b))
+* update module default to use init entrypoint ([#329](https://github.com/RedHatProductSecurity/trestle-bot/issues/329)) ([d1490cb](https://github.com/RedHatProductSecurity/trestle-bot/commit/d1490cbde72b204875260cd210f61760e9f3c056))
+* updates SSP generation to include all parts ([#348](https://github.com/RedHatProductSecurity/trestle-bot/issues/348)) ([18c6600](https://github.com/RedHatProductSecurity/trestle-bot/commit/18c6600a47d9833811a045fa60e167608f06a180))
+
+
+### Bug Fixes
+
+* add markdown-include package to workflow and poetry ([#339](https://github.com/RedHatProductSecurity/trestle-bot/issues/339)) ([c7a05ee](https://github.com/RedHatProductSecurity/trestle-bot/commit/c7a05eebe87f853a435b31abadba8db05d2458a2))
+* updates dependabot prefix for conventional commits ([#308](https://github.com/RedHatProductSecurity/trestle-bot/issues/308)) ([ee86f5c](https://github.com/RedHatProductSecurity/trestle-bot/commit/ee86f5c35755686d3fc3adf6ca94e1c4ac8d873e))
+* updates e2e tests checkout ref during image publishing ([#334](https://github.com/RedHatProductSecurity/trestle-bot/issues/334)) ([5439b91](https://github.com/RedHatProductSecurity/trestle-bot/commit/5439b91c7b0ed1d75c7a5ec3f2b3f4e94ea5968a))
+
+
+### Maintenance
+
+* change dependabot frequency to weekly ([#290](https://github.com/RedHatProductSecurity/trestle-bot/issues/290)) ([3da37f7](https://github.com/RedHatProductSecurity/trestle-bot/commit/3da37f7b69538e157b5b48b461140d0f9bfd6d9d))
+* **deps:** adds compliance-trestle-fedramp dependency ([#349](https://github.com/RedHatProductSecurity/trestle-bot/issues/349)) ([aeb6e0c](https://github.com/RedHatProductSecurity/trestle-bot/commit/aeb6e0c59bb0e09ee2142f886e9682a8f8e118e6)), closes [#318](https://github.com/RedHatProductSecurity/trestle-bot/issues/318)
+* **deps:** bump trestle to version v3.3.0 ([#269](https://github.com/RedHatProductSecurity/trestle-bot/issues/269)) ([a2a2db6](https://github.com/RedHatProductSecurity/trestle-bot/commit/a2a2db6bbbcac2bec23b9fe520a0958afc488616))

CONTRIBUTING.md

@@ -18,6 +18,7 @@ Before you start contributing, please take a moment to read through the guide be
     - [Documentation](#documentation)
       - [Architecture Decisions](#architecture-decisions)
       - [Update the `actions` files](#update-the-actions-files)
+      - [Authoring CI Workflows](#authoring-ci-workflows)
     - [License Text in Files](#license-text-in-files)
     - [Tools](#tools)
       - [Format and Styling](#format-and-styling)
@@ -97,7 +98,18 @@ Each `README.md` under the `actions` directory have an Actions Inputs and Action
 make update-action-readmes
 ```
 
-### License Text in Files
+#### Authoring CI Workflows
+
+The CI workflows for trestle-bot leverage third party actions pinned to a hash value which is updated by `dependabot.yml`. The purpose of pinning actions to a full length commit SHA is to ensure that the action's code and behavior remain consistent. Actions that are pinned to full length commit SHAs act as immutable releases which allow for distinction between versions and an accurate history log. When selecting a commit SHA to include, the SHA value that is associated with the version of the action should be chosen from the associated action's repository. Dependabot checks for the action's reference against the latest version ensuring a secure and consistent approach to managing dependencies and version updating.
+
+To generate a pin for a third party action, there should be a full length commit SHA associated with the version of the action being referenced. The reference used is the full length SHA, tag, or branch that dependabot will use when updating dependencies and bumping versions.
+
+- The syntax for a specified action is: `OWNER/REPOSITORY@TAG-OR-SHA`.
+- The syntax for a specified reusable workflow is: `OWNER/REPOSITORY/PATH/FILENAME@TAG-OR-SHA`.
+
+This approach is used for authoring CI workflows that utilize versioned actions to produce frequent updates from dependabot for python and GitHub Actions.
+
+### License Text in Files 
 
 Please use the SPDX license identifier in all source files.
 

Dockerfile

@@ -24,6 +24,7 @@ RUN microdnf update -y \
 FROM python-base AS dependencies
 
 ARG POETRY_VERSION=1.7.1
+ARG INSTALL_PLUGINS=true
 
 # https://python-poetry.org/docs/configuration/#using-environment-variables
 ENV POETRY_VIRTUALENVS_IN_PROJECT=true \
@@ -39,14 +40,20 @@ COPY . "/build"
 # Install runtime deps and install the project in non-editable mode.
 # Ensure pip and setuptools are updated in the virtualenv as well.
 RUN python3.9 -m venv "$VENV_PATH" && \
+    . "$VENV_PATH"/bin/activate && \
+    python3.9 -m pip install --no-cache-dir --upgrade pip setuptools && \
+    if [ "$INSTALL_PLUGINS" == "true" ]; then \
+      poetry install --with plugins --no-root; \
+    else \
+      poetry install --no-root; \
+    fi
+
+RUN  python3.9 -m venv "$VENV_PATH" && \
   . "$VENV_PATH"/bin/activate && \
-  python3.9 -m pip install --no-cache-dir --upgrade pip setuptools && \
-  poetry install --without tests,dev --no-root && \
   poetry build -f wheel -n && \
   pip install --no-cache-dir --no-deps dist/*.whl && \
   rm -rf dist ./*.egg-info
 
-
 FROM python-base AS final
 
 COPY --from=dependencies $PYSETUP_PATH $PYSETUP_PATH

Makefile

@@ -6,7 +6,7 @@ all: develop lint test
 .PHONY: all
 
 develop: pre-commit
-	@poetry install
+	@poetry install --with tests,dev
 	@poetry shell
 .PHONY: develop
 

TEMPLATES/README.md

@@ -0,0 +1,8 @@
+# Templates
+
+
+This directory contains workflow templates using `trestle-bot` to facilitate an editing workflow for different OSCAL models and integration with CI/CD providers.
+
+`trestle-bot` provides a ready-made integrations for GitLab CI/CD and GitHub Actions though it can be used in multiple contexts using additional flags.
+
+> Adding GitLab CI/CD workflows is on the ROADMAP

trestlebot/entrypoints/templates/github/trestlebot-autosync-catalog.yml → TEMPLATES/github/trestlebot-autosync-catalog.yml

@@ -9,6 +9,10 @@ on:
       - 'catalogs/**'
       - 'markdown/catalogs/**'
 
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
 jobs:
   autosync:
     name: Autosync catalog content

trestlebot/entrypoints/templates/github/trestlebot-autosync-profile.yml → TEMPLATES/github/trestlebot-autosync-profile.yml

@@ -9,6 +9,10 @@ on:
       - 'profiles/**'
       - 'markdown/profiles/**'
 
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
 jobs:
   autosync:
     name: Autosync profile content

TEMPLATES/github/trestlebot-autosync-ssp.yml

@@ -0,0 +1,32 @@
+name: Trestle-bot autosync ssp updates
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'profiles/**'
+      - 'catalogs/**'
+      - 'component-definitions/**'
+      - 'system-security-plans/**'
+      - 'markdown/**'
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  autosync:
+    name: Autosync ssp content
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Run autosync
+        id: autosync
+        uses: RedHatProductSecurity/trestle-bot/actions/autosync@main
+        with:
+          markdown_path: "markdown/system-security-plans"
+          oscal_model: "ssp"
+          file_pattern: "*.json,markdown/*"

trestlebot/entrypoints/templates/github/trestlebot-create-component-definition.yml → TEMPLATES/github/trestlebot-create-component-definition.yml

@@ -40,7 +40,7 @@ jobs:
           component_title: ${{ github.event.inputs.component_title }}
           component_type: ${{ github.event.inputs.component_type }}
           component_description: ${{ github.event.inputs.component_description }}
-          markdown_path: "markdown/components"
+          markdown_path: "markdown/component-definitions"
           branch: "create-component-definition-${{ github.run_id }}"
           target_branch: "main"
           file_pattern: "*.json,markdown/*,rules/*"

trestlebot/entrypoints/templates/github/trestlebot-rules-transform.yml → TEMPLATES/github/trestlebot-rules-transform.yml

@@ -17,29 +17,37 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  check_rules:
+    runs-on: ubuntu-latest
+    outputs:
+      rules_changed: ${{ steps.changes.outputs.rules }}
+    steps:
+    - uses: actions/checkout@v4
+    - uses: dorny/paths-filter@v3
+      id: changes
+      with:
+        filters: |
+          rules:
+            - 'rules/**'
   rules-transform-and-autosync:
     name: Rules Transform and AutoSync
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    needs: check_rules
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
       - name: AutoSync
         id: autosync
         uses: RedHatProductSecurity/trestle-bot/actions/autosync@main
         with:
-          markdown_path: "markdown/components"
+          markdown_path: "markdown/component-definitions"
           oscal_model: "compdef"
-          file_pattern: "*.json,markdown/*"
-      - name: Check if rules changed
-        id: changes
-        uses: dorny/paths-filter@v3
-        with:
-          filters: |
-            rules:
-              - 'rules/**'
-      - name: Rules Tranform
-        if: steps.changes.outputs.rules == 'true'
+          commit_message: "Autosync component definition content [skip ci]"
+      - name: Rules Transform
+        if: needs.check_rules.outputs.rules_changed == 'true'
         uses: RedHatProductSecurity/trestle-bot/actions/rules-transform@main
         with:
-          markdown_path: "markdown"
+          markdown_path: "markdown/component-definitions"
           commit_message: "Auto-transform rules [skip ci]"

docs/tutorials/authoring.md

@@ -0,0 +1,57 @@
+# Authoring Tutorial
+
+This tutorial provides an overview of the authoring process using `trestlebot`.  We will use the component definition created in the [GitHub tutorial](https://redhatproductsecurity.github.io/trestle-bot/tutorials/github/) as our starting point.  This tutorial will demonstrate the workflow for updating Markdown content and syncing those changes to OSCAL.
+
+## 1. Prerequisites
+
+- Complete the [GitHub tutorial](https://redhatproductsecurity.github.io/trestle-bot/tutorials/github/)
+
+
+## 2. Edit in Markdown
+
+We will begin where we left off at the end of the [GitHub tutorial](https://redhatproductsecurity.github.io/trestle-bot/tutorials/github/).  Our repository has a newly created component definition named `my-first-compdef` with corresponding content in the `markdown/` and `component-definitions/` directories.  We will now demonstrate how to author changes in Markdown and produce updated OSCAL content.
+
+1. Navigate to the `markdown/component-definitions/my-first-compdef/test-component/nist_rev5_800_53/ac` directory and select the `ac-1.md` file.
+2. Click the `Edit this file` (pencil) icon.
+3. Scroll down to the section titled `## What is the solution and how is it implemented?` and add a new line of text with a brief comment.  For example:
+
+```
+## What is the solution and how is it implemented?
+
+Here is where details should be added by the author.
+```
+
+4. Click the `Commit changes..` button
+5. Select the `Create a new branch for this commit and start a pull request` radio button
+6. Click `Propose changes`
+
+
+The `Open a pull request` page now opens.  Enter any additional details about your changes into the description box.
+
+7. Click `Create pull request`
+8. For demo purposes, we will go ahead and merge the pull request ourselves.  In a production setting the pull request process should be used for review, discussion and approval of the proposed changes.  Click `Merge pull request` and then `Confirm merge`.
+
+
+## Autosync
+
+Once the pull request has been merged the `Trestle-bot rules-transform and autosync` GitHub action will be triggered. We will now validate that action was successful.
+
+1. Navigate to the `Actions` tab of your GitHub repository.
+2. The top entry in the list of workflow runs should be titled `Merge pull request #<your PR number> from <your repo/your branch>`.  This action should be either running or have just successfully completed.
+3. [Optional] Clicking this entry will allow you to view the detailed steps and log output.
+4. Once the action is completed successfully, navigate back to the source code by clicking the `Code` tab of the repo.
+5. Click the `component-definitions` folder and navigate to `my-first-compdef/component-definition.json`.
+5. The `Last commit date` should align with the time the action completed.
+6. Click the `component-definitions.json` file and then click the `History` icon to view the commit history.
+7. Ensure the latest commit performed by the GitHub action reflects the changes made in Markdown as shown below:
+
+```
+    "description": "",
+    "description": "Here is where details should be added by the author",
+```
+
+You will also notice the `"last-modified"` timestamp has been updated.
+
+
+Congrats!  You've successfully authored a change by modifying a Markdown file and letting trestle-bot sync those changes back to the OSCAL content.
+