Add a docker wrapper script to make it easier to use

README.md

@@ -58,61 +58,49 @@ To install scapy, see the [installation guide](https://scapy.readthedocs.io/en/l
 
 ### Docker
 
-You may also use passer within docker. Building is optional as you can also jump straight to the `docker run` command or the examples which will pull a pre-build docker image from a public repository. You can build the passer image like this:
+Passer also comes packaged as a Docker image. If you don't already have Docker here is a quick and dirty way to install it on Linux:
+
+```bash
+curl -fsSL https://get.docker.com | sh -
+```
+
+Otherwise, follow the [install instructions](https://docs.docker.com/get-docker/) for your operating system.
+
+For most uses, we recommend the [`passer`](https://github.com/activecm/passer/blob/master/passer) script included in this repo. This script will handle all docker-specific
+
 ```bash
-docker build -t quay.io/activecm/passer .
+wget https://raw.githubusercontent.com/activecm/passer/master/passer
+chmod +x passer
 ```
 
-And then you can run it like this:
+You can then use this script just as you would in any of the examples below. For example:
+
 ```bash
-docker run --rm -i --init --name=passer --net=host quay.io/activecm/passer
+./passer -i eth0
+# The equivalent without using the included script would be:
+docker run --rm --name=passer -i --init --net=host --cap-add=net_raw activecm/passer -i eth0
 ```
 
-In order to kill passer you can run:
+In order to stop passer run:
+
 ```bash
 docker stop passer
 ```
-or press `Ctrl-\` (control then backslash) in passer's window.
+
 
 ## Examples
 
-Both native and docker equivalent commands are given for each of the following examples. For the docker commands, please use the following bash function which is a wrapper around the docker command with the the additional ability to parse volume mount arguments:
-```bash
-# "c" for "containerized"
-function cpasser() {  
-  local docker_args=("--rm" "--interactive" "--init" "--name" "passer" "--net" "host")
-  local passer_args=()
-  while [[ $# -gt 0 ]]; do
-    case $1 in
-      -v|--volume)
-        # pop next two arguments off and append to docker args
-        docker_args+=("$1"); shift
-        docker_args+=("$1"); shift
-        ;;
-      -v=*|--volume=*)
-        # pop next argument off and append to docker args
-        docker_args+=("$1"); shift
-        ;;
-      *)
-        # pop next argument off and append to passer args
-        passer_args+=("$1"); shift
-        ;;
-    esac
-  done
-  docker run "${docker_args[@]}" quay.io/activecm/passer "${passer_args[@]}"
-}
-```
-
-1) Sniff live as root
+### Sniff live as root
+
 ```bash
 /path/to/passer.py
-# or with docker
-cpasser
 ```
+
 This sniffs from all network interfaces and sends all output
 lines to your console.
 
-2) Sniff live as a non-root user
+### Sniff live as a non-root user
+
 ```bash
 sudo /path/to/passer.py
 ```
@@ -121,74 +109,69 @@ or
 su - -c '/path/to/passer.py'
 ```
 
-3) Sniff live as root, but only from one interface
+### Sniff live as root, but only from one interface
+
 ```bash
 /path/to/passer.py -i IfaceName
-# or with docker
-cpasser -i IfaceName
 ```
 Running `route` should give some live interfaces you might use. 
-This is incompatible with "-r".
+> :grey_exclamation: `-i` is incompatible with `-r`.
+
+### Read packets from a pcap file; no root privileges needed
 
-4) Read packets from a pcap file; no root privileges needed
 ```bash
 /path/to/passer.py -r /path/to/packets.pcap
-# or with docker
-cpasser -v /path/to/packets.pcap:/packets.pcap -r /packets.pcap
 ```
-This is incompatible with "-i".
 
-5) Accept raw pcap data on stdin
+> :grey_exclamation: `-r` is incompatible with `-i`.
+
+### Accept raw pcap data on stdin
+
 ```bash
 cat packetdata.pcap | ./passer.py -r /proc/self/fd/0
 zcat packetdata.pcap.gz | ./passer.py -r /proc/self/fd/0
 bzcat packetdata.pcap.bz2 | ./passer.py -r /proc/self/fd/0
 tcpdump -i eth0 -qtnp -w - | ./passer.py -r /proc/self/fd/0
-# or with docker
-cat packetdata.pcap | cpasser -r /proc/self/fd/0
 # etc...
 ```
+
 This lets you capture packets with any tool that can save
 packets to a pcap file, and later process them with passer on a
 different system.
 
