diff --git a/TESTING.md b/TESTING.md index 5755e6253..4674e565b 100644 --- a/TESTING.md +++ b/TESTING.md @@ -4,7 +4,6 @@ Pwntools makes extensive use of unit tests and integration tests to ensure every ## Test Suite - To run the test suite, it is best to use Ubuntu 12.04 or 14.04, and run the following commands. **Be aware** that this will add a user to the machine, and create a public key for SSH login! ```sh @@ -14,6 +13,12 @@ pip install --upgrade --editable . PWNLIB_NOTERM=1 make -C docs doctest ``` +## Testing in Docker + +A `Dockerfile` has been provided which has a clean testing environment with Ubuntu Xenial. It is very similar to the online Travis CI testing environment, but uses a more modern version of Ubuntu. + +See `travis/docker/README.md` for more information. + ## New Tests To add a new test to an existing module, just add an inline doctest. If the test needs access to an external module, add the import statement to the `testsetup` block in the corresponding file in `docs/source/.rst`. diff --git a/travis/docker/.gitignore b/travis/docker/.gitignore new file mode 100644 index 000000000..e7e01f401 --- /dev/null +++ b/travis/docker/.gitignore @@ -0,0 +1 @@ +pwntools.tar.gz diff --git a/travis/docker/Dockerfile b/travis/docker/Dockerfile new file mode 100644 index 000000000..839a10b86 --- /dev/null +++ b/travis/docker/Dockerfile @@ -0,0 +1,138 @@ +############################################################ +# Dockerfile to build Pwntools container +# Based on Ubuntu +############################################################ + +FROM pwntools/pwntools:stable +MAINTAINER Maintainer Gallopsled et al. + +USER root + +# Use UTF-8 +RUN locale-gen en_US.UTF-8 +ENV LANG en_US.UTF-8 +ENV LANGUAGE en_US:en +ENV LC_ALL en_US.UTF-8 + +# Dependencies from .travis.yml addons -> apt -> packages +RUN apt-get install -y ash +RUN apt-get install -y bash +RUN apt-get install -y dash +RUN apt-get install -y gcc-multilib +RUN apt-get install -y gcc-arm-linux-gnueabi +RUN apt-get install -y gcc-aarch64-linux-gnu +RUN apt-get install -y gcc-mips-linux-gnu +RUN apt-get install -y gcc-powerpc-linux-gnu +RUN apt-get install -y gcc +RUN apt-get install -y gdb +RUN apt-get install -y ksh +RUN apt-get install -y lib32stdc++6 +RUN apt-get install -y libc6-dev-i386 +RUN apt-get install -y mksh +RUN apt-get install -y pandoc +RUN apt-get install -y zsh + +# Dependencies from travis/install.sh +RUN apt-get install -y binutils +RUN apt-get install -y qemu-user-static +RUN apt-get install -y binutils-* +RUN apt-get install -y libcapstone3 + +# Required for various other things +RUN apt-get install -y curl +RUN apt-get install -y wget +RUN apt-get install -y unzip +RUN apt-get install -y openjdk-8-jre-headless +RUN apt-get install -y libxml2-dev +RUN apt-get install -y libxslt1-dev +RUN apt-get install -y ssh +RUN apt-get install -y lsb-release + +#============================================================================== +# ANDROID EMULATOR +#============================================================================== +# Android emulator from travis/install.sh +WORKDIR /usr/local +RUN wget -nv https://dl.google.com/android/android-sdk_r24.4.1-linux.tgz; \ + tar xf android-sdk_r24.4.1-linux.tgz; \ + rm -f android-sdk_r24.4.1-linux.tgz; +RUN ln -s android-sdk-linux android-sdk +ENV PATH="/usr/local/android-sdk/tools:$PATH" +ENV PATH="/usr/local/android-sdk/platform-tools:$PATH" + +RUN wget -nv https://dl.google.com/android/repository/android-ndk-r13b-linux-x86_64.zip ; \ + unzip android-ndk-r13b-linux-x86_64.zip ; \ + rm -f android-ndk-r13b-linux-x86_64.zip ; +RUN ln -s android-ndk-r13b android-ndk + +# Ensure that all executables can be run by other users e.g. travis +RUN find android-sdk/ -perm 744 -type f -executable | xargs chmod +x + +ENV NDK="/usr/local/android-ndk" +ENV PATH="$NDK:$PATH" + +RUN echo y | android update sdk --no-ui --all --filter platform-tools,extra-android-support +RUN echo y | android update sdk --no-ui --all --filter android-21 +RUN echo y | android update sdk --no-ui --all --filter sys-img-armeabi-v7a-android-21 + +# Upgrade pip +RUN pip install --upgrade pip + +#============================================================================== +# PWNTOOLS TEST REQUIREMENTS +#============================================================================== + +# Install pwntools from 'dev', to get all of the latest dependencies +# Then uninstall pwntools so we have a clean slate, but still have +# all of its dependencies installed. +WORKDIR /root +RUN git clone https://github.com/Gallopsled/pwntools +WORKDIR /root/pwntools +RUN pip install --upgrade --editable . +RUN pip install --upgrade --requirement docs/requirements.txt +RUN pip uninstall --yes pwntools +WORKDIR /root +RUN rm -rf pwntools + +#============================================================================== +# PWNTOOLS SSH TEST SETUP +#============================================================================== +# Start the container as travis +RUN useradd -m travis +RUN echo "travis ALL=(ALL:ALL) NOPASSWD: ALL" > /etc/sudoers.d/travis + +# Set up SSH stuff so we can SSH into localhost +USER travis +WORKDIR /home/travis +RUN ssh-keygen -t rsa -f ~/.ssh/travis -N '' +RUN echo 'from="127.0.0.1"' $(cat .ssh/travis.pub) > .ssh/authorized_keys +RUN echo \ +Host "example.pwnme\n\ + User travis\n\ + HostName 127.0.0.1\n\ + IdentityFile ~/.ssh/travis\n"\ +> ~/.ssh/config + +#============================================================================== +# ANDROID EMULATOR SETUP +#============================================================================== +RUN echo no | android --silent create avd --name android-armeabi-v7a --target android-21 --force --snapshot --abi armeabi-v7a +RUN emulator64-arm -avd android-armeabi-v7a -no-window -no-boot-anim -no-skin -no-audio -no-window -no-snapshot & \ + adb wait-for-device; \ + adb shell id; \ + adb shell getprop; \ + adb emu kill + +# Final touchup +USER root + +RUN apt-get install -y strace nano vim tmux + +# Entry point +USER travis +RUN mkdir /home/travis/pwntools +WORKDIR /home/travis/pwntools +ADD run.sh . +ADD pwntools.tar.gz . +RUN sudo chown -R travis . +ENTRYPOINT bash run.sh diff --git a/travis/docker/Makefile b/travis/docker/Makefile new file mode 100644 index 000000000..da5436ab6 --- /dev/null +++ b/travis/docker/Makefile @@ -0,0 +1,24 @@ +ROOT = $(shell git rev-parse --show-toplevel) +ANDROID ?= yes +TARGET ?= "" +TREE = $(shell cd $(ROOT) && git stash create "travis/docker testing") +ARCHIVE = $(ROOT)/travis/docker/pwntools.tar.gz + +ifeq ($(strip $(TREE)),) +TREE = HEAD +endif + +all: image + docker run -e "ANDROID=$(ANDROID)" -e "TARGET=$(TARGET)" --rm --privileged -it travis + +shell: image + docker run --rm --init --privileged --entrypoint /bin/bash -it travis + +image: $(ARCHIVE) + docker build -t travis . + +$(ARCHIVE): FORCE + cd $(ROOT) && git archive $(TREE) -o $@ + +FORCE: +.PHONY: all image diff --git a/travis/docker/README.md b/travis/docker/README.md new file mode 100644 index 000000000..739953363 --- /dev/null +++ b/travis/docker/README.md @@ -0,0 +1,29 @@ +# Testing in a Can + +This is a Dockerfile which has all of the requirements for testing pwntools. + +It's pretty simple, just run `make`. All of your changes will be copied into the docker container, and the doctest suite will be executed automatically. + +```shell +$ make -C travis/docker ANDROID=yes +$ make -C travis/docker ANDROID=no TARGET=docs/source/tubes/ssh.rst +``` + +## Options + +Currently, the options `TARGET` and `ANDROID` are available. + +### `ANDROID` + +Controls whether or not to run the Android test. The valid options are ``yes`` (the default) and ``no``. + +### `TARGET` + +This is appended to the `sphinx` command line, but generally is useful to sepcify a specific `rst` file to parse (e.g. to only run those tests). + +## Known Issues + +Currently, some tests are broken when executed in Docker. + +- `process.leak()` is broken, as it relies on `/proc//mem` +- `srop` tests are broken, since there are issues with `SYS_sigreturn` when running in Docker. diff --git a/travis/docker/run.sh b/travis/docker/run.sh new file mode 100644 index 000000000..d0367e9c5 --- /dev/null +++ b/travis/docker/run.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash +sudo service ssh start + +case "$ANDROID" in + [Yy]* ) + emulator64-arm -avd android-armeabi-v7a -no-window -no-boot-anim -no-skin -no-audio -no-window -no-snapshot & + adb wait-for-device + adb shell getprop ro.build.fingerprint + ;; + [Nn]* ) + echo "===========================================" >&2 + echo " WARNING: Disabling all Android tests !!! " >&2 + echo "===========================================" >&2 + + echo > 'docs/source/adb.rst' + echo > 'docs/source/protocols/adb.rst' + ;; +esac + +PWNLIB_NOTERM=1 coverage run -m sphinx -b doctest docs/source docs/build/doctest $TARGET