{"id":36680602,"url":"https://github.com/cuandari/lib-oss","last_synced_at":"2026-01-12T10:58:12.321Z","repository":{"id":260897613,"uuid":"882265247","full_name":"cuandari/lib-oss","owner":"cuandari","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-10T22:34:09.000Z","size":2391,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-12T03:41:42.541Z","etag":null,"topics":["discue","gatekeeper","go","golang","ptrace","seccomp"],"latest_commit_sha":null,"homepage":"https://www.discue.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cuandari.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-02T10:56:05.000Z","updated_at":"2026-01-10T22:32:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"ff91afc7-086a-4569-9125-b0f02918a646","html_url":"https://github.com/cuandari/lib-oss","commit_stats":{"total_commits":101,"total_committers":2,"mean_commits":50.5,"dds":0.00990099009900991,"last_synced_commit":"16009c8aa9292d67dbcf57a17288ff53c0409569"},"previous_names":["discue/go-syscall-gatekeeper","discue/go-syscall-gatekeeper-cli"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/cuandari/lib-oss","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuandari%2Flib-oss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuandari%2Flib-oss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuandari%2Flib-oss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuandari%2Flib-oss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cuandari","download_url":"https://codeload.github.com/cuandari/lib-oss/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuandari%2Flib-oss/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28338889,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T10:40:25.642Z","status":"ssl_error","status_checked_at":"2026-01-12T10:39:27.820Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["discue","gatekeeper","go","golang","ptrace","seccomp"],"created_at":"2026-01-12T10:58:12.246Z","updated_at":"2026-01-12T10:58:12.312Z","avatar_url":"https://github.com/cuandari.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003cp align=\"center\"\u003e\n  \u003c!-- \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://avatars.githubusercontent.com/u/252919145?s=200\u0026v=4\"\u003e --\u003e\n  \u003cimg alt=\"Cuandari Logo featuring a medieval helmet\" src=\"https://storage.googleapis.com/stfsy-cuandari/cuandari-rounded\" width=\"400\" height=\"400\" style=\"border-radius: 50%\"\u003e\n\u003c/p\u003e\n\n\u003cbr/\u003e\n\u003cdiv align=\"center\"\u003e\n\n[![contributions - welcome](https://img.shields.io/badge/contributions-welcome-blue/green)](/CONTRIBUTING.md \"Go to contributions doc\")\n[![GitHub License](https://img.shields.io/github/license/cuandari/lib-oss.svg)](https://github.com/cuandari/lib-oss/blob/main/LICENSE)\n\u003cbr/\u003e\n[![Go Report Card](https://goreportcard.com/badge/github.com/cuandari/lib-oss)](https://goreportcard.com/report/github.com/cuandari/lib-oss)\n[![Go](https://img.shields.io/github/go-mod/go-version/cuandari/lib-oss\n)](https://github.com/cuandari/lib-oss/blob/main/go.mod)\n\u003cbr/\u003e\n[![lints](https://github.com/cuandari/lib-oss/actions/workflows/lints.yml/badge.svg)](https://github.com/cuandari/lib-oss/actions/workflows/lints.yml)\n[![tests](https://github.com/cuandari/lib-oss/actions/workflows/tests.yml/badge.svg)](https://github.com/cuandari/lib-oss/actions/workflows/tests.yml)\n\u003c/div\u003e\n\n# cuandari/lib - Process Manager with Privilege Restrictions\nGo process manager that can be used to\n- start other processes and control their lifecycle,\n- watch the status of the started process and return appropriate exit codes,\n- and, most importantly, **trace and limit the syscalls of the started process**.\n\nThis allows you to start trusted and untrusted applications (e.g., Go, Python, Node.js) and limit their access to the file system or the network. With simple command-line flags you can easily grant permissions to the started process.\n\n## Use Cases\n- **Securely run untrusted code**: Limit what trusted and untrusted applications can do on your system.\n- **Sandboxing**: Create lightweight sandboxes for applications without the overhead of full VMs or containers.\n- **Testing and debugging**: Trace syscalls to understand application behavior and identify potential issues.\n- **Compliance and auditing**: Enforce strict policies on application behavior for regulatory compliance\n\n## 🤝 Examples\nThis section shows examples of how processes can be started with different levels of permissions and success. See below how the `curl` command fails until both filesystem and network permissions are granted.\n\nWhile it's obvious why `curl` needs network permissions, filesystem permissions are necessary to read, e.g., configuration files and shared libraries.\n\n### ❌ No filesystem permissions\nIn this case, `curl` is only started with a default set of permissions. The command fails because access to the filesystem is denied.\n```bash\n$ gatekeeper run -- curl -v google.com\n[...]\nSyscall not allowed: access\nenter [pid 4855] access (/etc/ld.so.preload)\nPID 4855 exited from signal SIGKILL (killed) (9)\nExiting with code 111\nexit status 111\n```\n\n### ❌ With filesystem permissions, but no permission to access the network\nIn this second 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 socket syscall gets denied.\n```bash\n$ gatekeeper run \\\n  --allow-file-system-read \\\n  -- \\\n  curl -v google.com\n[...]\nSyscall not allowed: socket\nenter [pid 4996] socket\nPID 4996 exited from signal SIGKILL (killed) (9)\nExiting with code 111\nexit status 111\n```\n\n### ✅ With filesystem and network permissions\nIn this case, `curl` is started with read access to the filesystem **and** network. The command then exits with success.\n```bash\n$ gatekeeper run \\\n  --allow-file-system-read \\\n  --allow-network-client \\\n  --allow-network-local-sockets \\\n  -- \\\n  curl -v google.com\n[...]\n\u003cHTML\u003e\u003cHEAD\u003e\u003cmeta http-equiv=\"content-type\" content=\"text/html;charset=utf-8\"\u003e\n\u003cTITLE\u003e301 Moved\u003c/TITLE\u003e\u003c/HEAD\u003e\u003cBODY\u003e\n\u003cH1\u003e301 Moved\u003c/H1\u003e\nThe document has moved\n\u003cA HREF=\"http://www.google.com/\"\u003ehere\u003c/A\u003e.\n\u003c/BODY\u003e\u003c/HTML\u003e\n[...]\nPID 5255 exited from exit status 0 (code = 0)\nExiting with code 0\n```\n\n### ✅ With filesystem and network permissions\nIn this case, `curl` is started with read access to only specific folders **and** network. The command then exits with success.\n```bash\n$ gatekeeper run \\\n  --allow-file-system-read \\\n  --allow-network-client \\\n  --allow-network-local-sockets \\\n  --allow-file-system-path=/etc \\\n  --allow-file-system-path=/lib/x86_64-linux-gnu \\\n  --allow-file-system-path=/usr/lib \\\n  --allow-file-system-path=/usr/share \\\n  --allow-file-system-path=/proc/sys/crypto \\\n  --allow-file-system-path=/home/stfsy \\\n  -- \\\n  curl -v google.com\n[...]\n\u003cHTML\u003e\u003cHEAD\u003e\u003cmeta http-equiv=\"content-type\" content=\"text/html;charset=utf-8\"\u003e\n\u003cTITLE\u003e301 Moved\u003c/TITLE\u003e\u003c/HEAD\u003e\u003cBODY\u003e\n\u003cH1\u003e301 Moved\u003c/H1\u003e\nThe document has moved\n\u003cA HREF=\"http://www.google.com/\"\u003ehere\u003c/A\u003e.\n\u003c/BODY\u003e\u003c/HTML\u003e\n[...]\nPID 5255 exited from exit status 0 (code = 0)\nExiting with code 0\n```\n\n## 📦 Installation\nInstall the package:\n\n```bash\ngo get https://github.com/cuandari/lib-oss\n```\n\n## 🔣 Usage\n```bash\n./gatekeeper [run|trace] [flags] -- [binary] [args...]\n```\n\n### 🤺 Permissions\nYou can pass the following flags.\n\n- Triggers \u0026 verbosity:\n  - `--trigger-enforce-on-log-match` — Enable enforcement when trace output contains this string (use with `--enforce-on-startup=false`).\n  - `--trigger-enforce-on-signal` — Enable enforcement upon receiving this signal (name or number, use with `--enforce-on-startup=false`).\n  - `--verbose` — Enable verbose decision logging from the tracer.\n\n- Filesystem:\n  - `--allow-file-system-read` — Allow read-only filesystem access (open O_RDONLY, read, stat, list).\n  - `--allow-file-system-write` — Allow modifying the filesystem (create, write, rename, unlink, truncate).\n  - `--allow-file-system` — Alias for `--allow-file-system-write` (full read/write filesystem access).\n  - `--allow-file-system-permissions` — Allow changing file ownership and permissions (chmod/chown/fchmod/fchown*).\n  - `--allow-file-system-path` — Allow whitelisting specific filesystem paths (repeatable); **paths should be absolute**. Example: `--allow-file-system-path=/etc` `--allow-file-system-path=/lib`. When provided, access is restricted to the listed directories (useful to grant minimal read access without enabling broad filesystem permissions).\n\n- Network \u0026 sockets:\n  - `--allow-network-client` — Allow outbound network connections (socket/connect/send/recv).\n  - `--allow-network-server` — Allow listening sockets and incoming connections (socket/bind/listen/accept).\n  - `--allow-network-local-sockets` — Allow local-only sockets (AF_UNIX, AF_NETLINK) for client use.\n  - `--allow-networking` — Enable both client and server networking capabilities.\n\n- Process \u0026 runtime:\n  - `--allow-process-management` — Allow process/thread creation and lifecycle control (exec/fork/clone/wait).\n  - `--allow-memory-management` — Allow memory mapping and related syscalls (mmap/mprotect/mremap/brk).\n  - `--allow-signals` — Allow setting and handling POSIX signals (rt_sig*, sigaltstack).\n  - `--allow-timers-and-clocks-management` — Allow timers and clocks (clock_gettime, timerfd_*, nanosleep).\n  - `--allow-security-and-permissions` — Allow identity/capability changes and seccomp (setuid/setgid/capset/seccomp). Risky; enable only if needed.\n  - `--allow-system-information` — Allow system information and rlimit operations (uname/sysinfo/getrlimit/setrlimit).\n  - `--allow-process-communication` — Allow IPC mechanisms (SysV shared memory, semaphores, mqueue).\n  - `--allow-process-synchronization` — Allow synchronization primitives (futex/flock/robust list).\n  - `--allow-misc` — Allow miscellaneous syscalls (includes ioctl, splice, vmsplice).\n\n- Enforcement / baseline / action:\n  - `--enforce-on-startup` (default true) — Start with enforcement enabled on startup.\n  - `--allow-implicit-commands` (default true) — Enable the safe baseline implicit permissions (enabled by default).\n  - `--on-syscall-denied {kill|error}` — Action when a syscall is denied: `kill` (SIGKILL) or `error` (simulate EPERM via SIGSYS).\n\n\n\n## Baseline\nBy default (unless you pass `--allow-implicit-commands=false`), gatekeeper enables a safe baseline including process management, memory, synchronization, signals, basic time queries and sleep (`clock_gettime`, `gettimeofday`, `nanosleep`), miscellaneous, security, and system information. This avoids breaking common applications that need time functions without requiring extra flags. Use `--allow-timers-and-clocks-management` for the full timers/clock set (e.g., `timerfd_*`, `setitimer`), or keep the default minimal set for tighter policies. If you only need to permit access to a small set of directories (for example, `/etc` or `/lib`), prefer `--allow-file-system-path` to whitelist those paths instead of granting broad filesystem read/write permissions. To explicitly disable the implicit baseline, pass `--allow-implicit-commands=false`. (Note: this flag replaces older `--no-implicit-allow`-style usage.)\n\n#### Dynamically allow individual syscalls\nIn addition to grouped permissions, you can enable specific syscalls directly from the CLI without modifying configuration files. This is useful for targeted exceptions.\n\n- `--allow-syscall-\u003cname\u003e`: allow a single syscall by name.\n- `--allow-syscall=\u003cname\u003e`: equivalent form using `=`.\n\n### 🔎 Trace\nThe `trace` subcommand runs the given binary and traces its syscalls. For example:\n\n```bash\n./gatekeeper trace ls -l\n```\n\n## 🧪 Running Unit Tests\nTo run tests, run the following command\n\n```bash\n./test.sh\n```\n\n# 🚧 Running E2E Tests\nTo run the end-to-end tests, run the following command\n\n```bash\n./test-e2e.sh\n```\nThis will run all the end-to-end tests located in the `test-e2e` directory.\n\n## 📄 License\n[BSD 3-Clause](https://choosealicense.com/licenses/bsd-3-clause/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuandari%2Flib-oss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcuandari%2Flib-oss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuandari%2Flib-oss/lists"}