# chen
Code Hierarchy Exploration Net (chen) is an advanced exploration toolkit for your application source code and its dependency hierarchy. This repo contains the source code for chen library and an advanced REPL console called chennai (chen not AI).
## Requirements
- Java >= 21
- Python >= 3.10
- Node.js >= 20 (To run [atom](https://github.com/AppThreat/atom))
- Minimum 16GB RAM
## Getting started
chen container image has everything needed to get started.
### Jupyter notebook with docker compose
Use the docker compose from this repo to try chennai with Jupyter Notebook.
```shell
git clone https://github.com/AppThreat/chen
cd chen
docker compose up
```
- Navigate to the link "http://127.0.0.1:9999/tree?token=chennai"
- Click notebooks and then `getting-started.ipynb`
Use the controls in Jupyter to interact with the cells. For a preview via github click [here](./notebooks/getting-started.ipynb)
<img src="./docs/_media/chennai-jupyter1.png" alt="Jupyter console" width="512">
<img src="./docs/_media/chennai-jupyter2.png" alt="Jupyter console" width="512">
### Interactive console
To start the interactive console, run `chennai` command.
```shell
docker run --rm -v /tmp:/tmp -v $HOME:$HOME -v $(pwd):/app:rw -it ghcr.io/appthreat/chen chennai
```
### Chennai server mode
`chennai` could also be run as an HTTP server.
```shell
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
```shell
# 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.
```shell
chen --download
```
To generate custom graphs and models with atom for data science, download the scientific pack which installs support for the PyTorch ecosystem. [conda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html) is recommended for the best experience.
```shell
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:
```shell
[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.12
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.
```shell
chennai
```
```shell
_ _ _ _ _ __
/ |_ _ ._ ._ _. o |_ / \ / \ / \ / |_|_
\_ | | (/_ | | | | (_| | |_) \_/ \_/ \_/ / |
Version: 0.0.7
Type `help` to begin
chennai>
```
## Sample commmands
### Help command
```shell
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 |
callTree | Show call tree for the given method | callTree(method full name) |
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 |
reachables | Show reachable flows from a source to sink. Default source: framework-input and sink: framework-output | reachables |
cryptos | Show reachable flows from a source to sink. Default source: crypto-algorithm and sink: crypto-generate | cryptos |
```
Refer to the documentation site to learn more about the commands.
## Languages supported
- C/C++
- H (C/C++ Header files alone)
- Java (Requires compilation) - 8 to 21
- Jar
- Android APK (Requires Android SDK. Set the environment variable `ANDROID_HOME`)
- JavaScript
- TypeScript
- Python
- PHP (Requires PHP >= 7.0. Supports PHP 5.2 to 8.3)
## Troubleshooing
### Commands throw errors in chennai console
You might see errors like this in chennai console.
```shell
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 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. python313
- JAVA_TOOL_OPTIONS - jna.library.path must be set to the python lib directory
- SCALAPY_PYTHON_PROGRAMNAME - Path to Python executable in case of virtual environments (Usually not required)
## Origin of chen
chen is a fork of the popular [joern](https://github.com/joernio/joern) project. We deviate from the joern project in the following ways:
- Keep the CPG implementation at 1.0 based on the original paper.
- 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 + Cloud + beyond)
We don't intend for bug-to-bug compatibility and often rewrite patches to suit our needs. We also do not bring features and passes that do not add value for hierarchical analysis.
## License
Apache-2.0
## Enterprise support
Enterprise support including custom language development and integration services is available via AppThreat Ltd.
## Sponsors
YourKit supports open source projects with innovative and intelligent tools for monitoring and profiling Java and .NET applications.
YourKit is the creator of <a href="https://www.yourkit.com/java/profiler/">YourKit Java Profiler</a>, <a href="https://www.yourkit.com/dotnet-profiler/">YourKit .NET Profiler</a>, and <a href="https://www.yourkit.com/youmonitor/">YourKit YouMonitor</a>.
Raw data
{
"_id": null,
"home_page": "https://github.com/AppThreat/chen",
"name": "appthreat-chen",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.10",
"maintainer_email": null,
"keywords": "chen, code-analysis, static-analysis",
"author": "Team AppThreat",
"author_email": "cloud@appthreat.com",
"download_url": "https://files.pythonhosted.org/packages/58/7c/e314e127cfd135355c94c89847806a0030a068833f6166d5a77e8733e541/appthreat_chen-2.2.2.tar.gz",
"platform": null,
"description": "# chen\n\nCode Hierarchy Exploration Net (chen) is an advanced exploration toolkit for your application source code and its dependency hierarchy. This repo contains the source code for chen library and an advanced REPL console called chennai (chen not AI).\n\n## Requirements\n\n- Java >= 21\n- Python >= 3.10\n- Node.js >= 20 (To run [atom](https://github.com/AppThreat/atom))\n- Minimum 16GB RAM\n\n## Getting started\n\nchen container image has everything needed to get started.\n\n### Jupyter notebook with docker compose\n\nUse the docker compose from this repo to try chennai with Jupyter Notebook.\n\n```shell\ngit clone https://github.com/AppThreat/chen\ncd chen\ndocker compose up\n```\n\n- Navigate to the link \"http://127.0.0.1:9999/tree?token=chennai\"\n- Click notebooks and then `getting-started.ipynb`\n\nUse the controls in Jupyter to interact with the cells. For a preview via github click [here](./notebooks/getting-started.ipynb)\n\n<img src=\"./docs/_media/chennai-jupyter1.png\" alt=\"Jupyter console\" width=\"512\">\n<img src=\"./docs/_media/chennai-jupyter2.png\" alt=\"Jupyter console\" width=\"512\">\n\n### Interactive console\n\nTo start the interactive console, run `chennai` command.\n\n```shell\ndocker run --rm -v /tmp:/tmp -v $HOME:$HOME -v $(pwd):/app:rw -it ghcr.io/appthreat/chen chennai\n```\n\n### Chennai server mode\n\n`chennai` could also be run as an HTTP server.\n\n```shell\ndocker run --rm -v /tmp:/tmp -v $HOME:$HOME -v $(pwd):/app:rw -p 8080:8080 -it ghcr.io/appthreat/chen chennai --server\n```\n\n**Defaults:**\n\n- Port 8080\n- Username chenadmin\n- Password chenpassword\n\n## Local Installation\n\n```shell\n# Install atom and cdxgen\nsudo npm install -g @appthreat/atom @cyclonedx/cdxgen --omit=optional\n\n# Install chen from pypi\npip install appthreat-chen\n```\n\nTo download the chen distribution.\n\n```shell\nchen --download\n```\n\nTo generate custom graphs and models with atom for data science, download the scientific pack which installs support for the PyTorch ecosystem. [conda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html) is recommended for the best experience.\n\n```shell\nchen --download --with-science\n```\n\nOnce 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:\n\n```shell\n[21:53:36] INFO To run chennai console, add the following environment variables to your .zshrc or .bashrc:\nexport JAVA_OPTS=\"-Xmx16G\"\nexport JAVA_TOOL_OPTIONS=\"-Dfile.encoding=UTF-8 -Djna.library.path=<lib dir>\"\nexport SCALAPY_PYTHON_LIBRARY=python3.12\nexport CHEN_HOME=/home/user/.local/share/chen\nexport PATH=$PATH:/home/user/.local/share/chen/platform:/home/user/.local/share/chen/platform/bin:\n```\n\nIt is important to set these environment variables without which the console commands would fail with errors.\n\n## Running the console\n\nType `chennai` to launch the console.\n\n```shell\nchennai\n```\n\n```shell\n\n _ _ _ _ _ __\n/ |_ _ ._ ._ _. o |_ / \\ / \\ / \\ / |_|_\n\\_ | | (/_ | | | | (_| | |_) \\_/ \\_/ \\_/ / |\n\n\nVersion: 0.0.7\nType `help` to begin\n\n\nchennai>\n```\n\n## Sample commmands\n\n### Help command\n\n```shell\nchennai> help\nval res0: Helper = Welcome to the interactive help system. Below you find a table of all available\ntop-level commands. To get more detailed help on a specific command, just type\n\n`help.<command>`.\n\nTry `help.importCode` to begin with.\n_______________________________________________________________________________________________________________________________________________________________\ncommand | description | example |\n=============================================================================================================================================================|\nannotations | List annotations | annotations |\ncallTree | Show call tree for the given method | callTree(method full name) |\nclose | Close project by name | close(projectName) |\ndeclarations | List declarations | declarations |\ndistance | Show graph edit distance from the source method to the comparison methods | distance(source method iterator, comparison method iterators) |\nexit | Exit the REPL | |\nfiles | List files | files |\nimportAtom | Create new project from existing atom | importAtom(\"app.atom\") |\nimportCode | Create new project from code | importCode(\"example.jar\") |\nimports | List imports | imports |\nmethods | List methods | methods('Methods', includeCalls=true, tree=true) |\nsensitive | List sensitive literals | sensitive |\nshowSimilar | Show methods similar to the given method | showSimilar(method full name) |\nsummary | Display summary information | summary |\nreachables | Show reachable flows from a source to sink. Default source: framework-input and sink: framework-output | reachables |\ncryptos | Show reachable flows from a source to sink. Default source: crypto-algorithm and sink: crypto-generate | cryptos |\n```\n\nRefer to the documentation site to learn more about the commands.\n\n## Languages supported\n\n- C/C++\n- H (C/C++ Header files alone)\n- Java (Requires compilation) - 8 to 21\n- Jar\n- Android APK (Requires Android SDK. Set the environment variable `ANDROID_HOME`)\n- JavaScript\n- TypeScript\n- Python\n- PHP (Requires PHP >= 7.0. Supports PHP 5.2 to 8.3)\n\n## Troubleshooing\n\n### Commands throw errors in chennai console\n\nYou might see errors like this in chennai console.\n\n```shell\nchennai> help\n-- [E006] Not Found Error: -----------------------------------------------------\n1 |help\n |^^^^\n |Not found: help\n |-----------------------------------------------------------------------------\n | Explanation (enabled by `-explain`)\n |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\n | The identifier for `help` is not bound, that is,\n | no declaration for this identifier can be found.\n | That can happen, for example, if `help` or its declaration has either been\n | misspelt or if an import is missing.\n -----------------------------------------------------------------------------\n1 error found\n```\n\nThis error is mostly due to missing python .so (linux), .dll (windows) or .dylib (mac) file. Ensure the environment variables below are set correctly.\n\n- SCALAPY_PYTHON_LIBRARY - Use values such as python3.10, python3.11 based on the version installed. On Windows, there are no dots. python313\n- JAVA_TOOL_OPTIONS - jna.library.path must be set to the python lib directory\n- SCALAPY_PYTHON_PROGRAMNAME - Path to Python executable in case of virtual environments (Usually not required)\n\n## Origin of chen\n\nchen is a fork of the popular [joern](https://github.com/joernio/joern) project. We deviate from the joern project in the following ways:\n\n- Keep the CPG implementation at 1.0 based on the original paper.\n- Make code analysis accessible by adding first-class integration with Python and frameworks such as NetworkX and PyTorch.\n- Enable broader hierarchical analysis (Application + Dependency + Container + OS layer + Cloud + beyond)\n\nWe don't intend for bug-to-bug compatibility and often rewrite patches to suit our needs. We also do not bring features and passes that do not add value for hierarchical analysis.\n\n## License\n\nApache-2.0\n\n## Enterprise support\n\nEnterprise support including custom language development and integration services is available via AppThreat Ltd.\n\n## Sponsors\n\nYourKit supports open source projects with innovative and intelligent tools for monitoring and profiling Java and .NET applications.\nYourKit is the creator of <a href=\"https://www.yourkit.com/java/profiler/\">YourKit Java Profiler</a>, <a href=\"https://www.yourkit.com/dotnet-profiler/\">YourKit .NET Profiler</a>, and <a href=\"https://www.yourkit.com/youmonitor/\">YourKit YouMonitor</a>.\n\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Code Hierarchy Exploration Net (chen)",
"version": "2.2.2",
"project_urls": {
"CI": "https://github.com/AppThreat/chen/actions",
"Homepage": "https://github.com/AppThreat/chen",
"Repository": "https://github.com/AppThreat/chen"
},
"split_keywords": [
"chen",
" code-analysis",
" static-analysis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "14399a72c9bc39631ddcde196c29472b9e764f63172751a5d13d8fe0bd1715a3",
"md5": "0399d74820d870548cc584c54d8308be",
"sha256": "a12424f0f096361b4de19f6630e81abf0318f637df97b75fc73b5c4809d861ac"
},
"downloads": -1,
"filename": "appthreat_chen-2.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0399d74820d870548cc584c54d8308be",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 40607,
"upload_time": "2024-11-17T21:19:39",
"upload_time_iso_8601": "2024-11-17T21:19:39.763740Z",
"url": "https://files.pythonhosted.org/packages/14/39/9a72c9bc39631ddcde196c29472b9e764f63172751a5d13d8fe0bd1715a3/appthreat_chen-2.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "587ce314e127cfd135355c94c89847806a0030a068833f6166d5a77e8733e541",
"md5": "b7132e16a759d2be2550f02232e7b950",
"sha256": "562fa06f94db59ee144532425bb881035ed25a7dfebd88eacf90f6ae37a6b16c"
},
"downloads": -1,
"filename": "appthreat_chen-2.2.2.tar.gz",
"has_sig": false,
"md5_digest": "b7132e16a759d2be2550f02232e7b950",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.10",
"size": 38348,
"upload_time": "2024-11-17T21:19:42",
"upload_time_iso_8601": "2024-11-17T21:19:42.517810Z",
"url": "https://files.pythonhosted.org/packages/58/7c/e314e127cfd135355c94c89847806a0030a068833f6166d5a77e8733e541/appthreat_chen-2.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-17 21:19:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AppThreat",
"github_project": "chen",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "appthreat-chen"
}
JSON
