Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Profile resolution how-to readmes #1666

Merged
merged 4 commits into from
Mar 3, 2023
Merged

Profile resolution how-to readmes #1666

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
da76795
Profile resolution how-to readmes
nikitawootten-nist Feb 22, 2023
b2b667f
Update resolver-pipeline readme.md with more generic instructions on …
nikitawootten-nist Feb 28, 2023
a04e362
Remove notice to only use Saxon 10 in line with previous feedback
nikitawootten-nist Feb 28, 2023
42222ca
Added instructions for the wrapper script
nikitawootten-nist Feb 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions src/utils/util/resolver-pipeline/TESTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Profile Resolver Pipeline Tests

The `testing/*` folders contain XSpec tests that indicate expected interim results of each XSLT transformation in the sequence.

Note that these interim results are _not necessarily valid to any OSCAL schema_, although they are quite close to OSCAL profile and catalog syntax.

The files in `testing/*` are only for this implementation. Implementation-independent tests and sample files for profile resolution are [with the specification](../../../specifications/profile-resolution).
58 changes: 32 additions & 26 deletions src/utils/util/resolver-pipeline/readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
## Profile Resolver Pipeline
# Profile Resolver Pipeline

Profile resolution is implemented here as a sequence of XSLT transformations. The sequence applies to defined inputs (a **source profile** with imported **catalog** sources) and produces defined outputs (a **profile resolution result** in the form of a catalog). The word **baseline** also refers to a particular profile in application, whether in its unprocessed form or its resolved, serialized form.

Expand All @@ -10,40 +10,46 @@ The sequence of XSLT transformations reflects and roughly corresponds to the ste

- **modification**: setting parameters and potentially supplementing, amending or editing control text

### Tests for this Implementation
## Usage

The `testing/*` folders contain XSpec tests that indicate expected interim results of each XSLT transformation in the sequence.
The entry point for the transformation pipeline is `oscal-profile-RESOLVE.xsl`, which invokes the transformation steps in sequence, taking the source profile document as primary input.

Note that these interim results are *not necessarily valid to any OSCAL schema*, although they are quite close to OSCAL profile and catalog syntax.
The following additional parameters can be used to modify the transformation pipeline's behavior:

The files in `testing/*` are only for this implementation. Implementation-independent tests and sample files for profile resolution are [with the specification](../../../specifications/profile-resolution).
| Name | Description | Default |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `hide-source-profile-uri` | If `true`, the output catalog's metadata does not record the source profile's URI. | `false` |
| `path-to-source` | Path from output catalog to location of source profile. | None |
| `top-uuid` | UUID value for top-level element in output catalog, if `uuid-method` is `user-provided`. | None |
| `uuid-method` | Method for computing UUID of top-level element in output catalog. Valid values are: `random-xslt`, in which case the `random-number-generator` XPath function must be available; `random-java`, in which case the `java.util.UUID.randomUUID()` Java method must be available; `user-provided`, in which case you must specify the `top-uuid` parameter; `web-service`, referring to the `uuid-service` parameter value; and `fixed`. | `fixed` |
| `uuid-service` | URI for a web service that produces a UUID, if `uuid-method` is `web-service`. | `https://www.uuidgenerator.net/api/version4` |
| `trace` | If set to `on`, additional debug information will be printed to the console and `opr:ERROR`, `opr:WARNING` messages will be retained in the output document. | None |

### Invoking the XSLT
Note that URIs (addresses) given in a profile document must link correctly as absolute or relative paths to their imported catalogs, as demonstrated in [examples](../../../specifications/profile-resolution/profile-resolution-examples).

Use a recent version of Saxon for best results — although we would also be *very interested* to hear from users of other XSLT engines conformant to the 3.1 family of XML standards (XSLT/XPath/XDM/XQuery).
A serialized output of profile resolution takes the form of an OSCAL catalog. Assuming inputs are correctly formed, the output is valid to the catalog schema.

