Code Hierarchy Exploration Net (chen)
Project description
chen
Code Hierarchy Exploration Net (chen) is an advanced exploration toolkit for your application source code and its dependency hierarchy.
Requirements
- Java 17 - 20
- Python > 3.8.1
- Node.js > 16 (To run atom)
- Minimum 16GB RAM
Additional requirements
- Rust (For rocksdb-py compilation)
Getting started
chen container image has everything needed to get started.
Interactive console
To start the interactive console, run chennai
command.
docker run --rm -v /tmp:/tmp -v $HOME:$HOME -v $(pwd):/app:rw -it ghcr.io/appthreat/chen chennai
Jupyter notebook server
docker run --rm -v /tmp:/tmp -v $HOME:$HOME -v $(pwd):/app:rw -it ghcr.io/appthreat/chen jupyter notebook --ip 0.0.0.0 --port 9000 --no-browser --allow-root
Chennai server mode
chennai
could also be run as an HTTP server.
docker run --rm -v /tmp:/tmp -v $HOME:$HOME -v $(pwd):/app:rw -p 8080:8080 -it ghcr.io/appthreat/chen chennai --server
Defaults:
- Port 8080
- Username chenadmin
- Password chenpassword
Local Installation
# Install atom and cdxgen
sudo npm install -g @appthreat/atom @cyclonedx/cdxgen --omit=optional
# Install chen from pypi
pip install appthreat-chen
To download the chen distribution.
chen --download
To generate custom graphs and models with atom for data science, download the scientific pack which installs support for PyTorch ecosystem. conda is recommended for best experience.
chen --download --with-science
Once the download finishes, the command will display the download location along with the environment variables that need to be set to invoke chennai
console. Example output below:
[21:53:36] INFO To run chennai console, add the following environment variables to your .zshrc or .bashrc:
export JAVA_OPTS="-Xmx16G"
export JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF-8 -Djna.library.path=<lib dir>"
export SCALAPY_PYTHON_LIBRARY=python3.10
export CHEN_HOME=/home/user/.local/share/chen
export PATH=$PATH:/home/user/.local/share/chen/platform:/home/user/.local/share/chen/platform/bin:
It is important to set these environment variables without which the console commands would fail with errors.
Running the console
Type chennai
to launch the console.
chennai
_ _ _ _ _ __
/ |_ _ ._ ._ _. o |_ / \ / \ / \ / |_|_
\_ | | (/_ | | | | (_| | |_) \_/ \_/ \_/ / |
Version: 0.0.7
Type `help` to begin
chennai>
Sample commmands
Help command
chennai> help
val res0: Helper = Welcome to the interactive help system. Below you find a table of all available
top-level commands. To get more detailed help on a specific command, just type
`help.<command>`.
Try `help.importCode` to begin with.
_______________________________________________________________________________________________________________________________________________________________
command | description | example |
==============================================================================================================================================================|
annotations | List annotations | annotations |
close | Close project by name | close(projectName) |
declarations | List declarations | declarations |
distance | Show graph edit distance from the source method to the comparison methods | distance(source method iterator, comparison method iterators) |
exit | Exit the REPL | |
files | List files | files |
importAtom | Create new project from existing atom | importAtom("app.atom") |
importCode | Create new project from code | importCode("example.jar") |
imports | List imports | imports |
methods | List methods | methods('Methods', includeCalls=true, tree=true) |
sensitive | List sensitive literals | sensitive |
showSimilar | Show methods similar to the given method | showSimilar(method full name) |
summary | Display summary information | summary |
Refer to the documentation site to learn more about the commands.
Languages supported
- C/C++ (Requires Java 17 or above)
- H (C/C++ Header files alone)
- Java (Requires compilation) - 8 to 17
- Jar
- Android APK (Requires Android SDK. Set the environment variable
ANDROID_HOME
) - JavaScript
- TypeScript
- Python
Troubleshooing
Commands throw errors in chennai console
You might see errors like this in chennai console.
chennai> help
-- [E006] Not Found Error: -----------------------------------------------------
1 |help
|^^^^
|Not found: help
|-----------------------------------------------------------------------------
| Explanation (enabled by `-explain`)
|- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
| The identifier for `help` is not bound, that is,
| no declaration for this identifier can be found.
| That can happen, for example, if `help` or its declaration has either been
| misspelt or if an import is missing.
-----------------------------------------------------------------------------
1 error found
This error is mostly due to missing python .so (linux), .dll (windows) or .dylib (mac) file. Ensure the two environment variables below are set correctly.
- SCALAPY_PYTHON_LIBRARY - Use values such as python3.10, python3.11 based on the version installed. On Windows, there are no dots. python311
- JAVA_TOOL_OPTIONS - jna.library.path must be set to the python lib directory
Origin of chen
chen is a fork of the popular joern project. We deviate from the joern project in the following ways:
- Make code analysis accessible by adding first-class integration with Python and frameworks such as NetworkX and PyTorch
- Enable broader hierarchical analysis (Application + Dependency + Container + OS layer)
- By creating a more welcoming community more appropriate for beginner users with great support
License
Apache-2.0
Enterprise support
Enterprise support including custom language development and integration services is available via AppThreat Ltd. Free community support is also available via Discord.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for appthreat_chen-0.0.18-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 95f163aaa80357bf737428f9893e4394403dc7406d849ff5cbeb7b08ac255b74 |
|
MD5 | 024c874a56928cf2d95bbb870b590e9a |
|
BLAKE2b-256 | 72f70fea9954d32dd20eab814d82d5a61dd9584b5e5dfbfb354f88ff81e2897a |