Merge main

.github/workflows/jingle.yml

@@ -2,53 +2,31 @@ name: jingle
 
 on:
   push:
-    branches:
-      - main
-      - dev
-    paths:
-      - jingle/**
-      - Cargo.lock
-      - Cargo.toml
   pull_request:
-    paths:
-      - jingle/**
-      - Cargo.lock
-      - Cargo.toml
+  workflow_dispatch:
 
 jobs:
-  jingle-build-test:
-    name: Build jingle on Ubuntu
-    runs-on: ubuntu-latest
+  pre_ci:
+    uses: dtolnay/.github/.github/workflows/pre_ci.yml@master
 
+  build:
+    name: ${{matrix.name || format('Rust {0}', matrix.rust)}}
+    needs: pre_ci
+    if: needs.pre_ci.outputs.continue
+    runs-on: ${{matrix.os}}-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        rust: [nightly, beta, stable]
+        os: [ubuntu]
+    env:
+      RUSTFLAGS: --cfg deny_warnings -Dwarnings
+    timeout-minutes: 45
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: true
-      - name: Set up Rust
-        uses: actions-rs/toolchain@v1
+      - uses: dtolnay/rust-toolchain@master
         with:
-          toolchain: stable
-          override: true
-
-      - name: Cache Cargo registry
-        uses: actions/cache@v3
-        with:
-          path: ~/.cargo/registry
-          key: ubuntu-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ubuntu-cargo-registry-
-
-      - name: Cache Cargo build
-        uses: actions/cache@v3
-        with:
-          path: target
-          key: ubuntu-cargo-build-jingle-${{ hashFiles('jingle/**', 'Cargo.lock') }}
-          restore-keys: |
-            ubuntu-cargo-build-jingle-
-
-      - name: Build jingle
-        run: cargo build --manifest-path jingle/Cargo.toml
-
-#      - name: Test jingle
-#        run: cargo test --manifest-path jingle/Cargo.toml
+          toolchain: ${{matrix.rust}}
+      - run: cargo build --all-features --manifest-path jingle_sleigh/Cargo.toml

.github/workflows/jingle_sleigh.yml

@@ -1,63 +1,45 @@
 name: jingle_sleigh
 
+# Stealing the multi-platform CI configuration from
+# https://github.com/dtolnay/cxx/blob/master/.github/workflows/ci.yml
+# for testing build using CXX.
+
 on:
   push:
-    branches:
-      - main
-      - dev
-    paths:
-      - jingle_sleigh/**
-      - Cargo.lock
-      - Cargo.toml
   pull_request:
-    paths:
-      - jingle_sleigh/**
-      - Cargo.lock
-      - Cargo.toml
+  workflow_dispatch:
 
 jobs:
-  jingle_sleigh-build-test:
-    name: Build jingle_sleigh on ${{ matrix.os }}
-    runs-on: ${{ matrix.os }}
+  pre_ci:
+    uses: dtolnay/.github/.github/workflows/pre_ci.yml@master
+
+  build:
+    name: ${{matrix.name || format('Rust {0}', matrix.rust)}}
+    needs: pre_ci
+    if: needs.pre_ci.outputs.continue
+    runs-on: ${{matrix.os}}-latest
     strategy:
+      fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-        rust: [stable]
-
+        rust: [nightly, stable]
+        os: [ubuntu]
+        include:
+          - name: Cargo on macOS
+            rust: nightly
+            os: macos
+          - name: Cargo on Windows (msvc)
+            rust: nightly-x86_64-pc-windows-msvc
+            os: windows
+            flags: /EHsc
+    env:
+      CXXFLAGS: ${{matrix.flags}}
+      RUSTFLAGS: --cfg deny_warnings -Dwarnings
+    timeout-minutes: 45
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: true
-      - name: Install Dependencies (Windows Only)
-        if: matrix.os == 'windows-latest'
-        run: |
-          choco install -y llvm
-
-      - name: Set up Rust
-        uses: actions-rs/toolchain@v1
-        with:
-          toolchain: ${{ matrix.rust }}
-          override: true
-
-      - name: Cache Cargo registry
-        uses: actions/cache@v3
+      - uses: dtolnay/rust-toolchain@master
         with:
-          path: ~/.cargo/registry
-          key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-registry-
-
-      - name: Cache Cargo build
-        uses: actions/cache@v3
-        with:
-          path: target
-          key: ${{ runner.os }}-cargo-build-jingle_sleigh-${{ hashFiles('jingle_sleigh/**', 'Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-build-jingle_sleigh-
-
-      - name: Build jingle_sleigh
-        run: cargo build --manifest-path jingle_sleigh/Cargo.toml
-
-#      - name: Test jingle_sleigh
-#        run: cargo test --manifest-path jingle_sleigh/Cargo.toml
+          toolchain: ${{matrix.rust}}
+      - run: cargo build --all-features --manifest-path jingle_sleigh/Cargo.toml

.github/workflows/style.yml

@@ -2,37 +2,35 @@ name: Style
 
 on:
   push:
-    branches:
-      - main
-      - dev
-    paths:
-      - '**/*.rs'
-      - Cargo.toml
-      - Cargo.lock
   pull_request:
