The Art of Mapper Making
A Look Ahead
In this section, we will cover:
Overview
Mapper creation is a nuanced process in which every situation demands a unique and tailored solution. As a result, there is no one objective best template or process to follow as field mappings will always be designed on a case-by-case basis.
But don't fret! Mapper making, like many forms of development, is a skill you have to cultivate and improve at. So while there is no one-size-fits-all solution, you can still train yourself to produce mappers that are the best for your needs and uses.
To help in improving your mapper making skills, the following section details a number of tips and best practices for mapper development that you should keep in mind while creating your mapper.
Tips and Best Practices
Reference Existing Solutions
Try to browse and reference existing solutions for other mappers in OHDF Converters to glean some insight on how previous *-to-OHDF mappers were implemented. By doing this, you may be able to find existing solutions to problems you may be facing or find novel ways of implementing concepts that you never thought of before.
Some simple and generally helpful mappers to look at when starting out are the Burp Suite mapper and the Snyk mapper. These mappers are straightforward and involve minimal data manipulation or corner cases. They represent the standard mapper experience and will likely reflect how your mapper will turn out unless your data format involves complicated or nontraditional data.
Some more technically involved mappers are the CycloneDX SBOM mapper and the Nessus mapper. These mappers are much more complicated but involve handling of specific corner cases (SBOM data formatting for the CycloneDX SBOM mapper and high complexity data for the Nessus mapper). It is not advised to look at these mappers unless you are decently familiar with Typescript and software development paradigms.
Understand Your Security Tool and Data
Understand how your security data is meant to be consumed in the original security tool's use case (i.e., don't just start development with the raw security data). Ask yourself the following questions:
- How does the original security tool group security data? Is it by type of concern? Where/what component was affected?
- What associations does the tool make to common security references (e.g., NIST SP 800-53, CVE, CWE, CCE, OWASP, STIG IDs)?
- What is the purpose of the security tool (e.g., vulnerability scanning, information visualization, etc.)?
- How does the security tool organize its results (e.g., by requirement, by system, etc.)?
These answers will help ensure that the intent of the data isn't skewed by the mapping process. It is important to try and "seek parity" with the original display style in the vendor's own tool. In other words, users must be able to recognize and navigate the security data in Heimdall just as easily as they can in the original native format.
Use Detailed and Diverse Samples
Data Sanitization
Sanitize your data sample so that it is safe for public release in the OHDF Converters GitHub repository. Once sensitive data is publically released, it is difficult to effectively scrub off the Internet. You can easily prevent this from happening by thoroughly screening the data first.
Build your mapper around sample outputs that are detailed and diverse, and try to obtain the data in any machine-readable format (e.g., JSON, XML, CSV) that is natively available. Oftentimes, the schema for the data format is not publically available or is poorly documented, so it is good practice to gather a large volume of varied samples in order to accurately cover the many possible representations of the data format that may exist.
APIs
If your security tool provides an API instead of a security data export, you will need to explore the API to determine what information may need to be collected and collated for use within the mapper. Even without an explicit results file from the vendor, you should have a thorough understanding of the security data that needs to be mapped to OHDF. We recommend contacting the SAF team for further guidance in creating a specialized mapper that works with that API.
Regularly Check Your Work
Mapper development is an iterative process that involves many adjustments and corrections in order to achieve an *-to-OHDF mapping that is as accurate as possible. You are encouraged to periodically check on your mapper output during development in order to check on your progress and verify that your mapper is operating as expected.
The technical details of how to check your output will be discussed later on.
Reach Out
Don't be afraid to reach out to the SAF team for assistance with mapper development if you are unable to solve an issue by yourself or are totally lost on how to continue. Our developers can help you with everything from mapping decisions to mapper integration with OHDF Converters.
You can contact us through email (saf@groups.mitre.org) for inquiries and by creating a GitHub issue on the Heimdall2 repository for technical implementation issues.
Try to be detailed and thorough in describing your issue. It is difficult to help when we have little to no context on what your problem is or how we can address it, and we certainly can't read minds to figure it out either.
A Look Back
In this section, we covered:
Tips and best practices for mapper development:
- Review existing mappers for potential solutions to any development issues you may encounter.
Understand your security tool and data
- Have a thorough understanding of your data format so you can preserve the intent of your data format when mapping to OHDF.
Use detailed and diverse samples
- Have a detailed and diverse set of samples to use for building your mapping in order to cover all possible representations of your data format.
- Check on your in-progress OHDF mapper to ensure that your current mapping is satisfactory and working as expected.
- Reach out for help if you can't work it out on your own.