Package: cpggen
CPG Generator██████╗██████╗  ██████╗
██╔════╝██╔══██╗██╔════╝
██║     ██████╔╝██║  ███╗
██║     ██╔═══╝ ██║   ██║
╚██████╗██║     ╚██████╔╝
 ╚═════╝╚═╝      ╚═════╝CPG Generator is a python cli tool to generateCode Property Graph, a novel intermediate representation, for code and threat analysis. The generated CPG can be directly imported toJoernfor analysis.Pre-requisitesJDK 11 or abovePython 3.10Docker or podman (Windows, Linux or Mac) orAtom ⚛orJoernInstallationcpggen is available as a single executable binary,PyPI packageor as acontainer image.Single executable binariesDownload the executable binary for your operating system from thereleases page. These binary bundle the following:Atom ⚛cpggen with Python 3.10cdxgen with Node.js 18 - Generates SBoMcurl-LOhttps://github.com/AppThreat/cpggen/releases/latest/download/cpggen-linux-amd64
chmod+xcpggen-linux-amd64
./cpggen-linux-amd64--helpAtom based frontend.curl-LOhttps://github.com/AppThreat/cpggen/releases/latest/download/atomgen
chmod+xatomgen
./atomgen--helpOn Windows,curl-LOhttps://github.com/appthreat/cpggen/releases/latest/download/cpggen.exe.\cpggen.exe--helpNOTE: On Windows, antivirus and antimalware could prevent this single executable from functioning properly. Depending on the system, administrative privileges might also be required. Use container-based execution as a fallback.OCI Artifacts via ORAS cliUseORAS clito download the cpggen binary on Linux and Windows.VERSION="1.0.0"curl-LO"https://github.com/oras-project/oras/releases/download/v${VERSION}/oras_${VERSION}_linux_amd64.tar.gz"mkdir-poras-install/
tar-zxforas_${VERSION}_*.tar.gz-Coras-install/
sudomvoras-install/oras/usr/local/bin/
rm-rforas_${VERSION}_*.tar.gzoras-install/oraspullghcr.io/appthreat/cpggen-bin:v1
chmod+xcpggen-linux-amd64
./cpggen-linux-amd64--helpOn WindowssetVERSION="1.0.0"curl.exe-sLO"https://github.com/oras-project/oras/releases/download/v%VERSION%/oras_%VERSION%_windows_amd64.zip"tar.exe-xvzforas_%VERSION%_windows_amd64.zipmkdir-p%USERPROFILE%\bin\copyoras.exe%USERPROFILE%\bin\setPATH=%USERPROFILE%\bin\;%PATH%Invoke-WebRequest-Urihttps://github.com/oras-project/oras/releases/download/v1.0.0/oras_1.0.0_windows_amd64.zip-UseBasicParsing-OutFileoras_1.0.0_windows_amd64.zipExpand-Archive-Pathoras_1.0.0_windows_amd64.zip-DestinationPath.oras.exepullghcr.io/appthreat/cpggen-windows-bin:v1PyPI packageThis would install the python cli tool with bundledatomdistribution.pip install cpggenWith atom, CPG can be generated for the following languages:C/C++JavaJarsJavaScript/TypeScriptPythonInstall joern and set theJOERN_HOMEenvironment variable if you would like support for additional languages and binaries.Bundled container imagedocker pull ghcr.io/appthreat/cpggen
# podman pull ghcr.io/appthreat/cpggenUse the AWS Public ECR mirror for those T days when ghcr becomes unavailable.docker pull public.ecr.aws/appthreat/cpggen:latest
# podman pull public.ecr.aws/appthreat/cpggen:latestAlmalinux 9 requires the CPU to support SSE4.2. For kvm64 VM use the Almalinux 8 version instead.docker pull ghcr.io/appthreat/cpggen-alma8
# podman pull ghcr.io/appthreat/cpggen-alma8Or use the nightly to always get the latest joern and tools.docker pull ghcr.io/appthreat/cpggen:nightly
# podman pull ghcr.io/appthreat/cpggen:nightlyFinally, a slimmer image based on atom distribution.docker pull ghcr.io/appthreat/atomgen
# podman pull ghcr.io/appthreat/atomgenUsageTo auto detect the language from the current directory and generate CPG.cpggenTo specify input and output directory.cpggen -i <src directory> -o <CPG directory or file name>You can even pass a git or a package url or CVE id as sourcecpggen -i https://github.com/HooliCorp/vulnerable-aws-koa-app -o /tmp/cpgcpggen -i "pkg:maven/org.apache.commons/commons-io@1.3.2" -o /tmp/cpgexport GITHUB_TOKEN=<token with read:packages scope>
cpggen -i CVE-2023-32681 -o /tmp/cpg

