aboutgitcodelistschat:MatrixIRC
diff options
context:
space:
mode:
authorStefano Brivio <sbrivio@redhat.com>2023-06-15 13:29:57 +0200
committerStefano Brivio <sbrivio@redhat.com>2023-06-21 23:47:52 +0200
commit6c8302e779fc70367fe396843d8491d2aec09eb3 (patch)
treeaae161e766880918164ad9a8fa2a3acc1d1b69b7
parent59968e8f0b4bf3a6ae16822ca93c866f42c8fb8e (diff)
downloadseitan-6c8302e779fc70367fe396843d8491d2aec09eb3.tar
seitan-6c8302e779fc70367fe396843d8491d2aec09eb3.tar.gz
seitan-6c8302e779fc70367fe396843d8491d2aec09eb3.tar.bz2
seitan-6c8302e779fc70367fe396843d8491d2aec09eb3.tar.lz
seitan-6c8302e779fc70367fe396843d8491d2aec09eb3.tar.xz
seitan-6c8302e779fc70367fe396843d8491d2aec09eb3.tar.zst
seitan-6c8302e779fc70367fe396843d8491d2aec09eb3.zip
README
-rw-r--r--README.md103
1 files changed, 64 insertions, 39 deletions
diff --git a/README.md b/README.md
index b23e2e8..5288678 100644
--- a/README.md
+++ b/README.md
@@ -4,42 +4,67 @@ Copyright (c) 2023 Red Hat GmbH
Author: Stefano Brivio <sbrivio@redhat.com>
-->
-<style>
-.markdown-body {
- display: block;
- font-family: Roboto Mono, monospace;
- font-weight: 200;
- font-size: 13pt;
- line-height: 1.5;
-}
-
-div > ul {
- float: left;
-}
-</style>
-
-<img src="/static/seitan.svg" alt="seitan diagram"
- style="object-fit: contain; width: 50%; float: left">
-
-* **build-filter**
- * build BPF binary-search tree
-
-* **build-table**
- * build transformation table
-
-* **seitan-eater**
- * load BPF blob
- * attach filter
- * call blocking syscall
- * on return, start binary
-
-* **seitan**
- * load transformation table blob
- * listen to netlink proc connector
- * look for seitan-eater, once found:
- * get seccomp notifier via pidfd_getfd()
- * listen to it, new syscall:
- * look up in transformation table
- * load args from memory
- * execute transformation, unblock, or block
- * return, optionally injecting context
+<link rel="stylesheet" type="text/css" href="/static/asciinema-player.css" />
+<script src="/static/asciinema-player.min.js"></script>
+
+## *seitan* was at [DevConf.CZ 2023](https://devconfcz2023.sched.com/event/1MYkc/seitan-a-plant-based-recipe-against-syscall-anxiety)! Check out the [slides](https://seitan.rocks/static/seitan_devconf_2023.pdf) and the [recording](https://seitan.rocks/static/seitan_devconf_2023.webm)
+
+<div style="display: grid; grid-template-columns: 60% auto;">
+<div>
+ <img src="/static/seitan.svg" alt="seitan diagram">
+</div>
+<div style="text-align: justify">
+
+<h2>
+<i>seitan</i> is a framework to filter, transform and impersonate system calls,
+enabling privilege reduction in container and virtualisation engines
+</h2>
+
+It allows you to filter and replay only the system calls you need, instead of
+running things as root, or granting capabilities to processes.
+
+<ul>
+<li><pre style="display: inline">seitan-cooker</pre> builds a BPF program and a
+ bytecode file (<i>gluten</i>) from a recipe with matches on system calls and
+ corresponding actions</li>
+<li><pre style="display: inline">seitan-eater</pre> loads the BPF program
+ associated to the process context into the kernel, and runs the target
+ process. Container engines such as Podman can directly load this program via
+ OCI annotations instead</li>
+<li><pre style="display: inline">seitan</pre> is the supervisor, getting
+ notifications via <pre style="display: inline">seccomp_unotify</pre>,
+ interpreting them according to <i>gluten</i>, and triggering the configured
+ actions as a result</li>
+</ul>
+
+<h5>Note that this project and its documentation still have some rough edges! No versions, no packages yet.</h5>
+
+<h4>Do you want to know more?</h4>
+Watch the <a href="#demo-handle-and-impersonate-connect-of-a-target-process-in-several-ways">demos</a> below, ask your questions on the
+users'
+<a href="https://lists.seitan.rocks/postorius/lists/seitan-user.seitan.rocks/">list</a>,
+<a href="https://matrix.to/#/#seitan:libera.chat">chat</a> with us.
+
+<h4>Do you want to contribute?</h4>
+Send patches to the development
+<a href="https://lists.seitan.rocks/postorius/lists/seitan-dev.seitan.rocks/">list</a>...
+<u><b>and</b></u> <a href="https://matrix.to/#/#seitan:libera.chat">chat</a> with us!
+
+</div>
+</div>
+
+## Demo: handle and impersonate `connect()` of a target process in several ways
+
+<div id="demo_connect" style="width: 99%;"></div>
+
+## Demo: issue `mknod()` on behalf of a Podman container
+
+<div id="demo_mknod" style="width: 99%;"></div>
+<script>
+AsciinemaPlayer.create('/static/seitan-connect.cast',
+ document.getElementById('demo_connect'),
+ { cols: 112, rows: 24, preload: true, poster: 'npt:0:2' });
+AsciinemaPlayer.create('/static/seitan-mknod.cast',
+ document.getElementById('demo_mknod'),
+ { cols: 112, rows: 24, preload: true, poster: 'npt:0:2' });
+</script>