Merge pull request #63 from FuzzingLabs/feat/cli_ast_cmd

Feat/cli ast cmd

Author: MohaFuzzingLabs

.github/workflows/deploy-mdbook.yml

@@ -0,0 +1,31 @@
+name: Deploy mdBook to GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Install mdBook
+        run: |
+          mkdir -p $HOME/.cargo/bin
+          curl -L https://github.com/rust-lang/mdBook/releases/download/v0.4.30/mdbook-v0.4.30-x86_64-unknown-linux-gnu.tar.gz | tar xvz -C $HOME/.cargo/bin
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      - name: Build mdBook
+        run: mdbook build docs
+
+      - name: Deploy to GitHub Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs/book # Default output folder for mdBook
+          branch: gh-pages

GEMINI.md

@@ -0,0 +1,79 @@
+# GEMINI AI Agent: Contributor Guidelines for sol-azy
+
+This document outlines the operational guidelines, development workflow, and quality standards for a GEMINI AI agent contributing to the `sol-azy` project. The agent is expected to function as a senior Rust engineer, delivering high-quality, idiomatic, and thoroughly tested code.
+
+## 1. Core Principles
+
+As a senior engineer on this project, you are expected to embody the following principles:
+
+*   **Quality First:** All contributions must be well-designed, robust, and maintainable. Code should be clean, idiomatic, and adhere to Rust best practices.
+*   **Deep Understanding:** Do not rush into coding. Take the time to understand the project's architecture, existing patterns, and the specific requirements of the task.
+*   **Proactive Ownership:** Independently identify challenges, research solutions, and take full ownership of the development lifecycle, from understanding the task to ensuring its successful integration.
+
+## 2. Project Overview
+
+*   **Purpose:** `sol-azy` is a CLI tool for Solana auditors, focusing on reverse engineering and static analysis.
+*   **Tech Stack:**
+    *   **Language:** 100% Rust.
+    *   **Documentation:** `mdbook` in the `docs/` directory.
+    *   **Scripting/Rules Engine:** `starlark-rs` for defining analysis rules with Python-like syntax.
+
+## 3. Onboarding Checklist
+
+Before your first contribution, complete the following steps to familiarize yourself with the project:
+
+1.  [ ] **Read the Introduction:** Start with `docs/src/introduction.md`.
+2.  [ ] **Understand the Architecture:** Review `docs/src/architecture.md` for a high-level system design.
+3.  [ ] **Learn CLI Usage:** Read `docs/src/cli_usage.md` to understand the tool's user-facing functionality.
+4.  [ ] **Study Rule Development:** The `docs/src/rules/` directory is critical. Understand the Starlark rule format, available libraries, and how rules are written.
+5.  [ ] **Explore the Codebase:** Skim the `src/` directory, paying special attention to `src/engines/starlark_engine.rs` to see how Starlark integrates with the Rust code.
+
+## 4. The Development Workflow
+
+Follow this structured workflow for every task or feature.
+
+### Step 1: Understand the Task
+- Deconstruct the request. If anything is unclear, ask for clarification.
+- Identify the core problem you need to solve.
+
+### Step 2: Explore & Research
+- **Documentation First:** Always begin by searching the project's `docs/` for relevant information. The documentation is the primary source of truth.
+- **Codebase Exploration:** Use `list_directory`, `glob`, and `read_file` to study existing modules, data structures, and functions. Look for similar implementations to maintain consistency.
+- **External Research:** If the project's resources are insufficient, use `search_web` to find information on:
+    - Rust language features or library usage.
+    - `starlark-rs` API and patterns.
+    - Relevant Solana development concepts.
+
+### Step 3: Implement
+- **Write Idiomatic Rust:** Adhere to Rust best practices, focusing on safety, performance, and clarity.
+- **Follow Existing Patterns:** Ensure your code is consistent with the surrounding codebase.
+- **Develop Starlark Rules:** When writing Starlark rules, refer to `docs/src/rules/` and existing rules in `rules/syn_ast/`. Use the provided Starlark libraries correctly.
+
+### Step 4: Verify & Test
+This is a non-negotiable step. High-quality code is tested code.
+
+1.  **Format:** Run `cargo fmt` to ensure consistent code style.
+2.  **Check:** Run `cargo check` for fast compilation checks.
+3.  **Lint:** Run `cargo clippy` to catch common mistakes and style issues. Address all warnings.
+4.  **Test:**
+    *   Write **unit tests** for new logic within the relevant module.
+    *   Add **integration tests** in the `tests/` directory for end-to-end functionality.
+    *   Run `cargo test` to execute the full test suite and ensure no regressions were introduced.
+
+### Step 5: Document & Commit
+- **Update Documentation:** If your changes affect user-facing functionality, the architecture, or the rule system, update the corresponding `mdbook` documentation in the `docs/` directory.
+- **Write Meaningful Commit Messages:** Follow the **Conventional Commits** specification. This helps maintain a clear and automated version history.
+    - **Format:** `<type>[optional scope]: <description>`
+    - **Example:** `feat(analysis): add new detector for insecure delegatecall`
+    - **Common types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`.
+
+## 5. Debugging Guide
+
+If you encounter an error or unexpected behavior:
+
+1.  **Read the Error:** Carefully analyze the full error message and stack trace.
+2.  **Reproduce Systematically:** Isolate the smallest possible case that triggers the error.
+3.  **Hypothesize:** Form a hypothesis about the root cause.
+4.  **Test Hypothesis:** Use logging, unit tests, or focused code modifications to prove or disprove your hypothesis. Iterate until the issue is resolved.
+
+By adhering to these guidelines, you will contribute effectively to `sol-azy` and uphold the standards of a senior Rust engineer.

README.md

@@ -61,7 +61,7 @@ cargo run -- sast --target-dir ./my_project --rules-dir ./rules/
 cargo run -- reverse --mode both --out-dir ./out --bytecodes-file ./program.so --labeling --reduced
 ```
 
