{"id":13575441,"url":"https://github.com/google/kafel","last_synced_at":"2025-04-04T22:31:04.966Z","repository":{"id":53719425,"uuid":"68689779","full_name":"google/kafel","owner":"google","description":"A language and library for specifying syscall filtering policies.","archived":false,"fork":false,"pushed_at":"2024-07-25T20:05:01.000Z","size":264,"stargazers_count":310,"open_issues_count":6,"forks_count":50,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-03-22T00:42:03.455Z","etag":null,"topics":["linux","seccomp-filter","security","syscalls"],"latest_commit_sha":null,"homepage":"http://google.github.io/kafel","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/google.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING","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}},"created_at":"2016-09-20T08:14:32.000Z","updated_at":"2025-03-05T05:53:59.000Z","dependencies_parsed_at":"2024-01-14T09:14:19.356Z","dependency_job_id":"ecdd0698-165a-4b71-b74f-3211bf6c7c6a","html_url":"https://github.com/google/kafel","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fkafel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fkafel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fkafel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fkafel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google","download_url":"https://codeload.github.com/google/kafel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247260450,"owners_count":20910006,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["linux","seccomp-filter","security","syscalls"],"created_at":"2024-08-01T15:01:01.078Z","updated_at":"2025-04-04T22:31:00.689Z","avatar_url":"https://github.com/google.png","language":"C","readme":"# WHAT IS IT?\nKafel is a language and library for specifying syscall filtering policies.\nThe policies are compiled into BPF code that can be used with seccomp-filter.\n\nThis is NOT an official Google product.\n\n# Usage\n\n## With verbose error reporting\n```c\nstruct sock_fprog prog;\nkafel_ctxt_t ctxt = kafel_ctxt_create();\nkafel_set_input_string(ctxt, seccomp_policy);\nif (kafel_compile(ctxt, \u0026prog)) {\n  fprintf(stderr, \"policy compilation failed: %s\", kafel_error_msg(ctxt));\n  kafel_ctxt_destroy(\u0026ctxt);\n  exit(-1);\n}\nkafel_ctxt_destroy(\u0026ctxt);\nprctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, \u0026prog, 0, 0);\nfree(prog.filter);\n```\n\n## Without verbose error reporting\n```c\nstruct sock_fprog prog;\nif (kafel_compile_string(seccomp_policy, \u0026prog)) {\n  fputs(\"policy compilation failed\", stderr);\n  exit(-1);\n}\nprctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, \u0026prog, 0, 0);\nfree(prog.filter);\n```\n\n# Policy language\n\nA simple language is used to define policies.\n\nPolicy file consists of statements.\n\nA statement can be:\n * a constant definition\n * a policy definition\n * a policy definition statement\n * a default action statement\n\nPolicy definition statements placed at file scope will be added to the implicit\ntop level policy.\nThis top level policy is going to be compiled.\n\n## Default action statement\n\n```\nDEFAULT the_action\n```\n\nSpecifies that action `the_action` should be taken when no rule matches.\n\nThe default action must be specified just once.\n\nIf the policy file specifies no default actions, the default action will\nbe KILL\n\n## Numbers\n\nKafel supports following number notations:\n * Decimal `42`\n * Hexadecimal `0xfa1`\n * Octal `0777`\n * Binary `0b10101`\n\n## Constant definitions\n\nYou may define numeric constants to make your policies more readable.\nConstant definitions may be placed almost anywhere in the policy file.\nA constant definition cannot be placed inside of a policy definition.\nThe defined constants can then be used anywhere where a number is expected.\n\n```\n#define MYCONST 123\n```\n\n## Policy definitions\n\nPolicy definition is a list of action blocks and use statements separated by\ncommas.\n\n__samples/__ contains some example policies that demonstrate supported features.\n\n### Use statements\n\nA `USE someOtherPolicy` behaves as if `someOtherPolicy` body was pasted in its\nplace. You may only use policies defined before the use statement.\n\nWith use statements you can create meaningful groups of filtering rules that are\nbuilding blocks of bigger policies.\n\n### Action blocks\n\nAction block consist of a target and list of syscall matching rules separated\nwith commas.\n\nTarget of first rule matched is the policy decision.\n\nFollowing table list Kafel targets and their corresponding seccomp-filter\nreturn values.\n\nKafel                          | seccomp-filter\n------------------------------ | ---------------------------\n`ALLOW`                        | `SECCOMP_RET_ALLOW`\n`LOG`                          | `SECCOMP_RET_LOG`\n`KILL`, `KILL_THREAD`, `DENY`  | `SECCOMP_RET_KILL`\n`KILL_PROCESS`                 | `SECCOMP_RET_KILL_PROCESS`\n`USER_NOTIF`                   | `SECCOMP_RET_USER_NOTIF`\n`ERRNO(number)`                | `SECCOMP_RET_ERRNO+number`\n`TRAP(number)`                 | `SECCOMP_RET_TRAP+number`\n`TRACE(number)`                | `SECCOMP_RET_TRACE+number`\n\n### Syscall matching rules\n\nA rules consist of syscall name and optional list of boolean expressions.\n\nList of boolean expressions separated by commas.\nA comma is semantically equivalent to `||` but has the lowest precedence,\ntherefore it may be easier to read.\n\n#### Syscall naming\n\nNormally syscalls are specified by their names as defined in Linux kernel.\nHowever, you may also filter __custom syscalls__ that are not in the standard\nsyscall list.\nYou can either define a constant and use it in place of syscall name or\nutilize `SYSCALL` keyword.\n\n```\n#define mysyscall -1\n\nPOLICY my_const {\n  ALLOW {\n    mysyscall\n  }\n}\n\nPOLICY my_literal {\n  ALLOW {\n    SYSCALL[-1]\n  }\n}\n```\n\n#### Argument filtering\n\nBoolean expressions are used to filter syscalls based on their arguments.\nA expression resembles C language syntax, except that there are no\narithmetic operators.\n\n```\nsome_syscall(first_arg, my_arg_name) { first_arg == 42 \u0026\u0026 my_arg_name != 42 }\n```\n\nBitwise and (`\u0026`) and or ('|') operators can be used to test for flags.\n\n```\nmmap { (prot \u0026 PROT_EXEC) == 0 },\nopen { flags == O_RDONLY|O_CLOEXEC }\n```\n\nYou don't have to declare arguments for well-known syscalls but can just use\ntheir regular names as specified in Linux kernel and `man` pages.\n\n```\nwrite { fd == 1 }\n```\n\n## Include directive\n\nIn order to simplify reuse and composition of policies, kafel provides include\nsupport.\n\n```\n#include \"some_other_file.policy\"\n```\n\nKafel looks for included files only under directories explicitly added to the\nsearch paths.\n\n```c\nkafel_include_add_search_path(ctxt, \"includes/path\");\n```\n\nAdds `includes/path` to search paths - the example include directive will refer\nthen to `includes/path/some_other_file.policy`.\n\nInclude directive is terminated by a newline or a semicolon.\nMultiple files, separated by whitespace, can be specified in one directive.\n\n```\n#include \"first.policy\" \"second.policy\"; #include \"third.policy\"\n```\n\n# Example\n\nWhen used with [nsjail](https://github.com/google/nsjail), the following command allows to create a fairly constrained environment for your shell\n\n```\n$ ./nsjail --chroot / --seccomp_string 'POLICY a { ALLOW { write, execve, brk, access, mmap, open, newfstat, close, read, mprotect, arch_prctl, munmap, getuid, getgid, getpid, rt_sigaction, geteuid, getppid, getcwd, getegid, ioctl, fcntl, newstat, clone, wait4, rt_sigreturn, exit_group } } USE a DEFAULT KILL' -- /bin/sh -i\n```\n```\n[2017-01-15T21:53:08+0100] Mode: STANDALONE_ONCE\n[2017-01-15T21:53:08+0100] Jail parameters: hostname:'NSJAIL', chroot:'/', process:'/bin/sh', bind:[::]:0, max_conns_per_ip:0, uid:(ns:1000, global:1000), gid:(ns:1000, global:1000), time_limit:0, personality:0, daemonize:false, clone_newnet:true, clone_newuser:true, clone_newns:true, clone_newpid:true, clone_newipc:true, clonew_newuts:true, clone_newcgroup:false, keep_caps:false, tmpfs_size:4194304, disable_no_new_privs:false, pivot_root_only:false\n[2017-01-15T21:53:08+0100] Mount point: src:'/' dst:'/' type:'' flags:0x5001 options:''\n[2017-01-15T21:53:08+0100] Mount point: src:'(null)' dst:'/proc' type:'proc' flags:0x0 options:''\n[2017-01-15T21:53:08+0100] PID: 18873 about to execute '/bin/sh' for [STANDALONE_MODE]\n/bin/sh: 0: can't access tty; job control turned off\n$ set\nIFS='\n'\nOPTIND='1'\nPATH='/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin'\nPPID='0'\nPS1='$ '\nPS2='\u003e '\nPS4='+ '\nPWD='/'\n$ id\nBad system call\n$ exit\n[2017-01-15T21:53:17+0100] PID: 18873 exited with status: 159, (PIDs left: 0)\n```\n","funding_links":[],"categories":["C"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Fkafel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle%2Fkafel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Fkafel/lists"}