More work towards improving core documentation.

README.md

@@ -11,14 +11,16 @@ The Metaschema Java framework provides:
 - A Java parser for reading and writing XML, JSON, or YAML into Java beans generated by this framework. This functionality is provided by the [Metaschema Java Binding Parser](metaschema-java-binding/).
 - XML and JSON schema generation based on a Metaschema provided by [Netaschema Schema Generator](metaschema-schema-generator/).
 
-## Contributing to this code base
-
-Thank you for interest in contributing to the Metaschema Java framework. For complete instructions on how to contribute code, please read through our [CONTRIBUTING.md](CONTRIBUTING.md) documentation.
+## License
 
-## Public domain
+See the [project license](LICENSE.md) in this repository.
 
 This project is in the worldwide [public domain](LICENSE.md). As stated in [CONTRIBUTING.md](CONTRIBUTING.md).
 
+## Contributing to this code base
+
+Thank you for interest in contributing to the Metaschema Java framework. For complete instructions on how to contribute code, please read through our [CONTRIBUTING.md](CONTRIBUTING.md) documentation.
+
 ## Using as a Maven dependency
 
 This project's modules are published to [Maven Central](https://search.maven.org/search?q=g:gov.nist.secauto.metaschema).
@@ -27,7 +29,7 @@ You can include these artifacts in your Maven POM as a dependency.
 
 ## Building
 
-This project can be built with [Apache Maven](https://maven.apache.org/) version 3.8.4 or greater.
+This project can be built with [Apache Maven](https://maven.apache.org/) version 3.9.0 or greater.
 
 The following instructions can be used to clone and build this project.
 

TESTING.md

@@ -27,7 +27,7 @@ Developers can formally or informally identify logically discrete portions of th
 
 This project uses the Maven [Surefire plugin](https://maven.apache.org/surefire/maven-surefire-plugin/) to automatically execute [JUnit 5](https://junit.org/junit5/) unit tests during all CI builds.
 
-#### References:
+References:
 
 - [Agile Alliance Glossary: Unit Testing](https://www.agilealliance.org/glossary/unit-test)
 - [USGS Testing and Automation Guidance](https://www.usgs.gov/software-management/testing-and-automation)
@@ -40,7 +40,7 @@ This project uses [Jacoco](https://github.com/jacoco/jacoco) and the Maven [Jaco
 
 The project strives for a 60% test code coverage ratio to ensure adequate test coverage. Work in this area is focused on enhancing unit testing of critical code paths to achieve this goal and to maximize [unit testing](#unit-testing) benefits.
 
-#### References
+References:
 
 - [NIST Cybersecurity White Paper: Combinatorial Coverage Difference Measurement](https://nvlpubs.nist.gov/nistpubs/CSWP/NIST.CSWP.06222021-draft.pdf)
 - [USGS Testing and Automation Guidance](https://www.usgs.gov/software-management/testing-and-automation)
@@ -49,7 +49,13 @@ The project strives for a 60% test code coverage ratio to ensure adequate test c
 
 As developers write code incrementally, it is not uncommon that undesirable (e.g. insecure code, underperforming) behavior of the code is not immediately apparent to the developer as they add or modify it. There are many factors a developer must continuously track across the codebase to prevent any undesirable behavior caused by how the code is written. Static analyzers are tools that augment the development process by analyzing the code "statically" (i.e. only reading the code as written and not executing it as bundled, finalized software). These tools perform analysis to spot potentially undesired behavior and report it to the developer. Often, these tools will provide recommendations on how to rewrite the code to potentially mitigate the issue. These tools help increase the ongoing awareness and inside into undesired behaviors while reducing the time and cognitive load needed for one or more developers to review the code.
 
-#### References
+Static analysis in this project is provided by multiple solutions.
+
+- [PMD](https://pmd.github.io/) is used to identify common programming errors. PMD is [configured](https://github.com/usnistgov/oss-maven/blob/main/oss-build-support/src/main/resources/pmd/category/java/custom.xml) to enforce Java programming best practices; to look for flaws in the code style, design, and documentation; and to identify error prone code and potential performance problems.
+- [SpotBugs](https://spotbugs.github.io/) identifies potential bugs using over 400 bug patterns. SpotBugs performs analysis during builds using the Maven [SpotBugs plugin](https://spotbugs.github.io/spotbugs-maven-plugin/).
+- [Checkstyle](https://checkstyle.sourceforge.io/) to enforce a [coding style](https://github.com/usnistgov/oss-maven/blob/main/oss-build-support/src/main/resources/checkstyle/checkstyle.xml). Checkstyle is run during builds using the Maven [checkstyle plugin](https://maven.apache.org/plugins/maven-checkstyle-plugin/).
+
+References:
 
 - [NIST Computer Security Resource Center Glossary: What is a static code analyzer?](https://csrc.nist.gov/glossary/term/static_code_analyzer)
 - [USGS Testing and Automation Guidance](https://www.usgs.gov/software-management/testing-and-automation)
@@ -58,7 +64,9 @@ As developers write code incrementally, it is not uncommon that undesirable (e.g
 
 As developers write code incrementally, it is common that undesirable behavior (e.g. not secure, not performant) is unnoticed until software is executed. In those cases it is not always apparent to the developer as they write or execute the software. Dynamic analysis tools, unlike static analysis tools, run the software in various conditions and with various data inputs to test for undesirable behavior. Dynamic analysis will find bugs that static analysis will often not find and vice versa, so performing both analyses on the code base has benefits. Dynamic analysis tools can recommend configuration and deployment changes to staff to potentially mitigate the undesired behavior. Using such a tool can reduce risk and improve the software's behavior with less developer effort. Detecting and fixing the behavior before an end user observes it also reduces reputational risk for the software.
 
-#### References
+This project does not use a dynamic analysis solution at this time.
+
+References:
 
 - [NIST Computer Security Resource Center Glossary: What is a dynamic code analyzer?](https://csrc.nist.gov/glossary/term/dynamic_code_analyzer)
 - [USGS Testing and Automation Guidance](https://www.usgs.gov/software-management/testing-and-automation)
@@ -68,7 +76,9 @@ As developers write code incrementally, it is common that undesirable behavior (
 
 Modern software must often provide complex functionality combining a variety of media, protocols, and data exchange mechanisms. It is often too resource intensive to implement the prerequisite functionality for these capabilities in before completing the features of the software the the end user wants. Developers use third-party libraries and tools to efficiently develop software and not expend resources on common prerequisites. Supply chain analysis identifies these third-party tools and software libraries and subsequently flag potentially undesired behavior from code changes, discovered security vulnerabilities, and/or performance degradation. When developers perform this analysis, they significantly reduce the risk of supply chain attacks. Not doing any supply chain analysis significantly increases the risk and likelihood of being an unknowing target of this increasingly popular attack vector.
 
-#### References
+Supply chain analysis is supported in this project by GitHub [Dependabot](https://docs.github.com/en/code-security/dependabot). Dependabot is [configured](https://github.com/usnistgov/metaschema-java/blob/main/.github/dependabot.yml) to automatically identify vulnerable and out-of-date dependencies and GitHub actions plugins, and create pull requests to update to newer versions.
+
+References:
 
 - [NIST Special Publication 800-161 Revision 1: Cybersecurity Supply Chain Risk Management Practices for Systems and Organizations](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-161r1.pdf)