cpggen -i GHSA-j8r2-6x86-q33q -o /tmp/cpgTo specify language type.cpggen -i <src directory> -o <CPG directory or file name> -l java

# Comma separated values are accepted for multiple languages
cpggen -i <src directory> -o <CPG directory or file name> -l java,js,pythonContainer-based invocationdocker run --rm -it -v /tmp:/tmp -v $(pwd):/app:rw --cpus=4 --memory=16g -t ghcr.io/appthreat/cpggen cpggen -i <src directory> -o <CPG directory or file name>Export graphsBy passing--export, cpggen can export the various graphs to many formats usingjoern-exportExample to exportcpg14graphs indotformatcpggen-i~/work/sandbox/crAPI-o~/work/sandbox/crAPI/cpg_out--build--export--export-out-dir~/work/sandbox/crAPI/cpg_exportTo exportcpginneo4jcsvformatcpggen-i~/work/sandbox/crAPI-o~/work/sandbox/crAPI/cpg_out--build--export--export-out-dir~/work/sandbox/crAPI/cpg_export--export-reprcpg--export-formatneo4jcsvSlicing graphsPass--sliceargument to extract intra-procedural slices from the CPG. By default, slices would be based onUsages. Pass--slice-mode DataFlowto create a sliced CPG based onDataFlow.cpggen-i~/work/sandbox/crAPI-o~/work/sandbox/crAPI/cpg_out--sliceCreating vectorsPass--vectorsargument to extract vector representations of code from CPG in json format.cpggen-i~/work/sandbox/crAPI-o~/work/sandbox/crAPI/cpg_out--vectorsArtifacts producedUpon successful completion, cpggen would produce the following artifacts in the directory specified underout_dir{name}-{lang}.⚛ - Atom representation for the given language. Requires the use of atomgen container image or the cli argument--use-atom{name}-{lang}.cpg.bin - Code Property Graph for the given language type{name}-{lang}.bom.json - SBoM in CycloneDX json format. Requires the environment variableENABLE_SBOMto be set totrue{name}-{lang}.manifest.json - A json file listing the generated artifacts and the invocation commandsServer modecpggen can run in server mode.cpggen --serverYou can invoke the endpoint/cpgto generate CPG from a path, http or package url. Parameters can be passed using GET or POST request.curl "http://127.0.0.1:7072/cpg?src=/Volumes/Work/sandbox/vulnerable-aws-koa-app&out_dir=/tmp/cpg_out&lang=js"curl "http://127.0.0.1:7072/cpg?url=https://github.com/HooliCorp/vulnerable-aws-koa-app&out_dir=/tmp/cpg_out&lang=js"Package url with slicing.curl "http://127.0.0.1:7072/cpg?url=pkg:maven/org.apache.commons/commons-io@1.3.2&out_dir=/tmp/cpg_out&slice=true"Languages supportedLanguageRequires buildMaturityCNoHighC++NoHighJavaNo (*)MediumScalaYesHighJavaScriptNoMediumTypeScriptNoMediumKotlinNo (*)LowPhpNoLowPythonNoLow(*) - Precision could be improved with dependenciesEXPERIMENTAL: Use the providedprotobuf bindingsto build new language frontends.Full list of optionscpggen --help
usage: cpggen [-h] [-i SRC] [-o CPG_OUT_DIR] [-l LANGUAGE] [--use-container] [--build] [--joern-home JOERN_HOME] [--server] [--server-host SERVER_HOST] [--server-port SERVER_PORT] [--export]
              [--export-repr {ast,cfg,cdg,ddg,pdg,cpg,cpg14,all}] [--export-format {neo4jcsv,graphml,graphson,dot}] [--export-out-dir EXPORT_OUT_DIR] [--verbose] [--skip-sbom] [--slice] [--slice-mode {Usages,DataFlow}] [--use-parse]

