Skip to main content

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.

6436185257.png

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/RepoFiles path in the container.

  • The database cppMacroDBProto.proto is produced in the volume with the names and definitions of all the macros in the repository files.

  • A repository.txt file 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\CPP and

  • <CheckmarxPath>\Checkmarx Engine Service\Engine Server\MacrosDatabase\CPP.