diff --git a/README.md b/README.md index 0cf5ce2..a67c327 100644 --- a/README.md +++ b/README.md @@ -4,71 +4,64 @@ OSCAL Custom Profiles for testing with FedRAMP REV5 HIGH baseline profile. > WARNING: Cloud Service Model derived profiles are experimental and have not been validated. -## Directory Structure - -### Content Managed by Automation - -Some the directories in this repository are managed through automated processes such as make targets or GitHub Actions. - -- catalogs: This stores OSCAL Catalogs installed in the trestle workspace. -- profiles (FedRAMP only) - This stores OSCAL Profiles installed in the trestle workspace. - - -For information on how this data is managed, see the [FAQs](./docs/faqs.md). - -### Content Managed by Control Owner (i.e. managed directly in this repository) -- markdown - This stores profile information that can be edited directly. -- profiles - This stores custom OSCAL Profile JSON installed in the trestle workspace. -- scripts - This stores bash scripts for automation tasks unique to this repository. - -## Workflow - -The below diagram depict the event-driven pull-based strategy used to update the content in this repository. - -```mermaid -graph LR - subgraph Trestle_Workspace - Catalogs(Catalogs) - Profiles(Profiles) - Upstream_Profiles(Upstream Profiles) - end - subgraph External Sources - Official_Catalogs_Profiles(Official OSCAL Catalogs and Profiles) - end - subgraph GitHub Actions - Catalog_Profile_Import(Catalog/Profile Import) - subgraph Trestle Bot - Commit(Commit) - Create_Pull_Request(Create Pull Request) - Sync_Profiles(Sync Profiles with Catalogs) - Sync_Profiles_P(Sync Profiles with Upstream Profiles) - end - end - subgraph Review and Approval - Pull_Request(Pull Request) - end - Person(Person) - - Official_Catalogs_Profiles --> Catalog_Profile_Import - Catalog_Profile_Import --> A{Content Updates?} - A -- Yes --> Commit - Commit --> Create_Pull_Request - Create_Pull_Request --> Person - A -- No --> B[End] - Sync_Profiles -- Catalog Content --> A - Sync_Profiles_P -- Profile Content --> A - Pull_Request -- Merge --> Catalogs - Pull_Request -- Merge --> Profiles - Pull_Request -- Merge --> Upstream_Profiles - Catalogs -- Workflow Dispatched --> Sync_Profiles - Upstream_Profiles -- Workflow Dispatched --> Sync_Profiles_P - Person -- Review --> Pull_Request - Person -- Approve --> Pull_Request - Profiles --> B -``` - -### Current Limitations: - -- Catalogs and profiles currently have to be synced by manually executing a GitHub Action workflow. - -To complete work from a fork, local automation is available. To see the available make targets, use `make help`. For information on how to edit the content in this repository, see the [tutorial](./docs/tutorial.md). +## Getting Started + +### Update Existing Content +#### Overview +The workflow to update content consists of the following steps: + +1. From a user's branch, modify and commit a markdown or json file within the workspace. (Most updates will be made to markdown files.) +2. A user submits a pull request to add their changes to the workspace's master branch. +3. From a user's branch, trestle-bot synchronizes the workspace content, validates it, and formats it. +4. The workspace updates are conditionally added to the workspace's main branch. + + +#### Step 1: Create and switch to a new branch +The first step in modifying content is to [create a new branch](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository) of the workspace to save your work to. + +#### Step 2: Locate content + Once you've created a branch, locate the content to be modified within the workspace. JSON and markdown files can be found in the following places: +- `./markdown/profiles/` +- `./profiles/` + + +#### Step 3: Modify content +Browse to the referenced file. Follow your Git Provider's instructions for committing changes to a file. +- [GitHub](https://docs.github.com/en/github/managing-files-in-a-repository/editing-files-in-your-repository) + + +#### Step 4: Open A pull request +Once the needed modifications have been performed, request to publish the changes by opening a pull request to merge your changes into the workspace's main branch. + +- [GitHub](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) + + +#### Step 5: Approve and merge pull request +Once trestle-bot has processed the workspace modifications, the pull request can be conditionally approved, which triggers the publishing of the changes to the workspace's main branch. + +- [GitHub](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/approving-a-pull-request-with-required-reviews) + + +### Creating new content +#### Overview +The workflow to create a new Profile consists of the following steps: + +1. Using the GitHub UI, complete a create new profile form and submit it to trestle-bot. +2. trestle-bot processes the form and creates a new profile within the workspace. +3. trestle-bot opens a pull request to add the new profile to the workspace's main branch. +4. The workspace updates are conditionally added to the workspace's main branch. + + +#### Step 1: Kickoff a workflow +Use your git provider's UI to kickoff a workflow, by browsing to the workspace's available workflows and selecting the `Profile Create` workflow. Enter the required information and submit the form to run the workflow. +[GitHub](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow#running-a-workflow) + + +#### Step 2: Approve and merge pull request +Once trestle-bot has processed the workspace modifications, the pull request can be conditionally approved, which triggers the publishing of the changes to the workspace's main branch. + +- [GitHub](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/approving-a-pull-request-with-required-reviews) + +## FAQs and Infrequent Tasks + +See [FAQs and Infrequent Tasks](./docs/faqs.md) for more information. diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 0000000..9732c85 --- /dev/null +++ b/docs/design.md @@ -0,0 +1,41 @@ +# Design + +In the repository, GitHub Actions is used to manage the trestle workspace. This document describes the purpose and design of each workflow. + +## Workflows + +#### Create + +Associated Workflows +- [create-new.yml](../.github/workflows/create-new.yml) + +The `create-new` workflow is triggered manually by going to the Action tab. This creates a new OSCAL profile in the trestle workspace. A new branch is created and a pull request is opened. + +#### AutoFix + +Associated Workflows +- [autofix-profile.yml](../.github/workflows/autofix-profile.yml) +- [manual-autofix.yml](../.github/workflows/manual-autofix.yml) +- [validate.yml](../.github/workflows/validate.yml) + +The `validate` workflow is triggered when a pull request is created or updated with updates to component definitions. It validates the trestle workspace and automatically sync any difference between the OSCAL JSON files and trestle managed Markdown files. The same workflow can be triggered through the Action tab using the `Run autofix adhoc` workflow. The `autofix-profile.yml` has all common logic for both workflows. The `validate.yml` and `manual-autofix.yml` workflows adds customer triggers and logic. + +The `validate` workflow will run checks with read-only permissions when a pull request is opened from a from a fork, but the autofix workflow will not run. + +#### Update Profile + +Associated Workflows +- [update-upstream.yml](../.github/workflows/update-upstream.yml) + +The `update-uptream` workflow is triggered manually to pull in updated profile and catalog information from upstream sources. This will update the profile information in the trestle workspace and open a pull request. + +#### Release + +Associated Workflows +- [dispatch.yml](../.github/workflows/dispatch.yml) +- [release.yml](../.github/workflows/release.yml) + + +The `release` workflow is triggered manually to assign a release version to the profiles in the repository. The artifacts are synced, version and changes are push back to the branch. An associated tag for the release is created and a GitHub release is created. Once, the release is publish, the `dispatch` workflow is triggered to notfiy downstream repositories. + + diff --git a/docs/tutorial.md b/docs/tutorial.md deleted file mode 100644 index 3acc448..0000000 --- a/docs/tutorial.md +++ /dev/null @@ -1,37 +0,0 @@ -# Tutorial - -OSCAL Profiles can be used to add control guidance and use controls from one or more catalogs or profiles to create a tailored subset of controls for a specific use-case. In this example, the profiles is using a tailored subset of the FedRAMP Rev5 High profile. - -To make changes to the ACME custom profile, checkout a new branch. - -```bash -git checkout -b "feat/adds-custom-guidance" -``` - -To add additional guidance to an existing control, add information under a "## Control" heading to the end of the `ac-2.md` file. - -```bash -cat << EOF >> ./markdown/profiles/example/ac/ac-2.md - -## Control additional_process_guidance - -Accounts must be documented in Markdown. -EOF -``` - -Run the `assemble-profiles` command to ensure that the Markdown changes are reflected in the OSCAL profile. - -```bash -make assemble-profiles -``` - -When you run `git status` , you should see three file changes. Two in the `markdown/profiles` directory, the other in the `profiles` directory. - -Using the GitHub CLI, you can now commit the changes to the branch and create a pull request. You can also use the [GitHub UI](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) to create a pull request. - -```bash -git add markdown/ profiles/ -git commit -m "feat: adds-custom-guidance" -git push -u origin "feat/adds-custom-guidance" -gh pr create -t "feat/adds-custom-guidance" -b "Adds guidance to control in custom profile" -B "main" -H "feat/adds-custom-guidance" -``` \ No newline at end of file