CPG Generator

optional arguments:
  -h, --help            show this help message and exit
  -i SRC, --src SRC     Source directory or url or CVE or GHSA id
  -o CPG_OUT_DIR, --out-dir CPG_OUT_DIR
                        CPG output directory
  -l LANGUAGE, --lang LANGUAGE
                        Optional. CPG language frontend to use. Auto-detects by default.
  --use-container       Use cpggen docker image
  --build               Attempt to build the project automatically
  --joern-home JOERN_HOME
                        Joern installation directory
  --server              Run cpggen as a server
  --server-host SERVER_HOST
                        cpggen server host
  --server-port SERVER_PORT
                        cpggen server port
  --export              Export CPG as a graph
  --export-repr {ast,cfg,cdg,ddg,pdg,cpg,cpg14,all}
                        Graph representation to export
  --export-format {neo4jcsv,graphml,graphson,dot}
                        Export format
  --export-out-dir EXPORT_OUT_DIR
                        Export output directory
  --verbose             Run cpggen in verbose mode
  --skip-sbom           Do not generate SBoM
  --slice               Extract intra-procedural slices from the CPG
  --slice-mode {Usages,DataFlow}
                        Mode used for CPG slicing
  --use-atom            Use atom toolkit
  --vectors             Extract vector representations of code from CPGEnvironment variablesNamePurposeJOERN_HOMEOptional when using atom. Joern installation directoryCPGGEN_HOSTcpggen server host. Default 127.0.0.1CPGGEN_PORTcpggen server port. Default 7072CPGGEN_CONTAINER_CPUCPU units to use in container execution mode. Default computedCPGGEN_CONTAINER_MEMORYMemory units to use in container execution mode. Default computedCPGGEN_MEMORYHeap memory to use for frontends. Default computedAT_DEBUG_MODESet to debug to enable debug loggingCPG_EXPORTSet to true to export CPG graphs in dot formatCPG_EXPORT_REPRGraph to export. Default allCPG_EXPORT_FORMATExport format. Default dotCPG_SLICESet to true to slice CPGCPG_SLICE_MODESlice mode. Default UsagesCPG_VECTORSSet to true to generate vector representations of code from CPGCDXGEN_ARGSExtra arguments to pass to cdxgenENABLE_SBOMEnable SBoM generation using cdxgenJIMPLE_ANDROID_JAROptional when using atom. Path to android.jar for use with jimple for .apk or .dex to CPG conversionGITHUB_TOKENToken with read:packages scope to analyze CVE or GitHub AdvisoryUSE_ATOMUse AppThreat atom instead of joern frontends. atomgen would default to this mode.GitHub actionsUse the marketplaceactionto generate CPGs using GitHub actions. Optionally, the upload the generated CPGs as build artifacts use the below step.- name: Upload cpg
  uses: actions/upload-artifact@v1.0.0
  with:
    name: cpg
    path: cpg_outLicenseApache-2.0Developing / Contributinggit clone git@github.com:AppThreat/cpggen.git
cd cpggen

python -m pip install --upgrade pip
python -m pip install poetry
# Add poetry to the PATH environment variable
poetry install

poetry run cpggen -i <src directory>