-    paths:
-      - '**/*.rs'
-      - Cargo.toml
-      - Cargo.lock
+  workflow_dispatch:
 
 jobs:
-  lint:
-    name: Fmt and Clippy
-    runs-on: ubuntu-latest
+  pre_ci:
+    uses: dtolnay/.github/.github/workflows/pre_ci.yml@master
 
+  build:
+    name: ${{matrix.name || format('Rust {0}', matrix.rust)}}
+    needs: pre_ci
+    if: needs.pre_ci.outputs.continue
+    runs-on: ${{matrix.os}}-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        rust: [ stable ]
+        os: [ ubuntu ]
+    env:
+      RUSTFLAGS: --cfg deny_warnings -Dwarnings
+    timeout-minutes: 45
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: true
-      - name: Set up Rust
-        uses: actions-rs/toolchain@v1
+      - uses: dtolnay/rust-toolchain@master
         with:
-          toolchain: stable
-          override: true
-
-      - name: Check formatting with cargo fmt
+          toolchain: ${{matrix.rust}}
+          components: clippy, rustfmt
+      - name: cargo fmt
         run: cargo fmt --all -- --check
-
-      - name: Check code with cargo clippy
+      - name: cargo clippy
         run: cargo clippy --all-targets --all-features -- -D warnings

README.md

@@ -30,6 +30,43 @@ related crates:
   expose APIs for constructing or reasoning about control-flow graphs. A more robust analysis
   is forthcoming, depending on my research needs.
 