The entry point for the transformation pipeline is `oscal-profile-RESOLVE.xsl`, which invokes the transformation steps in sequence, taking the source profile document as primary input. Load Saxon with your document and this stylesheet as follows (for example):
## Invoking the Pipeline

```bash
> java -cp saxon-he-10.0.jar net.sf.saxon.Transform -t -s:YOUR_PROFILE_DOCUMENT.xml -xsl:path/to/oscal-profile-RESOLVE.xsl -o:YOUR_RESULT_BASELINE.xml
```
As of now, the profile resolution pipeline **is incompatible with Saxon versions newer then 10.x**. For best results, use Saxon 10, though you may have luck with other XSLT engines conformant to the 3.1 family of XML standards (XSLT/XPath/XDM/XQuery).
nikitawootten-nist marked this conversation as resolved.
Show resolved Hide resolved

You can optionally set one or more of the parameters listed in the following table, using syntax `name=value` at the end of the command above. The sequence of parameters is not significant.
### Using Saxon From the Command Line

For example,
```bash
> java -cp saxon-he-10.0.jar net.sf.saxon.Transform -t -s:YOUR_PROFILE_DOCUMENT.xml -xsl:path/to/oscal-profile-RESOLVE.xsl -o:YOUR_RESULT_BASELINE.xml uuid-method=random-xslt hide-source-profile-uri=true
```
| Name | Description | Default |
|---|---|---|
| `hide-source-profile-uri` | If `true`, the output catalog's metadata does not record the source profile's URI. | `false` |
| `path-to-source` | Path from output catalog to location of source profile. | None |
| `top-uuid` | UUID value for top-level element in output catalog, if `uuid-method` is `user-provided`. | None |
| `uuid-method` | Method for computing UUID of top-level element in output catalog. Valid values are: `random-xslt`, in which case the `random-number-generator` XPath function must be available; `random-java`, in which case the `java.util.UUID.randomUUID()` Java method must be available; `user-provided`, in which case you must specify the `top-uuid` parameter; `web-service`, referring to the `uuid-service` parameter value; and `fixed`. | `fixed`|
| `uuid-service` | URI for a web service that produces a UUID, if `uuid-method` is `web-service`.| `https://www.uuidgenerator.net/api/version4`|
Before you begin:

Alternatively, set up the bindings in an IDE or programming environment that has XSLT 3.1 support.
- Install the Java runtime using your preferred method.
- Download a compatible version of [Saxon Java Home Edition](https://www.saxonica.com/download/java.xml) and extract the `saxon-he` jar file.

Note that URIs (addresses) given in a profile document must link correctly as absolute or relative paths to their imported catalogs, as demonstrated in [examples](../../../specifications/profile-resolution/profile-resolution-examples).
_Note: as stated above, Saxon 11 and 12 are currently unsupported. Saxon 10 must be downloaded from [Saxon's archive page](https://www.saxonica.com/products/archive.xml)_

A serialized output of profile resolution takes the form of an OSCAL catalog. Assuming inputs are correctly formed, the output is valid to the catalog schema.
Invoke Saxon with your document and the profile resolution stylesheet as follows:

```
$ java -jar /path/to/saxon-he-10.x.jar -t -s:YOUR_PROFILE_DOCUMENT.xml -xsl:path/to/oscal-profile-RESOLVE.xsl -o:YOUR_RESULT_BASELINE.xml
```

Saxon allows users to specify additional parameters (such as the ones specified [above](#usage)) by adding arguments with the format `name=value` to the end of the above command. As an example, see the command:

```bash
$ java -jar /path/to/saxon-he-10.x.jar -t -s:YOUR_PROFILE_DOCUMENT.xml -xsl:path/to/oscal-profile-RESOLVE.xsl -o:YOUR_RESULT_BASELINE.xml uuid-method=random-xslt hide-source-profile-uri=true
```
Loading