Merge pull request #8 from francesco-racciatti/francesco-revamp-documentation

chore: revamp security-playground

Author: tembleking

Dockerfile

@@ -1,15 +1,11 @@
-FROM python:3.7-buster
+FROM python:3.9-slim
 
-RUN pip install pipenv==2018.11.26
+RUN pip install --upgrade pipenv
 
 WORKDIR /app
-
-COPY Pipfile /app
-COPY Pipfile.lock /app
+COPY . .
 RUN pipenv install --system --deploy
 
-COPY app.py /app
-
 EXPOSE 8080
 
-CMD ["gunicorn", "-b", ":8080", "--workers", "2", "--threads", "4", "--worker-class", "gthread", "--access-logfile", "-", "--error-logfile", "-", "app:app"]
+ENTRYPOINT ["./entrypoint.sh"]

Pipfile

@@ -1,5 +1,5 @@
 [[source]]
-url = "https://pypi.python.org/simple"
+url = "https://pypi.org/simple"
 verify_ssl = true
 name = "pypi"
 
@@ -10,4 +10,4 @@ gunicorn = "*"
 [dev-packages]
 
 [requires]
-python_version = "3.7"
+python_version = "3.9"

Pipfile.lock

@@ -2,48 +2,89 @@
 
 ![last commit](https://flat.badgen.net/github/last-commit/sysdiglabs/security-playground?icon=github) ![licence](https://flat.badgen.net/github/license/sysdiglabs/security-playground) ![docker pulls](https://flat.badgen.net/docker/pulls/sysdiglabs/security-playground?icon=docker)
 
-The security playground is a HTTP web server to simulate security breaches in
-run time.
+The security playground is an HTTP web server to simulate security breaches. It allows you to read, write, and execute commands in a containerized environment.
+
+
+## Build
+
+```
+$ docker build -t sysdiglabs/security-playground:latest .
+```
+
 
 ## Installation
 
-Use the docker image to deploy it in your Kubernetes cluster or locally in a
-container.
+Deploy the docker image in your environment, and setup the probe health check to the `/health:8080` endpoint if required.
+
+You can also run the image locally:
 
 ```bash
 $ docker run --rm -p 8080:8080 sysdiglabs/security-playground
 ```
 
+
 ## Usage
 
-The HTTP API exposes tree endpoints to interact with the system.
+The application provides endpoints for:
+ - [Health checks](#health-checks)
+ - [Reading file](#reading-a-file)
+ - [Writing file](#writing-a-file)
+ - [Executing commands](#executing-a-command)
+
+
+### Health checks
+
+The health check endpoint is `/health` on port `8080` and returns the `200` HTTP status code.
+
 
 ### Reading a file
 
-You can read a file using just the URL.
+You can retrieve a file's contents by sending a `GET` request to the application's URL.
+
+```bash
+$ curl <URL>:8080/<PATH>
+```
+
+For example:
 
 ```bash
 $ curl localhost:8080/etc/shadow
 ```
 
-This will return the content of the /etc/shadow file.
+This will return the content of the `/etc/shadow` file in the container running locally.
+
+
 
 ### Writing a file
 
-You can write to a file using the URL and POSTing the content.
+You can write data to a file by sending a `POST` request to the application's URL with the desired content.
+
+```bash
+$ curl -X POST <URL>:8080/<PATH> -d 'content=<CONTENT>'
+```
+
+For example:
 
 ```bash
 $ curl -X POST localhost:8080/bin/hello -d 'content=hello-world'
 ```
 
-This will write to /bin/hello the hello-world string
+This command writes the string hello-world to /bin/hello.
+
+
 
 ### Executing a command
 
-You can execute a command using the /exec endpoint and POSTing the command.
+To execute a command, send a `POST` request to the `/exec` endpoint with the command as the payload.
+
+```bash
+$ curl -X POST <URL>:8080/exec -d 'command=<CMD>'
+```
+
+For example:
 
 ```bash
-$ curl -X POST /exec -d 'command=ls -la'
+$ curl -X POST localhost:8080/exec -d 'command=ls'
 ```
 
-This will capture and return the STDOUT of the command executed.
+This will run the command and return its STDOUT output.

README.md

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+gunicorn -b :8080 --workers 2 --threads 4 --worker-class gthread --access-logfile - --error-logfile - app:app