{"id":13439711,"url":"https://github.com/adtac/fssb","last_synced_at":"2025-04-06T10:11:45.731Z","repository":{"id":55131718,"uuid":"76869021","full_name":"adtac/fssb","owner":"adtac","description":"A filesystem sandbox for Linux using syscall intercepts.","archived":false,"fork":false,"pushed_at":"2020-12-19T19:50:31.000Z","size":55,"stargazers_count":402,"open_issues_count":5,"forks_count":42,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-04-06T05:40:25.193Z","etag":null,"topics":["c","filesystem","linux","sandbox"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adtac.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-19T14:29:57.000Z","updated_at":"2025-03-25T21:46:49.000Z","dependencies_parsed_at":"2022-08-14T13:00:16.590Z","dependency_job_id":null,"html_url":"https://github.com/adtac/fssb","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adtac%2Ffssb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adtac%2Ffssb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adtac%2Ffssb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adtac%2Ffssb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adtac","download_url":"https://codeload.github.com/adtac/fssb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247464222,"owners_count":20942970,"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":["c","filesystem","linux","sandbox"],"created_at":"2024-07-31T03:01:16.446Z","updated_at":"2025-04-06T10:11:45.708Z","avatar_url":"https://github.com/adtac.png","language":"C","readme":"# FSSB - Filesystem Sandbox for Linux\n\n## What is FSSB?\n\n**FSSB** is a sandbox for your filesystem. With it, you can run any program\nand be assured that none of your files are modified in any way. However, the\nprogram will not know this - every change it attempts to make will be made\nsafely in a sandbox while still allowing it to read existing files. This\nincludes creating, modifying, renaming, and deleting files.\n\nThe applications are endless:\n\n * Run arbitrary binaries that you don't trust safely (maybe you downloaded it from the internet).\n * FSSB provides a safe, repeatable environment for programs. This can be useful for debugging programs.\n * Make dry runs to see how a program behaves keeping your files intact. You can see exactly what changes the program made.\n\nPlease note that FSSB is still in alpha. Check out the `Contributing` section\nif you'd like to contribute.\n\n## Installation\n\nFSSB is a very lightweight application. It doesn't require too many\ndependencies. On most systems, you only need to install the `openssl`\nC library. And then, you can run:\n\n```bash\n$ make\n```\n\nto generate a binary `fssb`.\n\n## Usage\n\nFSSB is designed with simplicity in mind. Just do:\n\n```bash\n$ ./fssb -- \u003cprogram\u003e \u003cargs\u003e\n```\n\nto run the program in a safe, dependable, sandboxed environment.\n\nFor example, say we have a Python program `program.py`:\n\n```py\nwith open(\"new_file\", \"w\") as f:  # create a new file in the current directory\n    f.write(\"Hello world!\")       # write something\n\nwith open(\"new_file\", \"r\") as f:  # read the same file later on\n    print(f.read())               # print the contents to console\n```\n\nNormally, running `python program.py` would result in a file:\n\n```bash\n$ python program.py\nHello world!\n```\n\nThis, of course, would have created a file:\n\n```\n$ cat new_file\nHello world!\n```\n\nHowever, if you run it wrapped around FSSB:\n\n```bash\n$ ./fssb -m -- python program.py\nHello world!\nfssb: child exited with 0\nfssb: sandbox directory: /tmp/fssb-1\n    + 25fa8325e4e0eb8180445e42558e60bd = new_file\n```\n\nyou'll see that there's no file created:\n\n```bash\n$ cat new_file\ncat: new_file: No such file or directory\n```\n\nInstead, the file is actually created in a sandbox:\n\n```bash\n$ cat /tmp/fssb-1/25fa8325e4e0eb8180445e42558e60bd\nHello world!\n```\n\nAnd the best part is, the running child program doesn't even know about it!\n\nYou can run `./fssb -h` to see more options.\n\n## Neat. How does this work?\n\nIn Linux, every program's every operation (well, not every operation; most)\nis actually made through something called a system call - or syscall for\nshort. The `open` command in Python is actually a `fopen` command written\nin C a layer below, which is actually a syscall called `open`\n(this is wrapped by `glibc`).\n\nFSSB *intercepts* these syscalls before they are actually performed. For example\njust before the `open` syscall is performed, the program is stopped. Now, each of\nthese syscalls have arguments. For example, a `fopen(\"new_file\", \"w\")` in C\nmay actually look like:\n\n```\nopen(\"new_file\", O_WRONLY|O_CREAT|O_TRUNC, 0666) = 3\n```\n\nThe first argument is the filename, the second are the flags, the third is\nthe mode. To learn more about these, run `man -s 2 open`.\n\nEach syscall can have at most 6 arguments - these map to six CPU registers,\neach of which hold a value. In the above example, just before the\n`open` syscall is executed, the first register holds a memory address pointing\nto a string `\"new_file\"`.\n\nAnyway, just before the syscall is executed, FSSB *switches* the string to\nsomething else - to a filename in the sandbox. And then lets the syscall go on.\nTo the CPU, you basically asked to create a file in the sandbox. So it does.\n\nThen just after the syscall finishes (after the file is created), FSSB switches the\nvalue to its original value. Now, syscalls are pretty low-level. And we're operating\non either sides of a syscall - just before and after its execution. So the program\nhas no way of knowing that the file was actually created in the sandbox. Every\nsubsequent operation is actually performed on the sandbox file.\n\n## Contributing to the FSSB project\n\nThis is still in its alpha stage. There are so many syscalls - at the moment, there's\nsupport for sandboxing of:\n\n* creating new files\n* modifying existing files\n* deleting files\n* renaming files\n* reading files\n\nThere's still a lot of stuff to do. And I'd really appreciate help over here.\nI've tried to make the code very readable with looots of comments and\ndocumentation for what each thing does.\n\nAnd of course, I've only implemented this for my x86_64 linux system. I'd\ngreatly appreciate any help if someone could make this portable to other archs\n(please take a look at the `syscalls.h` file for this).\n\n## License\n\n```\n    FSSB - Filesystem Sandbox for Linux\n    Copyright (C) 2016 Adhityaa Chandrasekar\n\n    This program is free software: you can redistribute it and/or modify\n    it under the terms of the GNU General Public License as published by\n    the Free Software Foundation, either version 3 of the License, or\n    (at your option) any later version.\n\n    This program is distributed in the hope that it will be useful,\n    but WITHOUT ANY WARRANTY; without even the implied warranty of\n    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n    GNU General Public License for more details.\n\n    You should have received a copy of the GNU General Public License\n    along with this program.  If not, see \u003chttp://www.gnu.org/licenses/\u003e.\n```\n\nSee the [LICENSE](LICENSE) file for more details.\n","funding_links":[],"categories":["C","c","CLI Utilities"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadtac%2Ffssb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadtac%2Ffssb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadtac%2Ffssb/lists"}