Merge pull request #2 from Veridise/dev

Updated tool infrastructure

.github/workflows/dev.yml

@@ -0,0 +1,119 @@
+name: Dev CI
+
+on:
+    push:
+        branches: [ "main", "dev" ]
+    pull_request:
+        branches: [ "main", "dev" ]
+    workflow_dispatch:
+
+jobs:
+    environment-test:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.12'
+            - name: install dependencies
+              run: |
+                pip install networkx[default]
+                pip install beautifulsoup4
+                pip install pandas
+                pip install antlr4-tools
+                pip install antlr4-python3-runtime==4.13.1
+                antlr4 -v 4.13.1
+            - name: test hello.py
+              run: python tests/scripts/hello.py
+            - name: test dep.py
+              run: python tests/scripts/dep.py
+
+    parser-test:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.12'
+            - name: install dependencies
+              run: |
+                pip install networkx[default]
+                pip install beautifulsoup4
+                pip install pandas
+                pip install antlr4-tools
+                pip install antlr4-python3-runtime==4.13.1
+                antlr4 -v 4.13.1
+            - name: test parsing.py
+              run: PYTHONPATH="./" python ./tests/scripts/parsing.py
+
+    detector-test-divz:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.12'
+            - name: install dependencies
+              run: |
+                pip install networkx[default]
+                pip install beautifulsoup4
+                pip install pandas
+                pip install antlr4-tools
+                pip install antlr4-python3-runtime==4.13.1
+                antlr4 -v 4.13.1
+            - name: test divz
+              run: PYTHONPATH="./" python ./tests/scripts/test-divz.py
+
+    detector-test-infoleak:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.12'
+            - name: install dependencies
+              run: |
+                pip install networkx[default]
+                pip install beautifulsoup4
+                pip install pandas
+                pip install antlr4-tools
+                pip install antlr4-python3-runtime==4.13.1
+                antlr4 -v 4.13.1
+            - name: test infoleak
+              run: PYTHONPATH="./" python ./tests/scripts/test-infoleak.py
+
+    detector-test-rtcnst:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.12'
+            - name: install dependencies
+              run: |
+                pip install networkx[default]
+                pip install beautifulsoup4
+                pip install pandas
+                pip install antlr4-tools
+                pip install antlr4-python3-runtime==4.13.1
+                antlr4 -v 4.13.1
+            - name: test rtcnst
+              run: PYTHONPATH="./" python ./tests/scripts/test-rtcnst.py
+
+    detector-test-unused:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.12'
+            - name: install dependencies
+              run: |
+                pip install networkx[default]
+                pip install beautifulsoup4
+                pip install pandas
+                pip install antlr4-tools
+                pip install antlr4-python3-runtime==4.13.1
+                antlr4 -v 4.13.1
+            - name: test unused
+              run: PYTHONPATH="./" python ./tests/scripts/test-unused.py

.gitignore

@@ -1,24 +1,3 @@
-.DS_Store
-
-# ====================== #
-# ======== Rust ======== #
-# ====================== #
-
-# Generated by Cargo
-# will have compiled files and executables
-debug/
-target/
-
-# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
-# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
-Cargo.lock
-
-# These are backup files generated by rustfmt
-**/*.rs.bk
-
-# MSVC Windows builds of rustc generate these, which store debugging information
-*.pdb
-
 # ======================== #
 # ======== Python ======== #
 # ======================== #
@@ -182,4 +161,11 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+#.idea/
+
+# ===================================== #
+# ======== customized override ======== #
+# ===================================== #
+.DS_Store
+# exclude aleo build for benchmarks
+!tests/public/**/build/

README.md

@@ -6,40 +6,36 @@ This repo hosts an open-source Python branch of the static analysis tool Vanguar
 
 The following libraries are required for running (different components of) the tool:
 
-- Rust (1.73+) for running `aleo2json`
 - Python (3.10+) for running Vanguard and its Aleo detectors
