Update docs and fix docker mcsema-disass (#690)

* Fix mcsema-disass tool in final Docker image

* Update some README instructions

* Update more documentation

* Test that the disassembler has at least runtime dependencies to show help message

.github/workflows/ci.yml

@@ -34,7 +34,9 @@ jobs:
         echo ${{needs.VersionFile.outputs.version}} > VERSION
         docker build . -t docker.pkg.github.com/lifting-bits/mcsema/mcsema-llvm${{ matrix.llvm }}-ubuntu${{ matrix.ubuntu }}-amd64:latest -f Dockerfile --build-arg UBUNTU_VERSION=${{ matrix.ubuntu }} --build-arg ARCH=amd64 --build-arg LLVM_VERSION=${{ matrix.llvm }}
     - name: Test final Docker image
-      run: docker run --rm docker.pkg.github.com/lifting-bits/mcsema/mcsema-llvm${{ matrix.llvm }}-ubuntu${{ matrix.ubuntu }}-amd64:latest --version
+      run: |
+        docker run --rm docker.pkg.github.com/lifting-bits/mcsema/mcsema-llvm${{ matrix.llvm }}-ubuntu${{ matrix.ubuntu }}-amd64:latest --version
+        docker run --rm --entrypoint=mcsema-disass docker.pkg.github.com/lifting-bits/mcsema/mcsema-llvm${{ matrix.llvm }}-ubuntu${{ matrix.ubuntu }}-amd64:latest --help
     - name: Push Image for LLVM ${{ matrix.llvm }} on ${{ matrix.ubuntu }}
       if: github.event_name == 'push' && github.ref == 'refs/heads/master'
       run: |

Dockerfile

@@ -5,13 +5,22 @@ ARG DISTRO_BASE=ubuntu${UBUNTU_VERSION}
 ARG BUILD_BASE=ubuntu:${UBUNTU_VERSION}
 ARG LIBRARIES=/opt/trailofbits/libraries
 
+# Using this file:
+# 1. Clone the mcsema repo https://github.com/lifting-bits/mcsema
+# 2. docker build -t=mcsema .
+# To run the lifter
+# 3. docker run --rm -it --ipc=host -v "${PWD}":/home/user/local mcsema
+# To run the disassembler
+# 4. docker run --rm --entrypoint=mcsema-disass -it --ipc=host -v "${PWD}":/home/user/local mcsema
 
 # Run-time dependencies go here
 FROM ${BUILD_BASE} as base
 ARG UBUNTU_VERSION
 ARG LIBRARIES
 RUN apt-get update && \
-    apt-get install -qqy --no-install-recommends zlib1g && \
+    apt-get install -qqy --no-install-recommends python2.7 zlib1g curl ca-certificates && \
+    curl https://bootstrap.pypa.io/get-pip.py --output get-pip.py && python2.7 get-pip.py && \
+    update-alternatives --install /usr/bin/python2 python2 /usr/bin/python2.7 1 && \
     if [ "${UBUNTU_VERSION}" = "18.04" ] ; then \
       apt-get install -qqy --no-install-recommends libtinfo5 ; \
     else \
@@ -49,13 +58,6 @@ WORKDIR /mcsema
 
 # Source code build
 FROM deps as build
-# Using this file:
-# 1. wget https://raw.githubusercontent.com/trailofbits/mcsema/master/tools/Dockerfile
-# 2. docker build -t=mcsema .
-# 3. docker run --rm -it --ipc=host -v "${PWD}":/home/user/local mcsema
-
-# If using IDA for CFG recovery, uncomment the following line:
-# RUN sudo dpkg --add-architecture i386 && sudo apt-get install zip zlib1g-dev:i386 -y
 
 COPY . ./
 
@@ -75,18 +77,6 @@ RUN mkdir -p build && \
 RUN cd test_suite && \
     PATH="/opt/trailofbits/mcsema/bin:${PATH}" python2.7 start.py
 
-
-
-################################
-# Left to reader to install    #
-#  their disassembler (IDA/BN) #
-################################
-# But, as an example:
-# ADD local-relative/path/to/binaryninja/ /root/binaryninja/
-# ADD local-relative/path/to/.binaryninja/ /root/.binaryninja/ # <- Make sure there's no `lastrun` file
-# RUN /root/binaryninja/scripts/linux-setup.sh
-
-
 FROM base as dist
 ARG LLVM_VERSION
 
@@ -98,5 +88,15 @@ COPY --from=build /opt/trailofbits/anvill /opt/trailofbits/anvill
 COPY --from=build /opt/trailofbits/mcsema /opt/trailofbits/mcsema
 COPY scripts/docker-lifter-entrypoint.sh /opt/trailofbits/mcsema
 ENV LLVM_VERSION=llvm${LLVM_VERSION} \
-    PATH="/opt/trailofbits/mcsema/bin:${PATH}"
+    PATH="/opt/trailofbits/mcsema/bin:${PATH}" \
+    PYTHONPATH="/opt/trailofbits/mcsema/lib/python2.7/site-packages"
 ENTRYPOINT ["/opt/trailofbits/mcsema/docker-lifter-entrypoint.sh"]
+
+################################
+# Left to reader to install    #
+#  their disassembler (IDA/BN) #
+################################
+# But, as an example:
+# ADD local-relative/path/to/binaryninja/ /root/binaryninja/
+# ADD local-relative/path/to/.binaryninja/ /root/.binaryninja/ # <- Make sure there's no `lastrun` file
+# RUN /root/binaryninja/scripts/linux-setup.sh

README.md

@@ -89,11 +89,14 @@ Why would anyone translate binaries *back* to bitcode?
 
 ### Docker
 
-#### Step 1: Download Dockerfile
+#### Step 1: Clone the repo
 
-`wget https://raw.githubusercontent.com/lifting-bits/mcsema/master/tools/Dockerfile`
+```bash
+git clone https://github.com/lifting-bits/mcsema
+cd mcsema
+```
 
-#### Step 2: Add your disassembler
+#### Step 2: Add your disassembler to the Dockerfile
 
 Currently IDA, Binary Ninja, and Dyninst are supported for control-flow recovery, it's left as an exercise to the reader to install your disassembler of choice, but an example of installing Binary Ninja is provided (remember for Docker that paths need to be relative to where you built from):
 ```
@@ -115,8 +118,10 @@ ARCH=amd64; UBUNTU=18.04; LLVM=800; docker build . \
   --build-arg LLVM_VERSION=${LLVM} \
   --build-arg ARCH=${ARCH}
 
-# run mcsema container
+# run mcsema container lifter
 docker run --rm -it --ipc=host -v "$(pwd)":/mcsema/local mcsema:llvm${LLVM}-ubuntu{$UBUNTU}-${ARCH}
+# run mcsema container disassembler
+docker run --rm -it --entrypoint=mcsema-disass --ipc=host -v "$(pwd)":/mcsema/local mcsema:llvm${LLVM}-ubuntu{$UBUNTU}-${ARCH}
 ```
 
 ### Native Build On Linux