Tuesday 13 August 2013

Adding Custom Descriptions and Content to Fortify using the RulePack's CustomDescriptionRule element

After Cat.Net and Checkmarx, the next TeamMentor integration target is HP's Fortify

The idea is to add references and cross-links between Fortify results and TeamMentor Guidance. Since that way we get the best of both worlds: 
  • SAST Findings
  • Targeted and customised Security Guidance
I'm currently using the 5.16 version of Fortify which contains a nice Rule Editor that can be used to create well formatted RulePack files (this tool also as a nice wizard to help with the creation of 'proper' custom rules (for example to map out new Sources or Sinks)):

The Xml editor inside this tool is wired with the correct schema (located at C:\Program Files\HP_Fortify\HP_Fortify_SCA_and_Apps_3.90\Core\config\schemas\rules.xsd) and it will highlight any validation errors (which is a great help when one is trying to understand what works and what doesn't):

The schema for the description looks like this (image from this XMLSpy generated file):

Which basically means that we can add extra content to Fortify findings using the fields:

  • Abstract,
  • Explanation, 
  • Recommendations, 
  • Tips and 
  • References (I'm not 100% how to use the ContentType)
See also the Adding Custom Descriptions to HP Fortify Rules section of the official Rules Guide pdf.

Simple Version of a CustomDescriptionRule

Here is a RulePack with the simplest version of a CustomDescriptionRule element (see gist embedded at end of this post).

The objective of this first example is to show where each editable element is shown in the Fortify's SCA UI.

Actually, all elements of CustomDescriptionRule are optional, so this file could be even simpler (with for example, only the Recommendations element used)

Once we have this XML file created (and validated via the CustomRules editor) we can add it to the engine using the Import Security Content  (located in the Security Content Management pane from the Options window):

Select the Xml file with Custom Rule(s) to import:

And click OK (which will close the current window)

Back in the main GUI, click on the Scan button (top left), which will open this window (note the custom rule entry in the command line arguments)

 Click on Run Scan:

 Which (in this case) will rescan the current project and update the finding's data:

Note: In this example I'm using the ejb sample project (included in the main Fortify installation folder)

This is a small project that scans quickly, and shows how the Fortify Engine is able to find an SQL Injection that exists in an EJB SessionBean (which is the finding type we have mapped in the CustomDescriptionRule):

To update the information tabs with the new content, click on the SQL Injection finding, and the information provided in the CustomDescriptionRule Xml file should now be visible in the Details and Recommendations tabs.

Here is where the Abstract data was inserted (as a Custom Abstract section above the original Abstract section)

Here is the Custom Explanation section, inserted above the original Explanation section (can you spot the pattern?) :

Here are the Custom Recommendations:

Here are the Custom Tips:

And finally here are the Custom References:

Some HTML inside a CustomDescriptionRule

Notice how in all the examples above the content was in clear text.

I couldn't find much documentation about what HTML tags were allowed, so I created another XML RulePack to try it out (also on the gist linked below), and it looks like the following HTML Tags work:
  • A with HREF:
  • H1
  • P
  • LI
  • Pre (for source code samples)
You can see these tags in action in the XML shown below (with the content stored in an HTML Encoded format)

which was added

to the Installed Custom Security Content

Note: at this stage we will get this error:  (because the new XML file has the ID as the previous one)

Which can be fixed by removing the previous file from the customrules folder (I couldn't find a link/button to remove this mapping on the SCA UI)

After another scan, we can see the allowed HTML tags in action.

Here is the Custom Explanation with an A HREF and H1 header

... Custom Recommendations with an A HREF and H1 header

 ... Custom Tips and Custom References with an A HREF and H1 header

Other locations where the custom content also shows up:

In the native FVDL file:

In the Fortify Security Report  PDF:

Note how in the PDF the order of the Custom content (vs the original)

... is reversed (i.e. in the SCA UI the custom content is shown first):

Next Steps for TeamMentor:

Now that we know the capabilities of the Fortify's CustomDescriptionRule element we can export (using an Script) the relevant TeamMentor content as a RulePack, and allow the TeamMentor content to be consumed from inside Fortify's SCA and PDFs :)

XML code of the sample fileS used: