Merge branch 'feature/external-constraints' into constraints/system-c…

…haracteristics/has-security
GSA · Sep 25, 2024 · a3dec6d · a3dec6d
2 parents 9d62315 + 42d2219
commit a3dec6d
Show file tree

Hide file tree

Showing 50 changed files with 281 additions and 9,520 deletions.
diff --git a/src/validations/constraints/CONTRIBUTING.md b/src/validations/constraints/CONTRIBUTING.md
@@ -187,3 +187,140 @@ To add or modify constraints and their tests, it is important to understand Meta
 - [Metapath expression language](https://pages.nist.gov/metaschema/specification/syntax/metapath/)
 - [Metaschema tutorials for modeling and constraints](https://pages.nist.gov/metaschema/tutorials/)
 - [Metaschema complete syntax reference](https://pages.nist.gov/metaschema/specification/syntax/)
+
+## Troubleshooting
+
+### Enabling stack traces with `--show-stack-trace`
+
+See [this information](./README.md#debugging-details-of-unexpected-failures-with---show-stack-trace) on how to use `--show-stack-trace` for debugging info to troubleshoot unexpected failures.
+
+### Common causes and resolutions for unexpected failures
+
+Below is a list of common cases of unexpected failures. If an unexpected failure is in this list below, it is expected behavior unless otherwise noted. Each entry should have guidance on how to resolve the underlying issue so constraints and tools can successfully complete validation.
+
+#### org.xml.sax.SAXParseException
+
+This unexpected failure or similar ones indicate a case where you used the `oscal-cli` tool and constraints to validate an otherwise valid OSCAL XML document, but did not properly escape special syntax characters in XML as required (i.e. `&`; `<`; `>`). Below is an example.
+
+```sh
+docker run --rm -it -v \
+  $(PWD):/data ghcr.io/gsa/fedramp-automation/validation-tools \
+  validate \
+  '/data/AwesomeCloudSSP1.xml' \
+  --show-stack-trace
+Validating 'file:/data/AwesomeCloudSSP1.xml' as XML.
+Unexpected failure during validation of 'file:/data/AwesomeCloudSSP1.xml'
+java.io.IOException: Unexpected failure during validation of 'file:/data/AwesomeCloudSSP1.xml'
+        at gov.nist.secauto.metaschema.core.model.validation.XmlSchemaContentValidator.validate(XmlSchemaContentValidator.java:92) ~[dev.metaschema.java.metaschema-core-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.core.model.validation.AbstractContentValidator.validate(AbstractContentValidator.java:27) ~[dev.metaschema.java.metaschema-core-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.databind.IBindingContext$ISchemaValidationProvider.validateWithSchema(IBindingContext.java:473) ~[dev.metaschema.java.metaschema-databind-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.commands.AbstractValidateContentCommand$AbstractValidationCommandExecutor.execute(AbstractValidateContentCommand.java:250) ~[dev.metaschema.java.metaschema-cli-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.processor.CLIProcessor$CallingContext.invokeCommand(CLIProcessor.java:405) ~[dev.metaschema.java.cli-processor-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.processor.CLIProcessor$CallingContext.processCommand(CLIProcessor.java:376) [dev.metaschema.java.cli-processor-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.processor.CLIProcessor.parseCommand(CLIProcessor.java:175) [dev.metaschema.java.cli-processor-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.processor.CLIProcessor.process(CLIProcessor.java:158) [dev.metaschema.java.cli-processor-1.0.2.jar:?]
+        at gov.nist.secauto.oscal.tools.cli.core.CLI.runCli(CLI.java:67) [dev.metaschema.oscal.oscal-cli-enhanced-2.0.2.jar:?]
+        at gov.nist.secauto.oscal.tools.cli.core.CLI.main(CLI.java:38) [dev.metaschema.oscal.oscal-cli-enhanced-2.0.2.jar:?]
+Caused by: org.xml.sax.SAXParseException: The entity name must immediately follow the '&' in the entity reference.
+        at java.xml/com.sun.org.apache.xerces.internal.jaxp.validation.Util.toSAXParseException(Util.java:75) ~[?:?]
+        at java.xml/com.sun.org.apache.xerces.internal.jaxp.validation.StreamValidatorHelper.validate(StreamValidatorHelper.java:178) ~[?:?]
+        at java.xml/com.sun.org.apache.xerces.internal.jaxp.validation.ValidatorImpl.validate(ValidatorImpl.java:115) ~[?:?]
+        at java.xml/javax.xml.validation.Validator.validate(Validator.java:124) ~[?:?]
+        at gov.nist.secauto.metaschema.core.model.validation.XmlSchemaContentValidator.validate(XmlSchemaContentValidator.java:90) ~[dev.metaschema.java.metaschema-core-1.0.2.jar:?]
+        ... 9 more
+```
+
+To resolve this issue, you must find special characters (e.g. `&`) and properly escape them (e.g. `&amp;`) more details can be found in [this post maintained by the StackOverflow community](https://stackoverflow.com/a/46637835).
+
+#### org.json.JSONException
+
+This unexpected failure, or similar ones, indicate a case where you used the `oscal-cli` tool and constraints to validate data that is not a valid OSCAL JSON document.
+
+```sh
+docker run --rm -it \
+  -v $(PWD):/data ghcr.io/gsa/fedramp-automation/validation-tools \
+  validate --as=json \
+  '/data/AwesomeCloudSSP1.xml' \
+  --show-stack-trace
+Validating 'file:/data/AwesomeCloudSSP1.xml' as JSON.
+An uncaught runtime error occurred. A JSONObject text must begin with '{' at 1 [character 2 line 1]
+org.json.JSONException: A JSONObject text must begin with '{' at 1 [character 2 line 1]
+        at org.json.JSONTokener.syntaxError(JSONTokener.java:503) ~[org.json.json-20240303.jar:?]
+        at org.json.JSONObject.<init>(JSONObject.java:213) ~[org.json.json-20240303.jar:?]
+        at gov.nist.secauto.metaschema.databind.IBindingContext$ISchemaValidationProvider.validateWithSchema(IBindingContext.java:465) ~[dev.metaschema.java.metaschema-databind-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.commands.AbstractValidateContentCommand$AbstractValidationCommandExecutor.execute(AbstractValidateContentCommand.java:250) ~[dev.metaschema.java.metaschema-cli-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.processor.CLIProcessor$CallingContext.invokeCommand(CLIProcessor.java:405) ~[dev.metaschema.java.cli-processor-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.processor.CLIProcessor$CallingContext.processCommand(CLIProcessor.java:376) [dev.metaschema.java.cli-processor-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.processor.CLIProcessor.parseCommand(CLIProcessor.java:175) [dev.metaschema.java.cli-processor-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.processor.CLIProcessor.process(CLIProcessor.java:158) [dev.metaschema.java.cli-processor-1.0.2.jar:?]
+        at gov.nist.secauto.oscal.tools.cli.core.CLI.runCli(CLI.java:67) [dev.metaschema.oscal.oscal-cli-enhanced-2.0.2.jar:?]
+        at gov.nist.secauto.oscal.tools.cli.core.CLI.main(CLI.java:38) [dev.metaschema.oscal.oscal-cli-enhanced-2.0.2.jar:?]
+```
+
+To resolve the issue, check the path, content, and schema validity of a file to confirm it is valid OSCAL JSON data.
+
+#### java.net.UnknownHostException
+
+This unexpected failure or similar ones indicate a DNS resolution error when using the `oscal-cli` tool to validate a remote OSCAL document on a HTTP server. Below is an example.
+
+```sh
+docker run --rm -it -v \
+  $(PWD):/data ghcr.io/gsa/fedramp-automation/validation-tools \
+  validate \
+  'http://doesnotexist.tld/AwesomeCloudSSP1.xml' \
+  --show-stack-trace
+doesnotexist.tld
+java.net.UnknownHostException: doesnotexist.tld
+        at java.base/sun.nio.ch.NioSocketImpl.connect(NioSocketImpl.java:567) ~[?:?]
+        at java.base/java.net.Socket.connect(Socket.java:752) ~[?:?]
+        at java.base/java.net.Socket.connect(Socket.java:687) ~[?:?]
+        at java.base/sun.net.NetworkClient.doConnect(NetworkClient.java:183) ~[?:?]
+        at java.base/sun.net.www.http.HttpClient.openServer(HttpClient.java:531) ~[?:?]
+        at java.base/sun.net.www.http.HttpClient.openServer(HttpClient.java:636) ~[?:?]
+        at java.base/sun.net.www.http.HttpClient.<init>(HttpClient.java:280) ~[?:?]
+        at java.base/sun.net.www.http.HttpClient.New(HttpClient.java:386) ~[?:?]
+        at java.base/sun.net.www.http.HttpClient.New(HttpClient.java:408) ~[?:?]
+        at java.base/sun.net.www.protocol.http.HttpURLConnection.getNewHttpClient(HttpURLConnection.java:1310) ~[?:?]
+        at java.base/sun.net.www.protocol.http.HttpURLConnection.plainConnect0(HttpURLConnection.java:1243) ~[?:?]
+        at java.base/sun.net.www.protocol.http.HttpURLConnection.plainConnect(HttpURLConnection.java:1129) ~[?:?]
+        at java.base/sun.net.www.protocol.http.HttpURLConnection.connect(HttpURLConnection.java:1058) ~[?:?]
+        at java.base/sun.net.www.protocol.http.HttpURLConnection.getInputStream0(HttpURLConnection.java:1691) ~[?:?]
+        at java.base/sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1615) ~[?:?]
+        at java.base/java.net.URL.openStream(URL.java:1325) ~[?:?]
+        at gov.nist.secauto.metaschema.databind.io.DefaultBoundLoader.detectFormat(DefaultBoundLoader.java:110) ~[dev.metaschema.java.metaschema-databind-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.commands.AbstractValidateContentCommand$AbstractValidationCommandExecutor.execute(AbstractValidateContentCommand.java:223) ~[dev.metaschema.java.metaschema-cli-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.processor.CLIProcessor$CallingContext.invokeCommand(CLIProcessor.java:405) ~[dev.metaschema.java.cli-processor-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.processor.CLIProcessor$CallingContext.processCommand(CLIProcessor.java:376) [dev.metaschema.java.cli-processor-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.processor.CLIProcessor.parseCommand(CLIProcessor.java:175) [dev.metaschema.java.cli-processor-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.processor.CLIProcessor.process(CLIProcessor.java:158) [dev.metaschema.java.cli-processor-1.0.2.jar:?]
+        at gov.nist.secauto.oscal.tools.cli.core.CLI.runCli(CLI.java:67) [dev.metaschema.oscal.oscal-cli-enhanced-2.0.2.jar:?]
+        at gov.nist.secauto.oscal.tools.cli.core.CLI.main(CLI.java:38) [dev.metaschema.oscal.oscal-cli-enhanced-2.0.2.jar:?]
+```
+
+Check network and DNS settings to ensure the system where you deployed `oscal-cli` and constraints can resolve the hostname to access the target HTTP server.
+
+#### java.io.IOException: Server returned HTTP response code
+
+This unexpected failure, or similar ones, indicate a HTTP error when using the `oscal-cli` tool to validate a remote OSCAL document on a HTTP server. Below is an example.
+
+```sh
+docker run --rm -it -v \
+  $(PWD):/data ghcr.io/gsa/fedramp-automation/validation-tools \
+  validate \
+  'http://example.net/AwesomeCloudSSP1.xml' \
+  --show-stack-trace
+java.io.IOException: Server returned HTTP response code: 500 for URL: http://example.net/AwesomeCloudSSP1.xml
+        at java.base/sun.net.www.protocol.http.HttpURLConnection.getInputStream0(HttpURLConnection.java:2014) ~[?:?]
+        at java.base/sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1615) ~[?:?]
+        at java.base/java.net.URL.openStream(URL.java:1325) ~[?:?]
+        at gov.nist.secauto.metaschema.databind.io.DefaultBoundLoader.detectFormat(DefaultBoundLoader.java:110) ~[dev.metaschema.java.metaschema-databind-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.commands.AbstractValidateContentCommand$AbstractValidationCommandExecutor.execute(AbstractValidateContentCommand.java:223) ~[dev.metaschema.java.metaschema-cli-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.processor.CLIProcessor$CallingContext.invokeCommand(CLIProcessor.java:405) ~[dev.metaschema.java.cli-processor-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.processor.CLIProcessor$CallingContext.processCommand(CLIProcessor.java:376) [dev.metaschema.java.cli-processor-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.processor.CLIProcessor.parseCommand(CLIProcessor.java:175) [dev.metaschema.java.cli-processor-1.0.2.jar:?]
+        at gov.nist.secauto.metaschema.cli.processor.CLIProcessor.process(CLIProcessor.java:158) [dev.metaschema.java.cli-processor-1.0.2.jar:?]
+        at gov.nist.secauto.oscal.tools.cli.core.CLI.runCli(CLI.java:67) [dev.metaschema.oscal.oscal-cli-enhanced-2.0.2.jar:?]
+        at gov.nist.secauto.oscal.tools.cli.core.CLI.main(CLI.java:38) [dev.metaschema.oscal.oscal-cli-enhanced-2.0.2.jar:?]
+```
+
+Check network settings to ensure the system where you deployed `oscal-cli` and constraints can access this HTTP server as intended. Ensure the protocol, host, and full path are valid.