- For documentation and how to contribute, please follow this link.
- -help
- -getCpes
- -generateCCPPReport
- -listCpeDetails
- -getCves
- -writeCves
- -getHistoricalCpes
- -getHistoricalCves
- -getCweInfo
- -listVulnerabilities
- -generateSbom
- -generateConan
- -genDependencies
- -mapCpes
- -generateCSbom
- -getGhsa
- -extractGhsas
- -classifyCwe
- -getHistory
- -generateDockerSbom
- -addCpe
- -binwalk
- -compare
git clone https://github.com/nqminds/SBOM-GAP.git- vulnerability-reports directory can be downloaded from here. This also contains all the (National Vulnerability Database)NVD CPE/CWE data. (recommended)
- Cpe2.3 database link
- Unzip this and add it to data/
# please use node v16
node --version
V16.16.0
# recommended
npm --version
8.11.0Install docker and docker-compose on your machine
sudo usermod -aG docker $USERsudo chmod +x /usr/local/bin/docker-composenpm installIf, after running npm install, you do not see a list of Docker containers like the following when running docker ps -a:
vboxuser@testbinwaLlk:~$ docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
5a2541bb6992 sbom-gap-nqmvul "python ./ccscanner/.." 2 days ago Exited (2) 2 days ago sbom-gap-nqmvul-1
717bb93ecc87 ionutngm/depscanner:latest "python ./ccscanner/.." 2 days ago Exited (1) 2 days ago sbom-gap-ccscanner-1
6bb149d9d68e anchore/grype "/grype" 2 days ago Exited (1) 2 days ago sbom-gap-grype-1
4442271050da anchore/syft "/syft" 2 days ago Exited (1) 2 days ago sbom-gap-syft-1
4d9869d9be3a ionutngm/binwalk_v4:latest "binwalk" 2 days ago Exited (1) 2 days ago sbom-gap-binwalk-1
This could indicate that the Docker Compose version on your system differs from the expected version, or that the container images haven't been downloaded. To resolve this, you can try the following:
-
Check Docker and Docker Compose Installation: Ensure Docker and Docker Compose are installed and functioning correctly. Run
docker --versionanddocker-compose --versionordocker compose versionto verify their versions. -
Run Docker Compose with Root Permissions: If you suspect permission issues, you can run the following command to ensure all containers are started:
sudo docker compose up -dor
sudo docker-compose up -dnpm linkDownload the Git Advisory Database from here and replace this path in SBOM-GAP/config/config.json with your local advisory-database/advisories.
{
"gitAdvisoryDbPath": "/path/to/advisory-database/advisories"
}The above is necessary only for getting information about GHSA vulnerability codes. No need to download this data in order to generate an SBOM.
For speeding NIST API requests an API key cen be obtained from here. Please create a .env file in the root directory and add the key as:
NIST_API_KEY=your_NIST_api_keyTo improve the classification of weaknesses, include an OpenAi API key to the global .env. An API key can be obtain from here:
OPENAI_API_KEY=your_OpenAi_api_keyTo generate a Software Bill Of Materials (SBOM) for the ecosystems bellow use the command (Uses syft and grype):
nqmvul -generateSbom <project_path> <project_name>- Alpine (apk)
- C (conan)
- C++ (conan)
- Dart (pubs)
- Debian (dpkg)
- Dotnet (deps.json)
- Objective-C (cocoapods)
- Elixir (mix)
- Erlang (rebar3)
- Go (go.mod, Go binaries)
- Haskell (cabal, stack)
- Java (jar, ear, war, par, sar, nar, native-image)
- JavaScript (npm, yarn)
- Jenkins Plugins (jpi, hpi)
- Linux kernel archives (vmlinz)
- Linux kernel modules (ko)
- Nix (outputs in /nix/store)
- PHP (composer)
- Python (wheel, egg, poetry, requirements.txt)
- Red Hat (rpm)
- Ruby (gem)
- Rust (cargo.lock)
- Swift (cocoapods, swift-package-manager)
To generate a Software Bill Of Materials (SBOM) for other C/C++ ecosystems (Uses ccscanner and grype).
nqmvul -generateCCPPReport <path_to_c/cpp_project> <project_name>- Deb
- Conan
- Vcpkg
- Clib
- CPM
- Buckaroo
- Dds
- Hunter
- Cppget
- Xrepo
- Gitsubmodule
- Pkg-config
- Make
- CMake
- Autoconf
- Bazel
- Meson
- MSBuild
- Xmake
- Build2
- Buck
After generating a Software Bill Of Material (SBOM) use the visualization tool for a more detailed representation. Only CycloneDx json format is supported.
nqmvul -help- The
-getCpesflag will parse an SBOM and return a list of CPEs in the 2.3 format.
nqmvul -getCpes <absolute_path_to_sbom.json>To save the cpe to a file use:
nqmvul -getCpes <absolute_path_to_sbom.json> <filename>- The
-listCpeDetailsflag will parse an SBOM and return detailed information about each CPE, such as CVEs and CWEs
nqmvul -listCpeDetails <path_to_sbom.json>- The
-getCveswill return the known CVEs and CWS for a CPE. The CPE must be in CPE2.3 format e.g.cpe:2.3:\a:\busybox:busybox:1.33.2
nqmvul -getCves <CPE>- The
-writeCVEsflag will write all the CVE data of an sbom into a json format to output_directory/cveData.json
nqmvul -writeCves <path_to_sbom.json> <path_to_output_directory>- The
-getHistoricalCpesflag will return all known versions of the input CPE. The CPE must be in CPE2.3 format e.g.cpe:2.3:\a:\busybox:busybox:1.33.2
nqmvul -getHistoricalCpes <CPE>- The
-getHistoricalCvesflag will return all known versions of the input CVE. Supported CVE format:CVE-2022-48174
nqmvul -getHistoricalCves <CVE>- The
-getCweInfoflag will return information such as description for each CWE. Can take one or more CWEs. If multiple CWEs are passed, they must be writen without any space e.g.CWE-476,CWE-681
nqmvul -getCweInfo <CWE,CWE,...>- The
-generateSbomflag will generate an SBOM and a vulnerability report for a project. SBOM is saved to/vulnerability-reports/sboms/project_name.json. Vulnerability report is saved to/vulnerability-reports/reports/vulnerability-report-project_name.
nqmvul -generateSbom <project_path> <project_name>- The
-listVunlerabilitiesflag will list all vulnerabilities previously detected by grype
nqmvul -listVulnerabilities <path_to_vulnerability_report>- To extract all dependencies from a file system, use the
-genDependenciesflag. Used exclusively with C/C++ file systems.
- The first argument
<cpp_project>should represent the path to any C/C++ project you wish to scan. - The
<project_name>is utilised to save the extracted dependency list as/vulnerability-reports/ccsDependencies/project_name_dependencies.
nqmvul -genDependencies <cpp_project> <project_name>- The
-generateConanflag will generate aconanfile.txtfor that project.ccsDependencies/project_name_dependenciesmust exist before running this command. The dependency file is created by using the-genDependenciesflag.
nqmvul -generateConan <project_name>*The -mapCpes will create a list of known cpes for each dependency in /vulnerability-reports/ccsDependencies/project_name_dependencies and save them to vulnerability-reports/cpes/cpeMapping.json.
nqmvul -mapCpes <project_name>- The
-generateCSbomflag can be used to generate an SBOM only for C/C++ projects that are not supported by syft, e.g. C/C++ projects that are not using the CONAN package manager. It takes two arguments, the project name and format(only json or xml). Please ensure that /vulnerability-reports/conan-files/<project_name>/conanfile.txtand/vulnerability-reports/cpe_data.csvexists before running the command.
nqmvul -generateCSbom <project_name> <sbom_type>- The
-getGhsaflag will return detailed information about a known GHSA vulnerability. Please ensure the GHSA vul is valid and matches the following format e.gGHSA-j8xg-fqg3-53r7.
nqmvul -getGhsa <GHSA-vulnerability>- The
-extractGhsaswill return an array of GHSA codes. Before running this command please replace thegitAdvisoryDbPathpath fromconfig.jsonwith your localadvisory-database/advisoriespath.
nqmvul -extractGhsas <path_to_vulnerability_report>- The
-classifyCweflag will try and classify the CWE_ID as one of the following types: not-memory-related, other-memory-related, spatial-memory-related, temporal-memory-related. Please ensure the CWE_ID is valid and of the following form: e.g. 354. If the CWE_ID doesn't exist in the current database it will return "not found".
nqmvul -classifyCwe <CWE-ID>- The
-getHistoryflag will return allpreviousversions of a CPE and for each version will try and find known CVEs and CWEs (vulnerabilities). It also classifies each CWE into memory related issues or other. Can take as an argument various types of CPEs such as:cpe:2.3:\a:\busybox:busybox:1.33.2,cpe:/a:doxygen:doxygen:1.7.2. For cpes that contain trailing ':_' please place them inside quotes. e.g. :nqmvul -getHistory "cpe:2.3:a:openssl:openssl:1.1.1:_:_:_:_:_:_:_". Output is saved tooutput/output.txt
nqmvul -getHistory <CPE>To check the info of only once cpe use the false flag
nqmvul -getHistory <CPE> false- The
-generateCCPPReportcan be used to scan any type of C/C++ project. Running this command will combine some of the previous tools in order to produce an sbom and a vulnerability report.
nqmvul -generateCCPPReport <path_to_c/cpp_project> <project_name>- The
-generateDockerSbomcommand employs Syft to first generate an SBOM (Software Bill of Materials) for the specified Docker image (<image_name>). Following the SBOM creation, it uses Grype to analyze the identified components for vulnerabilities, producing a comprehensive vulnerability report. e.g.-generateDockerSbom nginx:latest nginx
nqmvul -generateDockerSbom <image_name> <project_name>- The
-addCpecommand allows a manual insertion off a CPE 2.3 to an CycloneDX json type SBOM. e.g.nqmvul -addCpe /path/to/sbom "cpe:2.3:a:postgresql:postgresql:9.6.2:*:*:*:*:*:*:*"
nqmvul -addCpe <path_to_sbom.json> <CPE>- The
nqmvul -binwalkcommand requires specific arguments to function correctly. Here is the general syntax to follow:
nqmvul -binwalk <directory_path> "[-binwalk_flags]" <file_name>- For more detailed documentation and advanced usage examples, please visit the Binwalk GitHub repository.
<directory_path>: This is the path to the directory containing the firmware file you wish to analyze.
"[-binwalk_flags]": These are the flags you want to pass to Binwalk, enclosed in square brackets and quoted. This allows for passing multiple flags as a single argument.
<file_name>: The name of the firmware file to be analyzed.
Here’s how you can use the command on a Linux system where you want to apply the -Me flag (for recursive extraction) to a specific firmware file:
nqmvul -binwalk "$(pwd)" "[-Me]" openwrt-23.05.3-mediatek-filogic-acer_predator-w6-initramfs-kernel.bin
This command tells nqmvul to run Binwalk in the current directory "$(pwd)", use the -Me flag for recursive extraction, and process the specified .bin file.
If you want to use multiple flags with Binwalk, such as -M for matryoshka (recursive) scanning and -e for extraction, you would format your command as follows:
nqmvul -binwalk /path/to/current/directory "[-M -e]" your_firmware_file.binThis setup directs nqmvul to execute Binwalk with both the -M and -e flags on your_firmware_file.bin located at the specified path.
- Ensure the path to the directory and the file name are correctly specified.
- Always enclose Binwalk flags within square brackets and quotes "[]" to ensure they are parsed correctly as a single argument by the script.
- Verify that your Docker container has access to the directory where the file resides, as Docker might have restrictions based on your system’s Docker configuration.
The -compare command compares components, versions, and vulnerabilities across multiple CycloneDX JSON SBOMs. It helps to visualize differences and similarities between the SBOMs, making it easier to identify discrepancies in components, versions, and vulnerabilities. This command takes multiple paths to SBOM files as arguments and generates a comprehensive report comparing them.
nqmvul -compare <absolute/path/to/sbom1> <absolute/path/to/sbom2> <additional SBOM paths...>The output will be saved by default to vulnerability-reports/comparisons/comparison-result.txt
If you want to specify a different file name to be saved, please use the following format:
nqmvul -compare "[<absolute/path/to/sbom-1.json> <absolute/path/to/sbom-2.json> <additional SBOM paths...>]" filenameThe output is structured in three sections:
Components Comparison: Displays which components are present or missing across the SBOMs.Version Information: Shows the version information of the components found in the SBOMs.Vulnerabilities: Lists the vulnerabilities associated with the components in each SBOM, detailing the CVEs.
npm run testnpm run test -- nqmvul-help.test.mjsnpm run lint