+## Requirements
+
+### Building
+
+If you're working directly with the `jingle` source distribution,
+you will need to manually download a copy of the `ghidra` source tree
+in order to build `jingle` or `jingle_sleigh`
+
+If you're working with `git`, this can be done using the existing submodule.
+Simply run
+
+```shell
+git submodule init && git submodule update
+```
+
+If you are for some reason using a zipped source distribution,
+then you can run the following:
+
+```shell
+cd jingle_sleigh
+git clone https://github.com/NationalSecurityAgency/ghidra.git
+```
+
+If you are using `jingle` as a cargo `git` or `crates.io` dependency,
+this step is not necessary. `cargo` will handle all this in the `git` case
+and we will vendor the necessary `ghidra` sources into all `crates.io` releases.
+
+### Running
+
+While `jingle` can be configured to work with a single set `sleigh` architecture,
+the default way to use it is to point it to an existing `ghidra` installation.
+[Install ghidra](https://ghidra-sre.org) and, if you are using `jingle` programatically,
+point it at the top level folder of the installation. If you are using the [CLI](./jingle),
+then provide the path to ghidra as an argument in your first run.
+
+The only thing ghidra is used for here is as a standardized folder layout for `sleigh` architectures.
+`jingle` has no ghidra dependency outside of the bundled `sleigh` C++ code.
 ## Usage
 
 In order to use `jingle`, include it in your `Cargo.toml` as usual:

jingle/Cargo.toml

@@ -27,7 +27,8 @@ tracing = "0.1.40"
 clap = { version = "4.5.14", optional = true, features = ["derive"] }
 confy = { version = "0.6.1" , optional = true}
 hex = { version = "0.4.3" , optional = true}
+anyhow = { version = "1.0.95", optional = true }
 [features]
 default = []
-bin_features = ["dep:clap", "dep:confy", "dep:hex"]
+bin_features = ["dep:clap", "dep:confy", "dep:hex", "dep:anyhow"]
 gimli = ["jingle_sleigh/gimli"]

jingle/README.md

@@ -1,4 +1,91 @@
 # `jingle`: Z3 + SLEIGH
 
 `jingle` uses the sleigh bindings provided by `jingle_sleigh` and the excellent
-z3 bindings from the `z3` crate to provide SMT modeling of sequences of `PCODE` instructions
+z3 bindings from the `z3` crate to provide SMT modeling of sequences of `PCODE` instructions.
+
+## CLI
+
+`jingle` exposes a simple CLI tool for disassembling strings of executable bytes and modeling them in logic.
+
+### Installation
+
+From this folder:
+
+```shell
+cargo install --path . --features="bin_features"
+```
+
+This will install `jingle` in your path. Note that 
+
+### Usage
+
+`jingle` requires that a Ghidra installation be present.
+
+When you provide it as the first argument to the `jingle` CLI, it
+will save that path for future usage.
+
+Once it has been configured, you can simple run it as follows:
+
+```shell
+jingle disassemble x86:LE:32:default 89fb
+jingle lift x86:LE:32:default 89fb
+jingle model x86:LE:32:default 89fb
+```
+
+These three invocations will print disassembly, pcode translation, and
+a logical model respectively. None of these, particularly the logical model,
+are intended to be used directly from this utility; this is merely for demonstration.
+The proper way to use this tool is through the API.
+
+The above invocations will produce the following output:
+```shell
+# jingle disassemble x86:LE:32:default 89fb
+MOV EBX,EDI
+```
+
+```shell
+# jingle lift x86:LE:32:default 89fb
+EBX = COPY EDI
+```
+
+```shell
+# jingle model x86:LE:32:default 89fb
+; benchmark generated from rust API
+(set-info :status unknown)
+(declare-fun register!4 () (Array (_ BitVec 32) (_ BitVec 8)))
+(declare-fun register!9 () (Array (_ BitVec 32) (_ BitVec 8)))
+(declare-fun ram!3 () (Array (_ BitVec 32) (_ BitVec 8)))
+(declare-fun ram!8 () (Array (_ BitVec 32) (_ BitVec 8)))
+(declare-fun OTHER!1 () (Array (_ BitVec 64) (_ BitVec 8)))
+(declare-fun OTHER!6 () (Array (_ BitVec 64) (_ BitVec 8)))
+(assert
+ (let ((?x77 (store (store register!4 (_ bv12 32) (select register!4 (_ bv28 32))) (_ bv13 32) (select register!4 (_ bv29 32)))))
+ (let ((?x81 (store (store ?x77 (_ bv14 32) (select register!4 (_ bv30 32))) (_ bv15 32) (select register!4 (_ bv31 32)))))
+ (let (($x82 (= register!9 ?x81)))
+ (let (($x63 (= ram!8 ram!3)))
+ (let (($x62 (= OTHER!6 OTHER!1)))
+ (and $x62 $x63 $x82)))))))
+(check-sat)
+
+```
+
+### Usage string
+
+```shell
+Usage: jingle [GHIDRA_PATH] <COMMAND>
+
+Commands:
+  disassemble    Adds files to myapp
+  lift           
+  model          
+  architectures  
+  help           Print this message or the help of the given subcommand(s)
+
+Arguments:
+  [GHIDRA_PATH]  
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+
+```