Skip to content

Commit

Permalink
Add explanation of errors and failure for debugging (#722)
Browse files Browse the repository at this point in the history
  • Loading branch information
@aj-stein-gsa
aj-stein-gsa authored Sep 25, 2024
1 parent d3c4bc8 commit 42d2219
Show file tree
Hide file tree
Showing 2 changed files with 276 additions and 0 deletions.
137 changes: 137 additions & 0 deletions src/validations/constraints/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Loading

0 comments on commit 42d2219

Please sign in to comment.