docs: update readme

discue · Dec 28, 2024 · 6ef42cf · 6ef42cf
1 parent ff20939
commit 6ef42cf
Showing 1 changed file with 50 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -18,10 +18,58 @@
 <br/>
 
 # go-syscall-gatekeeper
-Go application that can be used to watch and limit syscalls of other processes.
+Go process manager that can be used to 
+- start other processes and control their lifecycle,
+- watch the status of the started process and return appropriate exit codes,
+- and, most importantly, **trace and limit the syscalls of the started process**. 
 
-## 📦 Installation
+This allows you to start trusted and untrusted applications e.g. go, python, node apps and limit their access to the file system, or to the network. With simple command line flags you can easily grant permissions to the started process.
+
+## 🤝 Examples
+This section shows some examples of how processes can be started with different level of permissions and... success. See below, how the `curl` command is failing until both filesystem and network permissions are granted.
 
+While it's obvious, why `curl` needs network permissions, the filesystem permissions are necessary to read e.g. configuration files and shared libraries.
+
+### ❌ No filesystem permissions
+In this case, `curl` is only started with a default set of permissions. The command fails because, access to the filesystem gets denied.
+```bash
+$ gatekeeper run curl -v google.com
+[...]
+Syscall not allowed: access
+enter [pid 4855] access (/etc/ld.so.preload)
+Exiting with code 111
+exit status 111
+```
+
+### ❌ Without filesystem permissions, no permission access network
+In this case, `curl` is started with a default set of permissions and **read access for the file system**. The command still fails because, access to the network-related syscalls gets denied.
+```bash
+$ gatekeeper run --allow-file-system-read curl -v google.com
+[...]
+Syscall not allowed: socket
+enter [pid 4996] socket
+PID 4996 exited from signal SIGKILL (killed) (9)
+Exiting with code 111
+exit status 111
+```
+
+### ✅ With filesystem and network permissions
+In this case, `curl` is started with read access to the filesystem **and** network. The command then exits with success.
+```bash
+$ gatekeeper run --allow-file-system-read --allow-network-client curl -v google.com
+[...]
+<HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8">
+<TITLE>301 Moved</TITLE></HEAD><BODY>
+<H1>301 Moved</H1>
+The document has moved
+<A HREF="http://www.google.com/">here</A>.
+</BODY></HTML>
+[...]
+PID 5255 exited from exit status 0 (code = 0)
+Exiting with code 0
+```
+
+## 📦 Installation
 Install the package:
 
 ```bash