Added tracing and profile creation examples

docs/EXAMPLES.md

@@ -1,4 +1,6 @@
-# How to run an example
+# secimport Examples
+To understand how to trace you process and create custom profiles for modules or applications, please see <a href="TRACING_PROCESSES.md">TRACING_PROCESSES.md</a>
+# Prepared Examples
 1. Enter a root shell and `export PYTHONPATH=$(pwd)/src:$(pwd)/examples:$(pwd):$PYTHONPATH`<br>
 2. Make sure the python interpreter you use was compiled with `dtrace`.
 3. Run any of the examples in the following way:
@@ -36,20 +38,3 @@
     - `examples/run_dtrace_example.sh`
     - `examples/run_http_request_blocking_example.sh`
     - `examples/run_shell_blocking_example.sh`
-
-# Tracing processes
-  - Using `dtrace`
-    - Tracing the syscalls of a process with pid `12345`
-      - `dtrace -n 'syscall::: /pid == ($1)/ {@[pid,execname,probefunc]=count()}' 12345`
-    - Tracing the syscalls of a docker container with pid `12345`
-      - `dtrace -n 'syscall::: /progenyof($1)/ {@[pid,execname,probefunc]=count()}' 12345`
-  - Using `strace`
-    -  A script to list all your application's syscalls using `strace`.<br> I contributed it to `firejail` a few years ago:
-      - https://github.com/netblue30/firejail/blob/master/contrib/syscalls.sh
-      - ```
-        wget "https://raw.githubusercontent.com/netblue30/firejail/c5d426b245b24d5bd432893f74baec04cb8b59ed/contrib/syscalls.sh" -O syscalls.sh
-
-        chmod +x syscalls.sh
-
-        ./syscalls.sh examples/http_request.py
-        ```

docs/TRACING_PROCESSES.md

@@ -0,0 +1,26 @@
+# Tracing processes for syscalls
+There are several ways to create a secimport profile for your modules.
+
+  - Using `secure_import` from python:
+    - `secimport.secure_import(..., log_syscalls=True, destructive=False)`
+    - The log output will contain all the syscalls made by your process.
+    - Create a secure import based on that log
+  - Using our dscript to generate a profile:
+    -  `sudo dtrace -s src/secimport/templates/default.allowlist.template.d -c "python -m http.server"`
+    - CTRL+C
+    - Create a secure import based on that log.
+  - Using simple `dtrace`
+    - Tracing the syscalls of a process with pid `12345`
+      - `dtrace -n 'syscall::: /pid == ($1)/ {@[pid,execname,probefunc]=count()}' 12345`
+    - Tracing the syscalls of a docker container with pid `12345`
+      - `dtrace -n 'syscall::: /progenyof($1)/ {@[pid,execname,probefunc]=count()}' 12345`
+  - Using `strace`
+    -  A script to list all your application's syscalls using `strace`.<br> I contributed it to `firejail` a few years ago:
+      - https://github.com/netblue30/firejail/blob/master/contrib/syscalls.sh
+      - ```
+        wget "https://raw.githubusercontent.com/netblue30/firejail/c5d426b245b24d5bd432893f74baec04cb8b59ed/contrib/syscalls.sh" -O syscalls.sh
+
+        chmod +x syscalls.sh
+
+        ./syscalls.sh examples/http_request.py
+        ```

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "secimport"
-version = "0.2.0"
+version = "0.3.0"
 description = "A sandbox/supervisor for python modules."
 authors = ["Avi Lumelsky"]
 license = "MIT"