Patching release 1.1.1

.github/CODEOWNERS

@@ -1,12 +1,8 @@
-# directory specific owners
-/.github/               @usnistgov/itl-oscal-maintainers
-/build/                 @usnistgov/itl-oscal-maintainers
-/content/               @aj-stein-nist
-/docs/                  @aj-stein-nist
-/docs/content           @aj-stein-nist @iMichaela
-/json/                  
-/xml/                   
-/src/                   @usnistgov/itl-oscal-maintainers
-/src/metaschema         @aj-stein-nist
-/src/specifications/profile-resolution  @david-waltermire-nist @wendellpiez
-/src/utils              @wendellpiez
+# The OSCAL Admins team governs critical directories
+.github/workflows/      @usnistgov/itl-oscal-admins
+build/Makefile          @usnistgov/itl-oscal-admins
+# The OSCAL Maintainers team governs source and build directories
+src/                    @usnistgov/itl-oscal-maintainers
+build/                  @usnistgov/itl-oscal-maintainers
+# Otherwise governed by the OSCAL Team
+*                       @usnistgov/itl-oscal

.github/workflows/issue-triage.yml

@@ -4,24 +4,15 @@ on:
   issues:
     types:
       - opened
-      - closed
+      - reopened
+      - transferred
+
 jobs:
-  createCard:
-    runs-on: ubuntu-20.04
-    if: github.event.action == 'opened'
-    steps:
-      - name: Add New Issues to Issue Triage Board
-        uses: peter-evans/create-or-update-project-card@5eacbbd224b7814354861b555cc18a8359e2cebe
-        with:
-          project-name: Issue Triage
-          column-name: Needs Triage
-  removeCard:
+  add-to-project:
+    name: Add issue to project
     runs-on: ubuntu-20.04
-    if: github.event.action == 'closed'
     steps:
-      - uses: alex-page/github-project-automation-plus@7ffb872c64bd809d23563a130a0a97d01dfa8f43
+      - uses: actions/add-to-project@31b3f3ccdc584546fc445612dec3f38ff5edb41c
         with:
-          project: Issue Triage
-          column: Done
-          action: delete
-          repo-token: ${{ secrets.COMMIT_TOKEN }}
+          project-url: https://github.com/orgs/usnistgov/projects/25
+          github-token: ${{ secrets.COMMIT_TOKEN }}

.github/workflows/periodic.yml

@@ -12,10 +12,10 @@ jobs:
       # Needed to post comments and issues
       issues: write
     steps:
-      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
         with:
           submodules: recursive
-      - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d
+      - uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65
         with:
           node-version-file: "build/.nvmrc"
           cache: "npm"
@@ -26,7 +26,7 @@ jobs:
         working-directory: build
       - name: Create an issue or comment if bad links are detected
         if: failure()
-        uses: actions/github-script@d7906e4ad0b1822421a7e6a35d5ca353c962f410
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea
         with:
           script: |
             // Read the markdown linkcheck report

.github/workflows/release.yml

@@ -8,10 +8,10 @@ jobs:
     name: Package Release
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
         with:
           submodules: recursive
-      - uses: actions/setup-java@v3
+      - uses: actions/setup-java@v4
         with:
           distribution: "temurin"
           java-version: "17"

.github/workflows/status.yml

@@ -18,14 +18,14 @@ jobs:
     name: Status Checks
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
         with:
           submodules: recursive
-      - uses: actions/setup-java@v3
+      - uses: actions/setup-java@v4
         with:
           distribution: "temurin"
           java-version: "17"
-      - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d
+      - uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65
         with:
           node-version-file: "build/.nvmrc"
           cache: "npm"

build/markdown-link-check.json

@@ -8,7 +8,10 @@
         },
         {
             "pattern": "https://help.github.com"
-        }
+        },
+        {
+            "pattern": "https://linux.die.net/man/1/xmllint/"
+        }        
     ],
     "replacementPatterns": [
         {
@@ -28,4 +31,4 @@
             "replacement": "https://github.com/usnistgov/OSCAL/tree"
         }
     ]