-### Fetch deployed bytecode from mainnet
+### Fetch deployed bytecode from the mainnet
 
 ```bash
 cargo run -- fetcher --program-id <PROGRAM_ID> --out-dir ./out/
@@ -77,13 +77,22 @@ cargo run -- dotting -c functions.json -r reduced.dot -f full.dot
 
 ## Documentation
 
-The project includes a full [mdBook documentation](https://github.com/FuzzingLabs/sol-azy/tree/master/docs):
+The project includes full [mdBook documentation](https://github.com/FuzzingLabs/sol-azy/tree/master/docs):
+
+### Serve the docs
 
 ```bash
 cd book
 mdbook serve
 ```
 
+### Build the docs
+
+```bash
+cd book
+mdbook build
+```
+
 ---
 
 ## License
@@ -98,8 +107,8 @@ If you have any questions, suggestions, or need support:
 
 - Feel free to [open an issue](https://github.com/FuzzingLabs/sol-azy/issues).
 - You can also reach out directly to _(responses may take longer than issue depending on individual availability)_:
-  - [FuzzingLabs](https://x.com/FuzzingLabs)
-  - [MohaFuzzingLabs](https://github.com/MohaFuzzingLabs)
-  - [Ectario](https://x.com/Ectari0)
+    - [FuzzingLabs](https://x.com/FuzzingLabs)
+    - [MohaFuzzingLabs](https://github.com/MohaFuzzingLabs)
+    - [Ectario](https://x.com/Ectari0)
 
 We're happy to help and value community engagement!

docs/src/SUMMARY.md

@@ -11,6 +11,7 @@
   - [Rule Format](rules/format.md)
   - [Writing Templates](rules/templates.md)
   - [Detection Example](rules/example.md)
+  - [Starlark references](rules/starlark_libs.md)
 - [Reverse Engineering](reverse.md)
   - [Overview](reverse/overview.md)
   - [Disassembly](reverse/disassembly.md)
@@ -20,3 +21,5 @@
     - [Manual CFG Editing (Dotting)](reverse/dotting.md)
 - [Architecture](architecture.md)
   - [App State](architecture/app_state.md)
+  - [SAST Engine](architecture/sast_engine.md)
+- [Evolution of the tool](future.md)

docs/src/architecture.md

@@ -170,7 +170,7 @@ This feature is useful for audits where source code is unavailable or unverifiab
 
 ## External Dependencies
 
-- [sbpf-solana (anza-xyz)](https://github.com/anza-xyz/sbpf-solana): Disassembly / Analysis core
+- [`sbpf-solana (anza-xyz)`](https://github.com/anza-xyz/sbpf-solana): Disassembly / Analysis core
 - [`syn`](https://docs.rs/syn): Source AST parsing
 - [`starlark-rust`](https://github.com/facebook/starlark-rust): Rule evaluation engine
 

docs/src/architecture/app_state.md

@@ -7,7 +7,7 @@ It coordinates the execution of commands like `build`, `sast` and `reverse`, and
 
 ## Where It Lives
 
-File: `src/state/app_state.rs`]
+File: `src/state/app_state.rs`
 
 ---
 

docs/src/architecture/sast_engine.md

@@ -0,0 +1 @@
+# `SastEngine` Architecture

docs/src/future.md

@@ -0,0 +1,11 @@
+# Evolution of sol-azy
+
+**Sol-azy** is currently in development, and we have few ideas for new features.
+
+## Static analysis
+
+### Enhance Starlark libraries
+
+### Support MIR
+
+

docs/src/rules/starlark_libs.md

@@ -0,0 +1,83 @@
+# Starlark Libraries References
+
+## AST Node Structure
+
+An AST node represents a single element in the Abstract Syntax Tree with a standardized structure. Each node contains: a
+`raw_node` with the original AST data, an `access_path` string representing the node's location in the tree, `metadata`
+for additional information like position and mutability flags, `children` and `parent` references for tree navigation,
+`ident` for the node's identifier, and optional fields like `args` for function arguments and `root` to indicate if it's
+a root node. This consistent structure facilitates tree traversal and pattern matching operations throughout the
+codebase.
+
+```python
+{
+    "raw_node": {},   # Original AST data from parser
+    "access_path": "",# Path string showing location in tree (e.g. "root.expr.binary.left")
+    "metadata": {},   # Additional data like position and mutability flags
+    "children": [],   # List of child nodes
+    "parent": {},     # Reference to parent node
+    "root": False,    # Boolean indicating if this is a root node
+    "args": [],       # Function arguments (if applicable)
+    "ident": ""       # Node identifier/name
+}
+```
+
+## Syn AST Utilities
+
+The Syn AST utilities module provides functions for working with Rust's syntactic ASTs, particularly for security
+analysis. 
+
+### Core Components
+
+#### Constants
+
+- `EMPTY_ACCESS_PATH`, `EMPTY_IDENT`, `EMPTY_METADATA`, `EMPTY_NODE`: Default values for empty nodes
+
+#### Node Management
+
+- `new_ast_node(syn_ast_node, metadata, access_path)`: Creates a new AST node
+- `ast_node_add_child(node, child)`: Adds a child to an AST node
+- `ast_node_add_children(node, children)`: Adds multiple children to an AST node
+- `to_result(node)`: Converts a node to a result format
+- `filter_result(result)`: Filters duplicate results
+
+#### Tree Traversal
+
+- `traverse_tree(node, collector)`: Traverses a tree with a collector function
+- `flatten_tree(root)`: Flattens a tree into a list of nodes
+- `first(nodes)`: Returns the first node from a list
+
+#### Node Finding Functions
+
+- `find_by_child(self, child_ident)`: Finds nodes by child identifier
+- `find_chained_calls(self, *idents)`: Finds chained method calls
+- `find_macro_attribute_by_names(self, *idents)`: Finds macro attributes by name
+- `find_by_similar_access_path(self, access_path, stop_keyword)`: Finds nodes with similar access paths
+- `find_comparisons(self, ident1, ident2)`: Finds comparisons between two identifiers
+- `find_comparison_to_any(self, ident)`: Finds comparisons involving a specific identifier
+- `find_functions_by_names(self, *function_names)`: Finds functions by name
+- `find_by_names(self, *idents)`: Finds nodes by identifier names
+- `find_method_calls(self, caller, method)`: Finds method calls on a specific caller
+- `find_assignments(self, ident, value_ident)`: Finds assignment operations
+- `find_mutables(self)`: Finds mutable variables
+- `find_account_typed_nodes(self, ident)`: Finds account-typed nodes
+- `find_member_accesses(self, ident)`: Finds member accesses for a specific identifier
+
+#### AST Preparation
+
+- `find_ident_src_node(sub_data, sub_access_path, metadata)`: Finds identifier source nodes
+- `find_fn_names(node)`: Extracts function names from an AST
+- `find_raw_nodes_by_fn_names(node, func_names)`: Finds raw nodes by function names
+- `find_raw_nodes(ast)`: Finds all raw nodes in an AST
+- `prepare_syn_ast(ast, access_path, parent)`: Prepares a Syn AST for analysis
+- `prepare_ast(ast)`: Main function to prepare an AST for analysis
+
+### Usage Examples
+
+For finding specific code patterns:
+
+```python
+```
+
+This documentation provides an overview of the functionality available in these Starlark libraries, which are designed
+for security analysis of Solana programs by detecting specific code patterns in their AST representations.

docs/src/static_analysis.md

@@ -39,4 +39,11 @@ The rule engine gives you access to:
 ## Related Pages
 
 - 📘 [How to write Rules](rules/format.md)
-- ✅ [Use case example](rules/example.md) 
+- ✅ [Use case example](rules/example.md) 
+
+## Note
+
+The sast engineering core in Sol-azy is based on the excellent open-source project  
+[`radar`](https://github.com/Auditware/radar) by [Auditware)](https://github.com/Auditware).
+
+We've been heavily inspired by their approach and wanted a standalone binary capable of it.