ProfMal

KO | EN

gitlite — search

#react #typescript #go #golang #machine-learning #docker #macos #nodejs #windows #cli #kubernetes #pytorch #security #mcp

(★ 14)

ProfMal is a detection tool designed for identifying malicious NPM packages, combining static analysis and dynamic analysis.

ProfMal Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

## ProfMal: Detecting Malicious NPM Packages by the Synergy between Static and Dynamic Analysis

> [!IMPORTANT]
> **🚀 We have released [ProfMalPlus](https://github.com/yiheng98/ProfMalPlus)!**
>
> ProfMalPlus is a brand-new multi-agent detection tool. Compared with the current ProfMal, it delivers **better detection performance**, a **lower false-positive rate**, and **stronger explainability**.
>
> - 📦 Repository: [https://github.com/yiheng98/ProfMalPlus](https://github.com/yiheng98/ProfMalPlus)

## Overview

ProfMal is a unified, graph-based detector that leverages the synergy between static and dynamic analysis to detect malicious NPM packages.

## Sensitive API List

Our tool operates at the granularity of **Node.js built-in APIs**. The sensitive API list is provided in [sensitive_call.csv](./sensitive_call.csv).

## Structure

The key files and folders in this project are:

- `base_classes`: Defines the data structures for PDG and CPG, including node and edge definitions.

- `detector`: Contains the core implementation of the [HGT](https://github.com/acbull/pyHGT) model, including layer definitions, embedding procedures, input data construction, and graph classification.

- `detect_model.pth`: You can use the model we trained or train a new model based on your datasets. To generate the graph only, see the instructions in the **usage** section.

- `npm_pipeline`: Provides code and corresponding data structures for behavior graph generation.

- `package.py`: The core component for constructing the behavior graph, implementing operations for different types of statements.

- `dynamic_helper.py`: Performs dynamic analysis using [NodeProf](https://github.com/Haiyang-Sun/nodeprof.js), an instrumentation and profiling framework for [Graal.js](https://github.com/graalvm/graaljs). We use NodeProf to generate dynamic call graphs and identify sensitive API invocations. Instrumentation callbacks are implemented in `dyn.js`,  following the approach used by Jelly for dynamic call graph construction. We add an instrumentation callback for the *eval* function, which is frequently exploited by attackers to execute arbitrary code. This allows us to capture the evaluated source code and incorporate it into our behavior graph generation.

Sensitive API identification is achieved by modifying the builtin module layer of the [Node.js](https://github.com/oracle/graaljs/tree/master/graal-nodejs/lib) runtime within Graal.js to support NodeProf-based tracking. As illustrated in the figure, the builtin module layer defines core module APIs accessed by the Node.js application.

+ `static_helper.py`: Performs static analysis by first downloading the required third-party libraries,  then uses Joern and Jelly to generate the CPG and call graph.
+ `jelly_helper.py/joern_helper.py`: Contain the invocation code for Jelly and Joern. If you encounter timeouts when analyzing large projects, adjust the timeout settings in these files.

- `llm.py`: Implements interaction with LLMs. All **prompt** templates are defined here.

## Prerequisite

The detector runs only on Linux, to run the dynamic analysis, docker is necessary.

- Ubuntu 22.04
- [Docker](https://www.docker.com/)

## Setup

+ This implementation targets **Python 3.11**. Install dependencies with:

```shell
  pip install -r requirements.txt
  ```

+ The CPG is generated by [Joern](https://joern.io/). Since the default Joern settings ignore analysis of *node_modules*, we manually modified the source code of Joern 4.0.227 and release our customized joern-cli at https://drive.google.com/file/d/1g-nJbcdgh13x8XKeF8Q4XuSo0i7Z8P5y/view?usp=sharing, which can be used directly.

+ The call graph generated by [Jelly](https://github.com/cs-au-dk/jelly) 0.10.0, install the Jelly via:

```bash
  npm install -g @cs-au-dk/jelly
  ```
  
  or you can run `jelly/lib/main.js'`  in the jelly_helper.py, if you already have another Jelly version installed. Please refer to the [Jelly](https://github.com/cs-au-dk/jelly) for more details.

- We release the Docker image at https://drive.google.com/file/d/1fvZYUHKmq6NLSRxxqY_AtchxKKBaGAZa/view?usp=sharing containing all the necessities for dynamic analysis. Before running the detector, load the image via:

```bash
  docker load -i dynamic_env.tar
  ```

+ ProfMal leverages [DeepSeek-V3](https://github.com/deepseek-ai/DeepSeek-V3), You can deploy the model on your own server or access it via an API. See llm.py: implement your connection logic in *connect_with_retry*, and set *base_url* in *OpenAI* APi if necessary.

+ Set up the `config.yaml`

```yaml
  joern_path: "./joern-cli-4.0.227/joern-cli" # the path of the joern-cli
  
  sudo_passwd: you_sudo_passwd
  
  LLM: "the_name_of_the_model"
  
  API_KEY: "api_key_of_the_model"
  ```
  
  + Set the *Joern_path* to the joern-cli we provided, make sure the path is correct if you have a global Joern already.
  + The *sudo_passwd* is required to run *chmod* on dynamically executed files, as their file attributes may change after execution in Docker, occasionally leading to permission errors for subsequent processes. If you have a better solution for managing file permissions, feel free to adapt this step.
  + Set the name of the LLM used and the api key to access the model.

## Usage

Run the `main.py` with customized values:

```bash
package_name = "The name of the package"
# package source code
package_dir = "The path of the package"
# workspace for a one package
workspace_dir = "The path of the workspace"
# overwrite the existing joern output
overwrite = False
# dynamic support
dynamic_support = True
# True: Only generate graph, False: Detect maliciousness
graph_only = False
```

+ package_path: The location of the target package. Please ensure the package is unzipped before analysis.

+ The package to be analyzed as follows:

```
    <package-name>/
    └── package/            # REQUIRED subdirectory
        ├── package.json
        ├── code files      # source code
        └── ...
    ```

+ workspace_path: Where Joern and Jelly write their analysis results, and where the behavior graph will be saved.

+ overwrite: If True, remove previous outputs and re-analyze the package; if False, load the previous results from a pickle file in the static or dynamic folder.

+ dynamic_support: If True, include dynamic analysis.

+ graph only: If True, only generate the graph; if False, perform maliciousness detection.

ProfMal

ProfMal Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ProfMal

ProfMal Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README