-6) Save output lines to a text file for later processing
+### Save output lines to a text file for later processing
+
 ```bash
 /path/to/passer.py -l /path/to/networkinfo.txt
-# or with docker
-touch /path/to/networkinfo.txt
-cpasser -v /path/to/networkinfo.txt.pcap:/networkinfo.txt -l /networkinfo.txt
 ```
 
-7) Suppress warnings and other debugging info
+### Suppress warnings and other debugging info
+
 ```bash
 /path/to/passer.py 2>/dev/null
-# or with docker
-cpasser 2>/dev/null
 ```
 
-8) Show help screen
+### Show help screen
+
 ```bash
 /path/to/passer.py -h
-# or with docker
-cpasser -h
 ```
 
-9) Save "odd"/unhandled packets to a pcap file
+### Save "odd"/unhandled packets to a pcap file
+
 ```bash
 /path/to/passer.py -u /path/to/oddpackets.pcap
-# or with docker
-touch /path/to/oddpackets.pcap
-cpasser -v /path/to/oddpackets.pcap:/oddpackets.pcap -u /oddpackets.pcap
 ```
+
 This is generally intended for the development process; packets
 saved to this file are ones that need to have signatures written.  If
 you'd like to help improve the program, get in touch with the author,
 Bill Stearns ([email protected]).  Contributions of odd packets,
 descriptions of services, and patches to the program are gratefully
 accepted.
 
-10) Apply a BPF filter to limit which packets are processed
+### Apply a BPF filter to limit which packets are processed
+
 This _should_ be as simple as placing the BPF filter in single
 quotes at the end of the command line.  As of version 1.16, the
 underlying library does not appear to successfully use the supplied
@@ -197,8 +180,6 @@ hand the pared-down set of packets to passer on stdin, like above:
 
 ```bash
 tcpdump -r packets.pcap -w - 'icmp or arp' | ./passer.py -r /proc/self/fd/0
-# or with docker
-tcpdump -r packets.pcap -w - 'icmp or arp' | cpasser -r /proc/self/fd/0
 ```
 
 See the "Sample filters" section, below, for some suggestions of

passer

@@ -0,0 +1,71 @@
+#!/bin/bash
+
+# If the current user doesn't have docker permissions run with sudo
+SUDO=''
+if [ ! -w "/var/run/docker.sock" ]; then
+	SUDO="sudo --preserve-env "
+fi
+
+function cpasser() {
+	local passer_args=()
+	local docker_cmd=("docker" "run")
+	docker_cmd+=("--name" "passer")     # allow easy controlling of the container
+	docker_cmd+=("--rm")                # remove the container after passer exits
+	docker_cmd+=("--interactive")       # allow sending keystrokes to passer (e.g. to shut down) and piping in a pcap
+	docker_cmd+=("--init")              # needs tini init to properly shut down passer
+	docker_cmd+=("--net" "host")        # allow capturing on host network interfaces
+	docker_cmd+=("--cap-add" "net_raw") # allow listening in promiscuous mode
+
+	# For the most part, we can just pass all arguments directly through.
+	# However, certain commands need to mount files or directories
+	# into the docker container. This adds the volume mounts.
+	while [ $# -gt 0 ]; do
+		case $1 in
+			# The following arguments read from a file.
+			-r|--read)
+				passer_args+=("$1")
+				if [ -f "$2" ]; then
+					# Get the absolute path.
+					local abs_path=$(realpath "$2")
+					# Map to the same path inside the container for nicer status/error messages.
+					docker_cmd+=("--volume" "$abs_path:$abs_path")
+					# Change the argument to the absolute path.
+					passer_args+=("$abs_path")
+				else
+					# The file doesn't exist for some reason. Let passer display the error message.
+					passer_args+=("$2")
+				fi
+				shift
+				shift
+			;;
+			# The following arguments write to a file.
+			-l|--log)        ;& # fallthrough
+			-s|--suspicious) ;& # fallthrough
+			-u|--unhandled)
+				passer_args+=("$1")
+				# These files may or may not exist already. Mount in the parent directory instead.
+				local abs_path=$(realpath "$2")
+				local parent_path=$(dirname "$abs_path")
+				docker_cmd+=("--volume" "$parent_path:$parent_path")
+				# Change the argument to the absolute path.
+				passer_args+=("$abs_path")
+				shift
+				shift
+			;;
+			# All other arguments are passed through.
+			*)
+				passer_args+=("$1")
+				shift
+			;;
+		esac
+	done
+
+	docker_cmd+=("activecm/passer")
+
+	# Print out the final arguments and exit for debugging
+	#echo "docker_cmd: ${docker_cmd[@]}"; echo "passer_args: ${passer_args[@]}"; exit  # debug
+
+	$SUDO "${docker_cmd[@]}" "${passer_args[@]}"
+}
+
+cpasser "$@"