From 5a17f737e2c9ac4d24d762e80524e4a8bcad59d1 Mon Sep 17 00:00:00 2001 From: Alexander Kuechler Date: Wed, 4 Dec 2024 09:40:41 +0100 Subject: [PATCH] Add neo4j documentation --- docs/docs/GettingStarted/index.md | 4 +- docs/docs/GettingStarted/neo4j.md | 118 ++++++++++++++++++++++++++++++ docs/mkdocs.yaml | 1 + 3 files changed, 122 insertions(+), 1 deletion(-) create mode 100644 docs/docs/GettingStarted/neo4j.md diff --git a/docs/docs/GettingStarted/index.md b/docs/docs/GettingStarted/index.md index 028372010d..6743f16814 100644 --- a/docs/docs/GettingStarted/index.md +++ b/docs/docs/GettingStarted/index.md @@ -16,6 +16,8 @@ After [installing the library](./installation), it can be used in different ways * [As a library for Kotlin/Java](./library) * [Via an interactive command line interface](./cli) * [With custom automated analyses using the Query API](./query) +* [Via neo4j](./neo4j) -In all these cases, the [Shortcuts](./shortcuts) provide you a convenient way to + +In the first three cases, the [Shortcuts](./shortcuts) provide you a convenient way to quickly explore some of the most relevant information. diff --git a/docs/docs/GettingStarted/neo4j.md b/docs/docs/GettingStarted/neo4j.md new file mode 100644 index 0000000000..661c59aace --- /dev/null +++ b/docs/docs/GettingStarted/neo4j.md @@ -0,0 +1,118 @@ +--- +title: "Using the Interactive CLI" +linkTitle: "Using the Interactive CLI" +no_list: true +weight: 2 +date: 2020-01-30 +description: > + Using neo4j for visualization (cpg-n2o4j) +--- + +# Neo4J visualisation tool for the Code Property Graph + +A simple tool to export a *code property graph* to a neo4j database. + +## Requirements + +The application requires Java 17 or higher. + +## Build + +Build (and install) a distribution using Gradle + +``` +../gradlew installDist +``` + +Please remember to adjust the `gradle.properties` before building the project. + +## Usage + +``` +./build/install/cpg-neo4j/bin/cpg-neo4j [--infer-nodes] [--load-includes] [--no-default-passes] + [--no-neo4j] [--no-purge-db] [--print-benchmark] + [--use-unity-build] [--benchmark-json=] + [--custom-pass-list=] + [--export-json=] [--host=] + [--includes-file=] + [--password=] [--port=] + [--save-depth=] [--top-level=] + [--user=] ([...] | -S= + [-S=]... | + --json-compilation-database= | + --list-passes) + [...] The paths to analyze. If module support is + enabled, the paths will be looked at if they + contain modules + --benchmark-json= + Save benchmark results to json file + --custom-pass-list= + Add custom list of passes (includes + --no-default-passes) which is passed as a + comma-separated list; give either pass name if + pass is in list, or its FQDN (e.g. + --custom-pass-list=DFGPass,CallResolver) + --export-json= + Export cpg as json + --host= Set the host of the neo4j Database (default: + localhost). + --includes-file= + Load includes from file + --infer-nodes Create inferred nodes for missing declarations + --json-compilation-database= + The path to an optional a JSON compilation database + --list-passes Prints the list available passes + --load-includes Enable TranslationConfiguration option loadIncludes + --no-default-passes Do not register default passes [used for debugging] + --no-neo4j Do not push cpg into neo4j [used for debugging] + --no-purge-db Do no purge neo4j database before pushing the cpg + --password= + Neo4j password (default: password + --port= Set the port of the neo4j Database (default: 7687). + --print-benchmark Print benchmark result as markdown table + -S, --softwareComponents= + Maps the names of software components to their + respective files. The files are separated by + commas (No whitespace!). + Example: -S App1=./file1.c,./file2.c -S App2=. + /Main.java,./Class.java + --save-depth= Performance optimisation: Limit recursion depth + form neo4j OGM when leaving the AST. -1 + (default) means no limit is used. + --top-level= Set top level directory of project structure. + Default: Largest common path of all source files + --use-unity-build Enable unity build mode for C++ (requires + --load-includes) + --user= Neo4j user name (default: neo4j) +``` +You can provide a list of paths of arbitrary length that can contain both file paths and directory paths. + +## Json export + +It is possible to export the cpg as json file with the `--export-json` option. +The graph is serialized as list of nodes and edges: +```json +{ + "nodes": [...], + "edges": [...] +} +``` +Documentation about the graph schema can be found at: +[https://fraunhofer-aisec.github.io/cpg/CPG/specs/graph](https://fraunhofer-aisec.github.io/cpg/CPG/specs/graph) + +Usage example: +``` +$ build/install/cpg-neo4j/bin/cpg-neo4j --export-json cpg-export.json --no-neo4j src/test/resources/client.cpp +``` + +To export the cpg from a neo4j database, you can use the neo4j `apoc` plugin. +There it's also possible to export only parts of the graph. + +## Known issues: + +- While importing sufficiently large projects with the parameter --save-depth=-1 + a java.lang.StackOverflowError may occur. + - This error could be solved by increasing the stack size with the JavaVM option: -Xss4m + - Otherwise the depth must be limited (e.g. 3 or 5) + +- While pushing a constant value larger than 2^63 - 1 a java.lang.IllegalArgumentException occurs. diff --git a/docs/mkdocs.yaml b/docs/mkdocs.yaml index e73c12e752..a90e68543a 100755 --- a/docs/mkdocs.yaml +++ b/docs/mkdocs.yaml @@ -158,6 +158,7 @@ nav: - "Using the Interactive CLI": GettingStarted/cli.md - "Using the Query API": GettingStarted/query.md - "Shortcuts to Explore the Graph": GettingStarted/shortcuts.md + - "Using neo4j": GettingStarted/neo4j.md - "Specifications": - CPG/specs/index.md - "Graph Schema": CPG/specs/graph.md