|
| 1 | +# Contribute a Dockerfile |
| 2 | + |
| 3 | +Please contribute to the [REMnux collection of Docker images](../../run-tools-in-containers/remnux-containers.md) of malware analysis applications. You'll get a chance to experiment with [Docker](https://www.docker.com), become a master at setting up an application of your choice, and expand the set of tools that others can run for examining malicious software. |
| 4 | + |
| 5 | +To get started, review: |
| 6 | + |
| 7 | +1. [REMnux documentation section on Docker images.](../../run-tools-in-containers/remnux-containers.md) |
| 8 | +2. [Docker documentation on Dockerfile creation.](https://docs.docker.com/engine/reference/builder/) |
| 9 | +3. [Dockerfiles in the REMnux Docker repository on Github.](https://github.com/remnux/docker) |
| 10 | +4. The details in this section below. |
| 11 | + |
| 12 | +{% hint style="success" %} |
| 13 | +Before creating the Dockerfile for the application you'd like to contribute to the REMnux toolkit, [reach out to Lenny Zeltser](https://zeltser.com/contact), the primary REMnux maintainer, to confirm that the application is a fit for REMnux. |
| 14 | +{% endhint %} |
| 15 | + |
| 16 | +## Creating a Dockerfile |
| 17 | + |
| 18 | +A properly-formatted Dockerfile describes the steps necessary to build and configure your application inside a Docker container in a repeatable and unattended manner. To get a sense for the structure of such files, browse the [REMnux repository of Dockerfiles on Github](https://github.com/REMnux/docker/). To explain how to build such files, we'll use the [JSDetox Dockerfile](https://github.com/REMnux/docker/blob/master/jsdetox/Dockerfile) as an example. |
| 19 | + |
| 20 | +The beginning of your Dockerfile should include comments that state which application is included in the image, who created the app and where it can be obtained in a traditional form. The comments should explain how the use of the image should run it. For instance: |
| 21 | + |
| 22 | +```text |
| 23 | +# This Docker image encapsulates the JSDetox malware analysis tool by @sven_t |
| 24 | +# from http://www.relentless-coding.com/projects/jsdetox |
| 25 | +# |
| 26 | +# To run this image after installing Docker, use the following command: |
| 27 | +# sudo docker run -d --rm --name jsdetox -p 3000:3000 remnux/jsdetox |
| 28 | +# Then, connect to http://localhost:3000 using your web browser. |
| 29 | +``` |
| 30 | + |
| 31 | +REMnux images typically use a minimal Docker image of Ubuntu 18.04 as a starting point, as designated by the `FROM` directive below. The `LABEL` directive specify meta data such as the maintainer and version of the Dockerfile: |
| 32 | + |
| 33 | +```text |
| 34 | +FROM ubuntu:18.04 |
| 35 | +LABEL maintainer="Lenny Zeltser (@lennyzeltser, www.zeltser.com)" |
| 36 | +LABEL updated="1 May 2020" |
| 37 | +``` |
| 38 | + |
| 39 | +The `USER` directive specifies the user inside the container that should perform the installation steps \("root"\). The `RUN` directive specifies the commands to run inside the container to install the software. Your Dockerfile file should include the `apt-get update` command, followed by `apt-get install -y` and a listing of the Ubuntu packages the application requires.The starting point for the image is a minimal Ubuntu installation, so assume that a given package is absent unless you explicitly install it: |
| 40 | + |
| 41 | +```text |
| 42 | +USER root |
| 43 | +RUN apt-get update && apt-get install -y \ |
| 44 | + git \ |
| 45 | + ruby \ |
| 46 | + ruby-dev \ |
| 47 | + bundler \ |
| 48 | + zlib1g-dev \ |
| 49 | + build-essential && \ |
| 50 | + rm -rf /var/lib/apt/lists/* |
| 51 | +``` |
| 52 | + |
| 53 | +Note that the `RUN` command above links several commands together using `&&` and employs `\` to break this sequence of commands into multiple lines for readability. We're linking several commands like this to slightly minimize the size of the resulting Docker image file. This is also the reason why we include the `rm` command to get rid of the package listing. |
| 54 | + |
| 55 | +The followng `RUN` directive sets up the non-root user creatively named "nonroot", so that commands and applications that don't require root provileges have a more restricted environment within which to run: |
| 56 | + |
| 57 | +```text |
| 58 | +RUN groupadd -r nonroot && \ |
| 59 | + useradd -r -g nonroot -d /home/nonroot -s /sbin/nologin -c "Nonroot User" nonroot && \ |
| 60 | + mkdir /home/nonroot && \ |
| 61 | + chown -R nonroot:nonroot /home/nonroot |
| 62 | +``` |
| 63 | + |
| 64 | +The next set of directives tells Docker to start running commands using the newly-set up "nonroot" user, defines the working directory to match that user's home directory and retrieves the code for the application we're installing \(JSDetox, in this case\): |
| 65 | + |
| 66 | +```text |
| 67 | +USER nonroot |
| 68 | +WORKDIR /home/nonroot |
| 69 | +RUN git clone https://github.com/svent/jsdetox.git |
| 70 | +``` |
| 71 | + |
| 72 | +The following instructions will install the application using the `bundle install` command, according the JSDetox installation instructions. These steps need to run as "root" to have the ability to copy the application's files into protected locations: |
| 73 | + |
| 74 | +```text |
| 75 | +USER root |
| 76 | +WORKDIR /home/nonroot/jsdetox |
| 77 | +RUN sed "s/, '0.9.8'/, '0.12.3'/g" -i Gemfile |
| 78 | +RUN bundle install |
| 79 | +``` |
| 80 | + |
| 81 | +The final set of directives below tells Docker to switch back to using the "nonroot" user and sets the working directory to the location from which JSDetox should be launched. It also specifies which command Docker should run when this image is launched without any parameters: |
| 82 | + |
| 83 | +```text |
| 84 | +USER nonroot |
| 85 | +EXPOSE 3000 |
| 86 | +WORKDIR /home/nonroot/jsdetox |
| 87 | +CMD ./jsdetox -l $HOSTNAME 2>/dev/null |
| 88 | +``` |
| 89 | + |
| 90 | +By default, JSDetox listens on localhost. To give us the opportunity to connect to JSDetox from outside of its container, the command above launches the tool with the `-l` parameter and specifies the $HOSTNAME varilable. This environment variable is automatically defined to match the hostname that Docker will assign when this container runs, which will allow JSDetox to listen on the network interface accessible from our underlying host. |
| 91 | + |
| 92 | +## Building a Image from the Dockerfile |
| 93 | + |
| 94 | +It’s difficult to create a Dockerfile, such as the one we reviewed above, in one step. Inevitably, some command will run in an unexpected manner, preventing the application from installing properly. Before documenting your steps in Dockerfile, consider launching the base Ubuntu container like this: |
| 95 | + |
| 96 | +```text |
| 97 | +docker run --rm -it ubuntu:18.04 bash |
| 98 | +``` |
| 99 | + |
| 100 | +Then, manually type and write down the commands into the container's shell to install the desired application. Once you've validated that a specific sequence of commands works, start building a Dockerfile by adding your instructions one or two at a time to validate that they work as intended. |
| 101 | + |
| 102 | +Once you've created a Dockerfile that contains the desired directives, go to the directory where the file is present and run the following command, where "image-name" is he name you'd like to assign to the image file you're building: |
| 103 | + |
| 104 | +```text |
| 105 | +docker build -t=image-name . |
| 106 | +``` |
| 107 | + |
| 108 | +After Docker builds the image, you can run it using the following command to get a shell in the container where your application has been installed: |
| 109 | + |
| 110 | +```text |
| 111 | +docker run --rm -it image-name bash |
| 112 | +``` |
| 113 | + |
| 114 | +Of course, "image-name" in the command above should correspond to the name you've assigned to the image. The `--rm` parameter directs Docker to automatically remove the container once it finishes running. This gets rid of any changes the application may have made to its local environment when it ran, but does not remove the cached image file that represents the app on your system. The `-it` parameter requests that Docker open an interactive session to the container so you can interact with it. |
| 115 | + |
| 116 | +Once you have built and tested your Dockerfile, [share it with Lenny Zeltser](https://zeltser.com/contact), so he can review it and, if appropriate, add your contribution to the REMnux repository. |
| 117 | + |
| 118 | +## Facilitating File System and Network Interactions |
| 119 | + |
| 120 | +The container will be isolated from the host system: by default it will be able to communicate over the network in the outbound direction, but won't accept inbound traffic. Also, if the container is invoked with the `--rm` parameter, its contents will disappear after it stops running. When building the image, anticipate the user's need to communicate with the app inside the container over the network or to pass files in and out of the container. |
| 121 | + |
| 122 | +### **Accessing Network Ports in the Container** |
| 123 | + |
| 124 | +In the JSDetox example above, the application listens on TCP port 3000. In its default configuration, JSDetox listens on localhost, which would make its port inaccessible from outside its Docker container. This is why we launched JSDetox with the `-l $HOSTNAME` parameter. This directed the application to listen on the network interface that could be accessed from outside the container. |
| 125 | + |
| 126 | +Unless the user explicitly requests access to the container's port when launching its image, no ports will be accessible from the underlying system. Fortunately, Docker allows us to use the `-p` parameter to specify that a specific port within the container should be accessible from outside the container. For example, to access JSDetox’ port 3000, the user needs to specify `-p 3000:3000`. This maps the container’s port 3000 to the underlying host’s port 3000, allowing the user to communicate with JSDetox by connecting to http://localhost:3000 using a web browser. |
| 127 | + |
| 128 | +### **Sharing Files with the Container** |
| 129 | + |
| 130 | +There is no need to share files with JSDetox inside the container by using the file system, because this application interacts with the user through the web browser. In contrast, some files expect the user to provide input or share output via the file system. Docker supports the `-v` parameter to share a directory between the underlying host and the container. |
| 131 | + |
| 132 | +For example, let’s say we wanted to share a folder with the container running [Rekall](../../run-tools-in-containers/remnux-containers.md#rekall), which is available in the REMnux repository on Docker Hub. If the memory image file that you’d like to analyze is on your underlying host in the ~/files directory, you could share that directory with the Rekall container by specifying `-v ~/files:/home/nonroot/files` when running the application’s image: |
| 133 | + |
| 134 | +```text |
| 135 | +sudo docker run --rm -it -v ~/files:/home/nonroot/files remnux/rekall bash |
| 136 | +``` |
| 137 | + |
| 138 | +This maps the local ~/files directory to the /home/nonroot/files directory inside the container. The Rekall image is built to run the user-designated command \(e.g., `bash`\) as the user "nonroot". To ensure that the non-root user has access to the underlying hosts ~/files directory, the user of the app will need to make that directory world-accessible \(i.e., `chmod a+xwr ~/files`\) before launching the container. |
| 139 | + |
0 commit comments