improving the doc

Author: cryptax

README.md

@@ -1,10 +1,16 @@
+# What's this?
+
+This is a _docker_ image for reverse engineering of _Android_ applications.
+
+
 # Disclaimer
 
 Please use responsibly.
 
 # Description
 
 This container contains many tools to reverse engineer Android applications.
+
 - Android emulators 4.4.2 and 5.1
 - androguard
 - apkid
@@ -23,35 +29,96 @@ This container contains many tools to reverse engineer Android applications.
 - procyon
 - radare2
 
-Those are free tools, or free demos.
+Those are open source tools, or free demos.
+
+# How to use this
+
+There are three steps:
+
+0. Install docker ;)
+1. Download docker image
+2. Run the container on your host
+3. Log into the container and use it ;)
+
+## Retrieve the image
+
+Normally, you just need to do:
 
-# Usage
+```
+$ docker pull cryptax/android-re
+```
+
+Unless you want to build your own image - then see below the _Customization_ section.
 
-You are expected to ssh into the container, using -X to forward X window.
+## Running the container
 
 Run the container:
 ```
 $ docker run -d --name androidre -p 5022:22 -p 5900:5900 cryptax/android-re
 ```
 
-Connect. Default password for root is **rootpass**. Modify Dockerfile to change this.
+where:
+- NAME is the name you wish to give to this container. You may start several different instances.
+- SSH_PORT is the port number the container will listen on for SSH connections. As the standard SSH port (22) is often already used, you may want to use another port here.
+- VNC_PORT is the port number the container will listen on for VNC connections.
+
+For other options in `docker run`, [please go to docker's documentation](https://docs.docker.com/engine/reference/run/). For example, you may want to mount a given directory of your network and make it accessible to the container using `-v` option.
+
+
+Typically, I run (but you may have to modify to suit your own needs):
 ```
-$ ssh -X -p 5022 [email protected]
+$ docker run -d --name androidre -p 5022:22 -p 5900:5900 cryptax/android-re
 ```
 
-Alternative to ssh login: vnc, with **rootpass** as default password.
+
+## Connecting
+
+Once a container is running, it's basically like a virtual Linux host. You need to connect to it.
+You are expected to log in using either **ssh** or **vncviewer**.
+The default root password is **rootpass**.
+
+### Logging in with SSH
+
+Use `-X` to forward X window. 
+
 ```
-$ vncviewer host::5900
+$ ssh -X -p SSH_PORT [email protected]
 ```
 
+where SSH_PORT is the SSH port the container listens on. In my docker run personal example, it's 5022.
+
+Note that X forwarding is known to have issues on Macs.
+
+### Logging in with VNC
+
+Please use `vncviewer`
+
+```
+$ vncviewer host::VNC_PORT
+```
+
+where VNC_PORT is the VNC port the container forwards. In my docker run example, it's 5900.
+
+
+## Misc info
+
 Android reverse engineering tools are installed in **/opt**.
 
 To run an Android emulator (5.1):
 ```
 $ emulator &
 ```
 
-# Hack.lu Workshop
+# Customization
+
+To change the default password, or for any other changes, modify the `Dockerfile` and re-build your own image.
+
+You are welcome to post issues or suggestions.
+
+
+# Hack.lu 2016 Workshop
 
-Workshop samples will be provided by other means. The image does not provide any Android sample.
+This docker image was used for a free workshop at [Hack.lu](http://2016.hack.lu).
+Workshop samples were provided to participants by other means.
+This image **does not provide any Android sample**.