Skip to content

Commit d54cf49

Browse files
nikitawootten-nistaj-stein-nist
nikitawootten-nist
and
aj-stein-nist
committed
Profile resolution how-to readmes (#1666)
* Profile resolution how-to readmes Fixes #1178 * Delete old `resolver-2018` folder * Update resolver-pipeline readme.md with more generic instructions on running the pipeline Co-authored-by: A.J. Stein <alexander.stein@nist.gov> * Remove notice to only use Saxon 10 in line with previous feedback * Added instructions for the wrapper script --------- Co-authored-by: A.J. Stein <alexander.stein@nist.gov>
1 parent 59ef15d commit d54cf49

File tree

6 files changed

+110
-851
lines changed

6 files changed

+110
-851
lines changed

‎src/utils/util/resolver-pipeline/README.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Profile Resolver Pipeline
2+
3+
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.
4+
5+
The sequence of XSLT transformations reflects and roughly corresponds to the steps in profile resolution described for OSCAL in the [Profile Resolution Specification](https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/):
6+
7+
- **selection**: importing catalogs or profiles, and selecting controls from them
8+
9+
- **organization (merging)**: organizing the selected controls for the output representation
10+
11+
- **modification**: setting parameters and potentially supplementing, amending or editing control text
12+
13+
## Usage
14+
15+
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.
16+
17+
The following additional parameters can be used to modify the transformation pipeline's behavior:
18+
19+
| Name | Description | Default |
20+
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
21+
| `hide-source-profile-uri` | If `true`, the output catalog's metadata does not record the source profile's URI. | `false` |
22+
| `path-to-source` | Path from output catalog to location of source profile. | None |
23+
| `top-uuid` | UUID value for top-level element in output catalog, if `uuid-method` is `user-provided`. | None |
24+
| `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` |
25+
| `uuid-service` | URI for a web service that produces a UUID, if `uuid-method` is `web-service`. | `https://www.uuidgenerator.net/api/version4` |
26+
| `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 |
27+
28+
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).
29+
30+
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.
31+
32+
## Invoking the Pipeline
33+
34+
The profile resolver and other utilities in this repo rely on open-source libraries and utilities developed by third parties. To review the software version used by this project, please review [the `build` directory for manifests of software and the specific versions](../../../../build) we recommend for running utilities from this repo, specifically the recommended [version of Saxon XSLT processor defined in the pom.xml manifest](../../../../build/pom.xml).
35+
36+
### Using Saxon Manually From the Command Line
37+
38+
Before you begin:
39+
40+
- Install the Java runtime using your preferred method.
41+
- Download a compatible version of [Saxon Java Home Edition](https://www.saxonica.com/download/java.xml) and extract the `saxon-he` jar file.
42+
43+
Invoke Saxon with your document and the profile resolution stylesheet as follows:
44+
45+
```
46+
$ 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
47+
```
48+
49+
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:
50+
51+
```bash
52+
$ 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
53+
```
54+
55+
### Using the `oscal-profile-resolve.sh` Wrapper Script
56+
57+
The [`oscal-profile-resolve.sh`](./oscal-profile-resolve.sh) wrapper script only requires [Maven](https://maven.apache.org/) to be installed.
58+
It manages external dependencies, and can be invoked from other directories.
59+
60+
The syntax for invoking the wrapper script is as follows:
61+
62+
```bash
63+
$ ./oscal-profile-resolve.sh YOUR_PROFILE_DOCUMENT.xml YOUR_RESULT_BASELINE.xml [additional arguments]
64+
```
65+
66+
Additional arguments are passed into Saxon verbatim and should be in the same `name=value` format described [above](#using-saxon-manually-from-the-command-line).

‎src/utils/util/resolver-pipeline/TESTING.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Profile Resolver Pipeline Tests
2+
3+
The `testing/*` folders contain XSpec tests that indicate expected interim results of each XSLT transformation in the sequence.
4+
5+
Note that these interim results are _not necessarily valid to any OSCAL schema_, although they are quite close to OSCAL profile and catalog syntax.
6+
7+
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).

‎src/utils/util/resolver-pipeline/oscal-profile-resolve.sh‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
#!/usr/bin/env bash
2+
# OSCAL Profile Resolution Pipeline Wrapper
3+
4+
set -Eeuo pipefail
5+
6+
usage() {
7+
cat <<EOF
8+
Usage: $(basename "${BASH_SOURCE[0]}") TARGET_PROFILE OUTPUT_BASELINE [ADDITIONAL_ARGS]
9+
10+
Runs the OSCAL Profile Resolution Pipeline on the TARGET_PROFILE.
11+
12+
Additional arguments should be specified in the `key=value` format.
13+
EOF
14+
}
15+
16+
if ! [ -x "$(command -v mvn)" ]; then
17+
echo 'Error: Maven (mvn) is not in the PATH, is it installed?' >&2
18+
exit 1
19+
fi
20+
21+
[[ -z "${1-}" ]] && { echo "Error: TARGET_PROFILE not specified"; usage; exit 1; }
22+
TARGET_PROFILE=$1
23+
[[ -z "${2-}" ]] && { echo "Error: OUTPUT_BASELINE not specified"; usage; exit 1; }
24+
OUTPUT_BASELINE=$2
25+
26+
ADDITIONAL_ARGS=$(shift 2; echo $@)
27+
28+
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd)"
29+
OSCAL_DIR="${SCRIPT_DIR}/../../../.."
30+
POM_FILE="${OSCAL_DIR}/build/pom.xml"
31+
ENTRY_STYLESHEET="${SCRIPT_DIR}/oscal-profile-RESOLVE.xsl"
32+
33+
mvn \
34+
-f $POM_FILE \
35+
exec:java \
36+
-Dexec.mainClass="net.sf.saxon.Transform" \
37+
-Dexec.args="-t -s:$TARGET_PROFILE -xsl:$ENTRY_STYLESHEET -o:$OUTPUT_BASELINE $ADDITIONAL_ARGS"

‎src/utils/util/resolver-pipeline/readme.md‎

Lines changed: 0 additions & 49 deletions
This file was deleted.

0 commit comments

Comments
 (0)