Merge branch 'merge-mui-server'

* merge-mui-server: (32 commits)
  [Server] Fix README on usage and installation directions
  [Server] Remove duplicated dependency
  [Server] Add notes about duplicated CLI parsing
  [Server] Support PEP 518 minimum build requirements
  [Server] Use logger for messages
  [Server] Fix linting commands
  [Server] Add CI
  [Server] Manticore black exclude formatting of server
  [Server] Remove test binaries
  [Server] Remove all references to "MUI"
  [Server] Fixes to dependency and project setup
  [Server] Add .gitignore, add missing dev-requirement (#101)
  [Server] Support manual state control (Pause/Kill) (#96)
  [Server] Add explicit field presence (#88)
  [Server] Implement native Unicorn emulate until address (#86)
  [Server] Fix some justfile commands
  Fix broken CI paths, update documentation
  [Server] Add tests for starting execution with hooks
  [Ghidra] Support find/avoid for stateless server
  [Server] Support all hooks as StartNative field
  ...

Author: ekilmer

.github/workflows/ci.yml

@@ -115,6 +115,36 @@ jobs:
       env:
         COVERALLS_PARALLEL: true
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  manticore-server:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.7
+
+      - name: 'Install tools'
+        run: |
+          # just command runner https://github.com/casey/just#pre-built-binaries
+          curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to "${HOME}/.local/bin"
+          sudo wget -O /usr/bin/solc https://github.com/ethereum/solidity/releases/download/v0.4.24/solc-static-linux
+          sudo chmod +x /usr/bin/solc
+
+      - name: 'Lint MUI Server'
+        working-directory: server
+        run: |
+          just init
+          source venv/bin/activate
+          just lint
+
+      - name: 'Test MUI Server'
+        working-directory: server
+        run: |
+          source venv/bin/activate
+          just test
+
   # Send notification when all tests have finished to combine coverage results
   coverage-finish:
     needs: tests

pyproject.toml

@@ -1,3 +1,9 @@
 [tool.black]
 target-version = ['py36']
 line-length = 100
+extend-exclude = '''
+(
+  venv
+  | server # Has its own formatting
+)
+'''

server/.gitignore

@@ -0,0 +1,4 @@
+manticore_server.egg-info/**
+**/__pycache__
+dist/**
+.mypy_cache/**

server/README.md

@@ -0,0 +1,20 @@
+# Manticore Server
+Manticore Server is a gRPC service that acts as a wrapper around  [Manticore](https://github.com/trailofbits/manticore), to support projects like the [Manticore User Interface (MUI)](https://github.com/trailofbits/ManticoreUI). Manticore Server is designed to allow developers to more easily create tools around Manticore that aren't in Python or to allow for Manticore to be run and managed in the cloud/remotely.
+
+❗NOTE❗: The server is not published or packaged anywhere and is intended to be installed from source in a clean Python virtual environment. The server is only tested for compatibility with the version of Manticore living in the parent directory; this version of Manticore is installed when installing the server.
+
+# Usage
+Create a new Python virtual environment:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+
+Install the server with `pip install .`. This will install Manticore from the parent directory.
+
+The Manticore Server can be run via `manticore_server`, and it will run on port `50010`.
+
+Your Manticore Server client will require the relevant gRPC client code. You can find out how to generate gRPC client code in your desired language from [the gRPC website](https://grpc.io/docs/languages/).
+
+You may refer to the [Protobuf Specification](manticore_server/ManticoreServer.proto) for information about the RPC services provided and the message types.

server/justfile

@@ -0,0 +1,25 @@
+init:
+  test -d venv || python3 -m venv venv
+  . venv/bin/activate; pip install -U setuptools pip wheel; pip install -e .[dev]
+
+format:
+  black .
+  isort .
+
+lint:
+  black --check .
+  isort --check .
+  mypy
+
+generate:
+  python3 setup.py generate
+
+build: generate
+  #!/usr/bin/env bash
+  set -euo
+  mkdir -p dist
+  py_ver=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
+  python3 -m shiv -c manticore_server -o dist/manticore_server --reproducible --no-modify --python "/usr/bin/env python${py_ver}" --compressed .
+
+test:
+  python3 -m unittest tests/test_*.py

server/manticore_server/ManticoreServer.proto

@@ -0,0 +1,107 @@
+syntax = "proto3";
+
+package manticore_server;
+
+service ManticoreServer {
+    rpc StartNative(NativeArguments) returns (ManticoreInstance) {}
+    rpc StartEVM(EVMArguments) returns (ManticoreInstance) {}
+    rpc Terminate(ManticoreInstance) returns (TerminateResponse) {}
+    rpc GetStateList(ManticoreInstance) returns (ManticoreStateList) {}
+    rpc GetMessageList(ManticoreInstance) returns (ManticoreMessageList) {}
+    rpc CheckManticoreRunning(ManticoreInstance) returns (ManticoreRunningStatus) {}
+    rpc StopServer(StopServerRequest) returns (StopServerResponse) {}
+    rpc ControlState(ControlStateRequest) returns (ControlStateResponse) {}
+}
+
+// LogMessage and StateList message types have "Manticore" in their names to distinguish them from those in mserialize
+
+message ManticoreLogMessage {
+    string content = 1;
+}
+
+message ManticoreMessageList {
+    repeated ManticoreLogMessage messages = 2;
+}
+
+message ManticoreState {
+    int32 state_id = 3;
+    uint64 pc = 10;
+    optional int32 parent_id = 28;
+    repeated int32 children_ids = 29;
+}
+
+message ManticoreStateList {
+
+    // state categories in Manticore - based on manticore enums StateStatus and StateList
+    repeated ManticoreState active_states = 4;
+    repeated ManticoreState waiting_states = 5;
+    repeated ManticoreState forked_states = 6;
+    repeated ManticoreState errored_states = 7;
+    repeated ManticoreState complete_states = 8;
+    repeated ManticoreState paused_states = 33;
+}
+
+message ManticoreInstance {
+    string uuid = 9;
+}
+
+message TerminateResponse {}
+
+message Hook {
+
+    enum HookType {
+        FIND = 0;
+        AVOID = 1;
+        CUSTOM = 2;
+        GLOBAL = 3;
+    }
+
+    optional uint64 address = 26;
+    HookType type = 27;
+    optional string func_text = 31;
+}
+
+message NativeArguments {
+    string program_path = 11;
+    repeated string binary_args = 16;
+    repeated string envp = 17;
+    repeated string symbolic_files = 18;
+    optional string concrete_start = 19;
+    optional string stdin_size = 20;
+    optional string additional_mcore_args = 21;
+    repeated Hook hooks = 30;
+    optional uint64 emulate_until = 32;
+}
+
+message EVMArguments {
+    string contract_path = 12;
+    string contract_name = 13;
+    string solc_bin = 14;
+    optional string tx_limit = 22;
+    optional string tx_account = 23;
+    repeated string detectors_to_exclude = 24;
+    optional string additional_flags = 25;
+}
+
+message ManticoreRunningStatus {
+    bool is_running = 15;
+}
+
+message StopServerRequest {}
+
+message StopServerResponse {}
+
+message ControlStateRequest {
+
+    enum StateAction {
+        RESUME = 0;
+        PAUSE = 1;
+        KILL = 2;
+    }
+
+    int32 state_id = 34;
+    ManticoreInstance manticore_instance = 35;
+    StateAction action = 36;
+}
+
+message ControlStateResponse {}