Last updated at Mon, 28 Aug 2017 14:45:32 GMT

Over the years, several documents have been written about how to write custom vulnerability checks in Nexpose.  The most important of these include one about the various components of a vulnerability check, one that gives examples of common vulnerability checking techniques, and another about converting NASL checks to something compatible with Nexpose.  These are all great documents in their own right, and some combination of them is often be more than enough to get even a new security practitioner well underway in writing vulnerability checks for Nexpose.

Unfortunately these documents alone are not always enough. From time to time we (the team at Rapid7 responsible for all vulnerability checks, among other things) get questions from both internal and external customers about how to do more advanced things with Nexpose's checks.  Fortunately, there is a pretty simple solution to this problem which has actually been shipping with the product for well over a year and astute Nexpose users may have already discovered this gem -- vulnerability schemas.  If you've read the previously mentioned documents, you know that all of Nexpose's checks are stored in XML format, and if you've spent any time with XML you are likely very familiar with the variety of schemas that can be used to describe, validate or understand XML documents.

Getting the Schemas

Nexpose ships with XSDs and they can be found in the plugins/xsd/ directory inside of your Nexpose installation.  There are numerous files, however here are the most important ones:

  • vulnerability-descriptor.xsd: describes the format for the vulnerability metadata stored in the .xml file
  • vulnerability-check.xsd: describes the format of the vulnerability check logic stored in the .vck file
  • vulnerability-solution.xsd: describes the format of the vulnerability solution instructions stored in the .sol file
  • vulnerability-shared.xsd: describes elements that are common among one or more of the check, descriptor or solution

Using the Schemas

Much like a set of blueprints won't necessarily allow someone who has never picked up a hammer in their life to suddenly be able to build a house, these schemas alone may not be enough for you to be able to write custom Nexpose vulnerability checks.  Instead, think of these schemas as a companion to the three previously mentioned documents which, all together, should be plenty adequate in getting you well on your way to becoming proficient in Nexpose vulnerability checks.  Below I describe several common situations in which these schemas could be used.

Validating Vulnerability Content

If you've every written or modified XML documents by hand, you've almost certainly experienced simple syntax errors like missing closing elements, improper attribute formatting and the like, and if you've ever worked with custom XML documents you've almost certainly experienced the complexities involved in ensuring that your custom XML document adheres to the standards of whatever will be consuming it.  Rather than writing the XML document and simply blindly giving it to the application in question only to find out that it is horrifically incorrect, you can use XML schemas to validate said XML document.

Assume for example's sake that you have a vulnerability check, descriptor and solution named my-rad-vulnerability.vck, my-rad-vulnerability.xml and my-rad-vulnerability.sol, respectively.  There are any number of ways to use Nexpose's vulnerability schemas to validate these files, especially if you are doing so programmatically, however the easiest and suggested way is using xmllint.  To use xmllint to achieve this goal, you need to pass it three options -- the path to a schema as an argument to --schema, the path to the XML document to validate, and finally --noout so as to simply tell you if it validated.  If all of your XML files are correct, you'll see results like this:

 $  xmllint --noout --schema <nexpose path>/plugins/xsd/vulnerability-check.xsd my-rad-vulnerability.vck my-rad-vulnerability.vck validates $ xmllint --noout --schema <nexpose path>/plugins/xsd/vulnerability-descriptor.xsd my-rad-vulnerability.xml my-rad-vulnerability.xml validates $ xmllint --noout --schema <nexpose path>/plugins/xsd/vulnerability-solution.xsd my-rad-vulnerability.sol my-rad-vulnerability.sol validates

If all of your XML files are not correct, you'll see results like this:

 $ xmllint --noout --schema ../../../../../../../../public/plugins/xsd/vulnerability-check.xsd my-rad-vulnerability.vck my-rad-vulnerability.vck:9: element HTTPResponse: Schemas validity error : Element 'HTTPResponse', attribute 'code': 'success' is not a valid value of the local atomic type. my-rad-vulnerability.vck fails to validate $ xmllint --noout --schema ../../../../../../../../public/plugins/xsd/vulnerability-descriptor.xsd my-rad-vulnerability.xml my-rad-vulnerability.xml:2: element Vulnerability: Schemas validity error : Element 'Vulnerability': Missing child element(s). Expected is one of ( pci, Description ). my-rad-vulnerability.xml fails to validate $  xmllint --noout --schema ../../../../../../../../public/plugins/xsd/vulnerability-solution.xsd my-rad-vulnerability.sol my-rad-vulnerability.sol:2: element Solution: Schemas validity error : Element 'Solution': Missing child element(s). Expected is one of ( summary, Supercedes, Prerequisites, AppliesTo, rollup, patch, AdditionalInfo ). my-rad-vulnerability.sol fails to validate

That output tells you the following, albeit a bit cryptically:

  1. Your code attribute in your check is wrong
  2. Your descriptor is missing a Description
  3. Your solution is missing a summary

Understanding Vulnerability Content

OK, so you know how to write and validate XML and you know the mechanics behind writing a custom vulnerability check, but what if that isn't enough?  What if you wonder what else you can do with checks, descriptors or solutions?  View the schemas and find out!

Questions, Feedback and Future Enhancements

As new detection methods are added to Nexpose or other changes are made, these schemas are updated and shipped to customers.  If you have questions about how to use them or are looking for detection logic not described in the schemas, ask here, in the forums or through your friendly Rapid7 Support representative.  We'd be happy to help!

Enjoy!