Configure C++ Macros and Build Files
Warning
Please note this document is highly technical and is intended for use only by experienced developers.
In version 9.4, a semi-automatic approach was added to improve how the Checkmarx C++ parser handles macros and build files. This section provides a high-level description of what is offered.
Notice
From 9.4 on, the configuration as code CppDefaultMacros.json file is replaced by the approach described in this section.
Note that the CppDefaultMacros.json file is still considered if it exists at the root of the project being scanned, and it overrides all information obtained from the semi-automatic approach.
Overview
The objective was to reduce the manual work of configuring a CppDefaultMacros.JSON file for each project being scanned by providing the following:
A method of inspecting and extracting macros, including paths and other information from the build files present in the project being scanned.
A method of extracting macros from different repositories and adding them to a database to be used during the C++ preprocessing.
C++ Build Files Support
The new approach includes elementary support for the most common C++ build files.
Currently, the following files/build technologies are detected:
Makefiles
CMake
Autotools
QMake
Compile Database (protobuf)
We inspect these files to extract (when possible):
Macro Definitions
Global Include paths
Target OS Architecture Information
Other specific options, such as trigraphs
C++ Macros Database
CPPMacroDBMaker is a CLI application that allows Checkmarx and customers to create a database of C++ macros and their definitions to be used in CxSAST scans.
This database is constructed from a list of sources for macros provided to the application via a text file where each line follows this syntax: <url> tab <file extension> tab <libName> .
For example:
https://raw.githubusercontent.com/cloudflare/jpegtran/master/jerror.h .h jerror
The execution of this application occurs offline:
During the release build creation - by Checkmarx
Whenever there is a need to update the macro database with new sources - from customers
Notice
The CxSAST runtime assumes such a database exists. It is never created during a scan.
Checkmarx provides a docker file ready to run the macro database building tool.
docker pull checkmarx/cppmacrodbmaker
docker run -v ${PWD}\<YourLocalFolder>:/app/RepoFiles checkmarx/cppmacrodbmaker-v specifies the volume where the database will be created. Maps to
/app/RepoFilespath in the container.The database
cppMacroDBProto.protois produced in the volume with the names and definitions of all the macros in the repository files.A
repository.txtfile can be added to the volume with extra sources to scan for lib-defined macros.
Warning
When running the container, note any errors displayed on the console related to libraries where the tool failed to gather the macros.
Once the file is created, move it to <CheckmarxPath>\Checkmarx Audit\MacrosDatabase\CPP and <CheckmarxPath>\Checkmarx Engine Service\Engine Server\MacrosDatabase\CPP by simply replacing the original file in that folder.
FAQ
Q: Is the CppDefaultMacros.json configuration file needed?
A: No. It is still considered in case it exists at the project's root. The file is useful if you want to add some extra information that is neither in the macro database nor the build files.
Q: Are the build files processing ON by default?
A: Yes!
Q: If the customer runs the docker tool with a new repository.txt file, will the macros on the original database be erased?
A: No. The docker tool will generate a new database containing the original macros and the ones extracted from the source code pointed to by the URLs in respository.txt.
Q: Does the docker tool replace the original database?
A: No. The docker tool will generate a new database that needs to be copied to the correct places:
<CheckmarxPath>\Checkmarx Audit\MacrosDatabase\CPPand<CheckmarxPath>\Checkmarx Engine Service\Engine Server\MacrosDatabase\CPP.