From 35ddde0106193cd10bc387af074fe83a9b6fcedc Mon Sep 17 00:00:00 2001
From: Brian Seymour <imbrianseymour@gmail.com>
Date: Fri, 21 Sep 2018 23:15:24 -0500
Subject: [PATCH] updated docs

---
 docker/execute |  2 +-
 readme.md      | 32 +++++++++++++++++++++++++++-----
 2 files changed, 28 insertions(+), 6 deletions(-)

diff --git a/docker/execute b/docker/execute
index 0b919b5..58eaf93 100755
--- a/docker/execute
+++ b/docker/execute
@@ -65,6 +65,6 @@ docker run \
     piston \
     runuser \
         -l runner \
-        -c "/$bin /$file $file | head -c 1024 2>&1"
+        -c "/$bin /$file $file | head -c 65536 2>&1"
 
 rm -f /tmp/$file
diff --git a/readme.md b/readme.md
index e33cc09..1b5cb38 100644
--- a/readme.md
+++ b/readme.md
@@ -1,7 +1,7 @@
 ## Piston
-This project is the underlying engine for running untrusted and possibly malicious code that originates
-from from EMKC contests and challenges.
-
+Piston is the underlying engine for running untrusted and possibly malicious code that originates
+from from EMKC contests and challenges. It's also used in the Engineer Man Discord server via
+[felix bot](https://github.com/engineer-man/felix).
 
 #### Installation
 - Install Docker https://www.docker.com/get-started
@@ -9,14 +9,36 @@ from from EMKC contests and challenges.
 - `cd piston/docker`
 - `./build`
 
-
 #### Usage
 - `docker/execute <lang> <path to file>`
 
-
 #### Supported Languages
 Currently python2, python3, c, c++, go, node, and ruby are supported.
 
+#### Principle of Operation
+Piston utilizes Docker as the primary mechanism for sandboxing. There is a small API written in Go which takes
+in execution requests and spawns new containers to execute the source from that request. High level, the API writes
+a temporary source file to `/tmp` and that mounts that and all the execution scripts read-only in the container.
+The source file is either ran or compiled and ran (in the case of languages like c, c++, go, etc.).
+
+#### Security
+Docker provides a great deal of security out of the box. Piston takes additional steps to make it resistant to
+various privilege escalation, denial-of-service, and resource saturation threats. These steps include:
+- Disabling outgoing network interaction
+- Greatly reducing CPU allowance (resists CPU saturation)
+- Capping memory at 64mb (resists RAM saturation)
+- Capping max processes at 16 (resists `:(){ :|: &}:;`, `while True: os.fork()`, etc.)
+- Capping max files at 128 (resists various file based attacks)
+- Mounting all resources read-only (resists `sudo rm -rf --no-preserve-root /`)
+- Capping runtime execution at 2 seconds
+- Capping stdout to 65536 characters (resists yes/no bombs and runaway output)
+- SIGKILLing misbehaving code
+- Disabling journald logs (resists log flood)
+
+#### Performance
+One thing that needs investigation is how to spawn containers faster. The Docker daemon is synchronous in its
+container spawning. This means the bottleneck for code execution is how fast containers can start. Environments
+vary, but, in ours they start at a rate of no more than 1 per second.
 
 #### License
 Piston is licensed under the MIT license.