-  - [NetworkX](https://networkx.org/documentation/stable/install.html) (2.8.4+) for speeding up graph reachability in detectors
+  - [NetworkX](https://networkx.org/documentation/stable/install.html) (3.2.1+) for speeding up graph reachability in detectors
+  - [Antlr](https://www.antlr.org/) (4.13.1) and its Python binding for loading and parsing Aleo programs
+    - `pip install antlr4-python3-runtime==4.13.1`
+    - `pip install antlr4-tools`
+  - [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/) (4.12.2+) for crawling benchmarks from public explorers in test suite
+  - [pandas](https://pandas.pydata.org/)  (2.1.4+) for data analysis in test suite
 - <u>Leo (**7ac50d8**) for compiling and running all benchmarks enclosed</u>
+  - The tools is tested under this version, but newer version of Lao may also work.
 
-## The Aleo to JSON Compiler
-
-Running of Vanguard for Aleo relies on a compiler that converts Aleo programs into JSON, which allows the program to be further analyzed by various tools and extensions. It's adapted from Aleo's [snarkVM](https://github.com/AleoHQ/snarkVM/). To allow Vanguard to directly process Aleo programs, we recommend installing the compiler while testing out the tool via:
-
-```bash
-git clone https://github.com/Veridise/aleo2json.git
-cd aleo2json/
-cargo install --path . --bin aleo2json
-```
-
-To remove it in the future, simply do:
+## Vanguard for Aleo
 
-```bash
-cargo uninstall -p snarkvm --bin aleo2json
-```
+The library of Vanguard for Aleo provides common vulnerability detectors and basic utilities for writing detectors based on static analysis. To use the tool, you can call it directly from the repo or install it as a library.
 
-### Usage
+### Calling from Source
 
-The `aleo2json` tool takes as input a path to `*.aleo` file, and directly outputs the compiled JSON, which includes enhanced information of the program and basic analysis results (e.g., variable types, visibilities, etc.):
+To call the detectors directly from source code, first make sure all prerequisites are satisfied, and call from the repo root directly:
 
-```bash
-aleo2json <path-to-aleo-file>
+```python
+from .vanguard.aleo.grammar import AleoEnvironment
+from .vanguard.aleo.detectors import detector_divz
+
+project_name = "divz0"
+function_name = "ex1"
+build_path = f"./tests/public/{project_name}/build/"
+env = AleoEnvironment(build_path) # load project
+detector_divz(env, env.main.id, function_name, readable=True) # detect
 ```
 
-## Vanguard for Aleo
-
-The library of Vanguard for Aleo provides both integration with the `aleo2json` tool, as well as basic utilities for writing detectors based on static analysis. We've also included detectors for several common vulnerabilities.
-
-### Library Usage
+### Calling as Library
 
 The analyzer can be installed via `pip` setup tools by running:
 
@@ -53,43 +49,57 @@ and if you want to remove it:
 pip uninstall vanguard
 ```
 
-You can write detectors by simply utilizing some functions provided by the analyzer. Here's an example that analyze and get all public outputs/signals from a given Aleo program:
+You can write detectors by simply utilizing some functions provided by the analyzer. Here's an example that loads a project called `divz0` and call the division-by-zero detector:
 
 ```python
-from vanguard.aleo.common import aleo2json
-from vanguard.aleo.detectors.divz import detector_divz
-
-aleo_path = ...
-aleo_json = aleo2json(aleo_path)
-
-out, info = detector_divz(ap, "main")
+from vanguard.aleo.grammar import AleoEnvironment
+from vanguard.aleo.detectors import detector_divz
+
+project_name = "divz0"
+function_name = "ex1"
+build_path = f"./tests/public/{project_name}/build/"
+env = AleoEnvironment(build_path) # load project
+detector_divz(env, env.main.id, function_name, readable=True) # detect
 ```
 
 ## Detectors Available
 
 ```python
-from vanguard.aleo.detectors.infoleak import detector_infoleak
-from vanguard.aleo.detectors.rtcnst import detector_rtcnst
-from vanguard.aleo.detectors.unused import detector_unused
-from vanguard.aleo.detectors.divz import detector_divz
-
+from vanguard.aleo.detectors import detector_infoleak
+from vanguard.aleo.detectors import detector_rtcnst
+from vanguard.aleo.detectors import detector_unused
+from vanguard.aleo.detectors import detector_divz
 ...
 ```
 
-(more coming soon...)
+(More coming soon...)
 
 ## Example Leo/Aleo Vulnerabilities
 
-You can find examples showing Leo/Aleo vulnerabilities with comments and annotations in projects in `tests/`:
+You can find examples showing Leo/Aleo vulnerabilities with comments and annotations in projects in `tests/public/`:
+
+| Project     | Vulnerability Description     |
+| ----------- | ----------------------------- |
+| divrd0/     | Division truncation/rounddown |
+| divz0/      | Division by zero              |
+| downcast0/  | Type downcast                 |
+| infoleak0/  | Information leakage           |
+| overflow0/  | Arithmetic overflow           |
+| rtcnst0/    | Returning constant            |
+| underflow0/ | Arithmetic underflow          |
+| unused0/    | Unused variable/signal        |
+
+## Parser/Lexer Generation
+
+In case the parser is not compatible with your environment, you can generate it again using Antlr:
+
+```bash
+cd ./vanguard/aleo/parser/
+antlr4 -v 4.13.1 -Dlanguage=Python3 ./Aleo.g4
+```
+
+The parser/lexer file is located in `./vanguard/aleo/parser/Aleo.g4`.
 
-| Project     | Vulnerability Description               |
-| ----------- | --------------------------------------- |
-| divrd0/     | Division round-down/truncation (part 0) |
-| divz0/      | Division by zero (part 0)               |
-| downcast0/  | Division downcast (part 0)              |
-| infoleak0/  | Information leakage (part 0)            |
-| overflow0/  | Arithmetic overflow (part 0)            |
-| rtcnst0/    | Returning constant (part 0)             |
-| underflow0/ | Arithmetic underflow (part 0)           |
-| unused0/    | Unused variable/signal (part 0)         |
+## Test Suite and Static Analysis APIs
 
+(Coming soon...)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vanguard"
-version = "0.0.1"
+version = "0.0.2"
 authors = [
   { name="Yanju Chen", email="yanju@veridise.com" },
 ]
@@ -13,5 +13,13 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 
+dependencies = [
+    "networkx[default]>=3.2.1",
+    "beautifulsoup4>=4.12.2",
+    "antlr4-python3-runtime==4.13.1",
+    "pandas>=2.1.4",
+    "antlr4-tools",
+]
+
 [project.urls]
 "Homepage" = "https://veridise.com/"

tests/public/divrd0/build/main.aleo

@@ -0,0 +1,50 @@
+program divrd0.aleo;
+
+
+
+function vanguard_helper:
+    cast  true true false true false true true into r0 as [boolean; 7u32];
+    output r0 as [boolean; 7u32].private;
+
+
+function ex0:
+    div 225u8 16u8 into r0;
+    output r0 as u8.private;
+
+
+function ex1:
+    div 15u8 2u8 into r0;
+    mul r0 2u8 into r1;
+    output r1 as u8.private;
+
+
+function ex2:
+    div 16u8 2u8 into r0;
+    mul r0 2u8 into r1;
+    output r1 as u8.private;
+
+
+function ex3:
+    input r0 as u8.private;
+    div r0 2u8 into r1;
+    mul r1 2u8 into r2;
+    output r2 as u8.private;
+
+
+function ex4:
+    mul 15u8 2u8 into r0;
+    div r0 2u8 into r1;
+    output r1 as u8.private;
+
+
+function ex5:
+    input r0 as u8.private;
+    mul r0 2u8 into r1;
+    div r1 2u8 into r2;
+    output r2 as u8.private;
+
+
+function ex6:
+    mul 15u8 2u8 into r0;
+    div r0 9u8 into r1;
+    output r1 as u8.private;

tests/public/divrd0/build/program.json

@@ -0,0 +1,6 @@
+{
+    "program": "divrd0.aleo",
+    "version": "0.0.0",
+    "description": "",
+    "license": "MIT"
+}

tests/public/divz0/build/imports/helpers.aleo

@@ -0,0 +1,9 @@
+program helpers.aleo;
+
+
+
+function division:
+    input r0 as u8.private;
+    input r1 as u8.private;
+    div r0 r1 into r2;
+    output r2 as u8.private;