-}
+}

build/pom.xml

@@ -48,7 +48,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-dependency-plugin</artifactId>
-                <version>3.6.0</version>
+                <version>3.6.1</version>
                 <executions>
                     <execution>
                         <id>copy-dependencies</id>

decisions/0007-implementation-agnostic-tests.md

@@ -0,0 +1,80 @@
+# Implementation-agnostic Testing and Test Harness
+
+Date: 10/06/2023
+
+## Status
+
+Proposed
+
+## Context
+
+In order to support the development of OSCAL tooling, it was decided prototype a unified tool responsible for validating OSCAL implementations against specification requirements.
+
+Currently, only profile resolution has been [formalized into a draft specification](../src/specifications/profile-resolution/profile-resolution-specml.xml).
+
+### Existing Infrastructure
+
+The profile resolver specification currently leverages an in-house XML format known as SpecML, which breaks down a specification into a collection of **sections**, which contain in turn a collection of **requirements**.
+Each `<section/>` and `<requirement/>` has a unique `@id` attribute.
+
+The sections and requirements are mirrored in the XSLT implementation's profile resolution unit tests.
+Although crucial to the XSLT implementation, these tests are not portable and it would not be simple to use the tests in their current state to validate other implementations.
+
+### Specification Tests
+
+Some specifications such as [CommonMark](https://commonmark.org/) include a [test suite and testing harness](https://github.com/commonmark/commonmark-spec/tree/master/test) to make it possible for implementors to "score" their implementation's conformance to the specification.
+
+## Decision
+
+### SpecML
+
+The specification format will remain unchanged for now.
+There is an argument for the format to be replaced or simplified in the future, but the use of `@id` attributes for sections and requirements make linking a test to a example simple.
+
+### Test Suite Data Format
+
+The test suite will be described using a JSON file with a simple data format.
+
+This file will contain a collection of objects that map to a given spec requirement via `section_id` and `requirement_id` fields.
+These objects will further contain a collection of "scenario" objects, each of which containing a `description`, `source_profile_path`, `expected_catalog_path`, and a collection of `selection_expressions`.
+
+For a given scenario, a test runner would be expected to perform profile resolution with the `source_profile_path` and compare selections of the resulting document with the `expected_catalog_path`.
+The `selection_expressions` are XPath expressions, though the [test harness](#test-harness) may further constrain the XPath expression's capabilities.
+
+Here is an example test suite made up of one requirement:
+
+```json
+[
+    {
+        "section_id": "import",
+        "requirement_id": "req-uri-resolve",
+        "scenarios": [
+            {
+                "description": "Check that group and control titles match, signalling that URIs have been resolved",
+                "source_profile_path": "requirement-tests/req-include-all-asis.xml",
+                "expected_catalog_path": "requirement-tests/output-expected/req-include-all-asis_RESOLVED.xml",
+                "selection_expressions": [
+                    "./oscal:group/oscal:title",
+                    "./oscal:group/oscal:control/oscal:title"
+                ]
+            }
+        ]
+    }
+]
+```
+
+The development of a JSON schema for this format is left as future work.
+
+### Test Harness
+
+A prototype testing harness has been developed, with the capability to report a given profile resolver's compliance to a specification given a [test suite JSON file](#test-suite-data-format).
+
+The prototype harness is built to be as simple as possible, avoiding external libraries.
+Python's native XPath capabilities are limited, further constraining the capabilities of the test suite.
+
+## Consequences
+
+Writing specification tests for profile resolution will require significant resources, but will make profile resolution more approachable for implementors and will make changes to the specification more maintainable.
+
+Due to the "requirement based" approach of the specification test suite, new tests can be added gradually.
+Test coverage can be determined by determining which requirements do not have tests.

decisions/0008-oscal-content-management.md

@@ -0,0 +1,65 @@
+# OSCAL Content Data Governance and Release Management
+
+Date: 11/09/2023
+
+## Status
+
+Approved
+
+## Context
+
+Since 2016, the OSCAL project has iterated on methods and locations for managing example content and published catalogs. It is time that we decide whether to continue as-is or make a meaningful change to how project's OSCAL content is developed, published, and maintained.
+
+### Key Takeaways
+
+1. Almost all changes to OSCAL representations of the published SP 800-53A and 800-53B catalogs do not diverge from the official publication. Clear data management and governance guidelines are needed to identify which changes are acceptable OSCAL Team leadership to approve for release, and which specific changes need review and approval by the Security Engineering and Risk Management maintainers of the official SP 800-53 content.
+1. By the nature of OSCAL models and relationships of document instances, the team must continue to manage published catalogs and examples that cite them together.
+1. It is important that final integration testing of all OSCAL content occur with the latest pending release of OSCAL as a final integration test, even if the content is backwards compatible with an older minor or patch release for the same version.
+
+### Background
+
+[In September 2020](https://github.com/usnistgov/OSCAL/commit/01c0aa9b45667b25e8105160119da011471c77cb), the NIST OSCAL Team migrated SP 800-53 Revision 4, SP 800-53 Revision 5, and example content from [the core OSCAL repository](https://github.com/usnistgov/OSCAL) to the [new oscal-content repository](https://github.com/usnistgov/oscal-content). Presumably, this migration allowed the development team to manage published catalog content, and to a lesser extent examples, in a more flexible way, independent from the established release process and practices for the core OSCAL models, schemas, and supporting tooling. (However, even by that time examples reflected the real-world cross-document relationships OSCAL models support. Examples inherently reference adjacent published catalogs of the NIST SP 800-53B controls.) The NIST OSCAL Team coordinated with the [Security Engineering and Risk Management Team](https://csrc.nist.gov/Groups/Computer-Security-Division/Security-Engineering-and-Risk-Management), maintainers of NIST SP 800-53A and SP 800-53B, to publish representations of the assessment methods and respective controls in conjunction with their official publication (in PDF and alternate formats). Team members employed semi-automatic techniques for content-generation and data quality checks to coordinate finalized release of the 5.0 and 5.1 versions of the official documents with the OSCAL representation (e.g. releasing to the `main` branch in the GitHub repository). Their publication schedule is more infrequent than the OSCAL development cycle. This is an important takeaway that lead to data governance, testing, and release challenges.
+
+### Data Management and Governance Challenges
+
+As enhancements and bug fixes for OSCAL increased, separate of the content, in between official upstream releases of SP 800-53A and SP 800-53B, staff and community members [identified bugs and enhancements to the OSCAL representations](https://github.com/usnistgov/oscal-content/issues). In most cases, these work items would not or did not diverge from the content in the official publication version. These data quality and OSCAL-specific enhancements would or did improve the ability of technical staff using the OSCAL representation to create or improve catalog and profile automation. There has been no clear guidance on how to accept these changes, publish them, and how to identify their versions upon release. These governance questions led to an accumulation of work items that delayed publication (at this time, read: merged into the `main` branch).
+
+### OSCAL Dependency Upgrades, Integration, and Regression Test Challenges
+
+Due to infrequent publications of the catalogs, managed together with examples, the OSCAL submodule to provide models, generated schema, and tooling support. At the time of writing this ADR draft, [the oscal-content main branch at `a53f261`](https://github.com/usnistgov/oscal-content/tree/a53f261a946c52811c507deb4d8385d9e4794a6f) uses a version of the OSCAL models and tooling that is ostensibly from December 2022, [`51d5de2`](https://github.com/usnistgov/OSCAL/commit/51d5de22c181477e3f9cf08789c4399fff013f14), a stable commit between v1.0.4 and v1.0.5. Several attempts to smoothly upgrade this with subsequent releases of OSCAL models and supporting tooling were rolled back or never completed. Automated content conversion and schema validation failed. The team confirmed bugs in dependencies to OSCAL. Fixing these issues required months of development work. Below is a non-exhaustive list with two examples.
+
+- [usnistgov/metaschema#235](https://github.com/usnistgov/metaschema/issues/235)
+- [usnistgov/metaschema#240](https://github.com/usnistgov/metaschema/issues/240)
+
+These bugs, and those like them, impacted conversion and validation of the examples, the published catalogs, or in some cases both. So in all cases, they stopped final publication into the oscal-content `main` branch, even as new OSCAL models were released. Specifically, fixing issues in an implementation of the Metaschema Information Modeling Framework used by OSCAL for schema generation, validation, and conversion need to not only be tested in their upstream projects, but then frequently regression tested across models with complex content present in the oscal-content repo. This manual follow-on work was a necessity to test all edge cases. It was exacerbated by the lack of frequent releases, or such problems would be caught sooner and fixed more frequently. This is a key takeaway that Metaschema and OSCAL Team's developers acknowledge, but not yet put into practice. This last line of defense is important to minimizing toil for the team.
+
+## Decision
+
+Moving forward, the team must commit to the following.
+
+1. A data management and governance procedure will be added [to the OSCAL Team Wiki](https://github.com/usnistgov/OSCAL/wiki/NIST-SP-800%E2%80%9053-OSCAL-Content-Data-Governance).
+1. The oscal-content repository will move to a `Makefile`-based approach for [usnistgov/oscal-content#116](https://github.com/usnistgov/oscal-content/issues/116) when [usnistgov/oscal-content#204](https://github.com/usnistgov/oscal-content/pull/204) is merged to match the same approach for the core repository enacted in [ADR 5](./0005-repository-reorganization.md). For consistency and simplicity of this new workflow, all examples, profiles, and catalogs will be developed in the [src directory](https://github.com/usnistgov/oscal-content/tree/7a079afed39b1a36a091c8d4ac939d096d42c76b/src) in OSCAL XML format only and converted later. This approach will simplify the architecture and improve efficiency of development cycles.
+1. Every OSCAL model release must coincide with an oscal-content release. At a minimum, even if examples or catalogs to be published do not change any content, the team must do the following.
+    - Update the OSCAL submodule to the latest tagged release.
+    - All source catalogs and profiles must have their `oscal-version` and `version` incremented. Their `last-modified` and `published` timestamps must be updated, even if the updated content in that release is backwards compatible with previous major, minor, and/or patch versions.
+    - All `xml-model` instructions at the top of every example, profile, and catalog instance must be updated to the complete OSCAL XML schema artifact for the release that matches the `oscal-version`.
+1. The team will tag the commit with generated artifacts and mimic [the core repository's versioning, branching, and release guidelines](https://github.com/usnistgov/OSCAL/blob/f159b28948cb0034370fb819a45bfdaeaef5192a/versioning-and-branching.md), following [SemVer requirements](https://semver.org/).
+1. Releases of content will be created alongside the core OSCAL repository.
+1. In ADR 5, the team cited risk with the ongoing use of auto-commit automation with GitHub Actions for core OSCAL models and generated artifacts. To evaluate the best option and allow time for coordination with the community, the team will continue with auto-committing content to `main` as a publication mechanism only for the near-term future. The team will revisit this decision and potentially propose an alternative method that is more suitable in a subsequent spike and approved ADR.
+1. OSCAL Team leadership will review resources and the feasibility of ongoing maintenance of the catalogs and alternative courses of action for long-term publication of NIST SP 800-53 Revision 5 catalogs.
+
+## Consequences
+
+Below are the consequences of the different approaches.
+
+### Do Nothing
+
+In the short-term, doing nothing would mean to stop publication of the content immediately. This solution would be detrimental to the community without effective analysis for alternative courses of action and approaches for usage of existing content.
+
+### Change Nothing
+
+If the team continues as-is by publishing content to `main` after bugs and build tooling improvements are complete, the challenges above will still sustain unnecessary risk without changes to process and tooling to support the team and its goals. Development of example content, not just publication of catalogs, will stall due to edge cases and accumulated changes in tooling that lead to many minor changes in content that must be reviewed and analyzed.
+
+### Clarify Governance and Require Upgrades for Testing
+
+Clear governance and frequent updates will require more periodic work for the NIST OSCAL Team, but ensure the challenges above will be less frequent and less significant.