docs: revamp documentation

Author: francesco-racciatti

README.md

@@ -4,47 +4,87 @@
 
 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
 
-Deploy the docker image in your environment. 
+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
 ```
 
-Setup the health check to the `/health` endpoint if required.
-
 
 ## 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 localhost:8080/exec -d 'command=ls -la'
+$ curl -X POST localhost:8080/exec -d 'command=ls'
 ```
 
-This will capture and return the STDOUT of the executed command.
+This will run the command and return its STDOUT output.