diff --git a/_docs/instructor/autograding/specification.md b/_docs/instructor/autograding/specification.md index c5fca1e1..58d472c7 100644 --- a/_docs/instructor/autograding/specification.md +++ b/_docs/instructor/autograding/specification.md @@ -146,11 +146,8 @@ executables. The instructor can also override / customize the default restrictions on use of system calls within the student code by - whitelisting additional categories of system calls: - [grading/system_call_categories.cpp][grading/system_call_categories.cpp] - [grading/seccomp_functions.cpp][grading/seccomp_functions.cpp] - - _FIXME: UPDATE & DOCUMENT_ + allowing additional categories of system calls. + *See also:* [System Call Filtering](/instructor/autograding/system_call_filtering) diff --git a/_docs/instructor/autograding/system_call_filtering.md b/_docs/instructor/autograding/system_call_filtering.md new file mode 100644 index 00000000..7e7ce1f8 --- /dev/null +++ b/_docs/instructor/autograding/system_call_filtering.md @@ -0,0 +1,152 @@ +--- +category: Instructor > Autograding +title: System Call Filtering +--- + + + +We use the GNU/Linux [seccomp](https://en.wikipedia.org/wiki/Seccomp) +"Secure Computing" library to monitor and limit the Linux system calls +that are allowed within untrusted student code. This feature helps +provide server security, manage compute resources, and ensure +adherence to programming assignment requirements. + + +### What are GNU/Linux system calls? What are the Submitty categories of system calls? + +Computer programs access resources from the operating system (e.g., +memory, disks, files, processes, networks, etc.) through +[system calls](https://en.wikipedia.org/wiki/System_call). + +Submitty has organized all available Linux system calls into +categories by purpose. The list of available system calls changes +over time with new versions of the operating system kernel. New +system calls are added *and* the system calls used by +publicly-available programs and libraries may also change accordingly +with new releases. + +The current categories and lists of calls within each category can be +inspected in the Submitty source code: +[grading/system_call_categories.cpp](https://github.com/Submitty/Submitty/blob/main/grading/system_call_categories.cpp) + + +### What system calls are used by a specific program? + +The GNU/Linux [strace](https://strace.io/) utility can be used to +collect all system calls made in a run of a program. First, install +strace on your machine. + +``` +sudo apt-get install strace +``` +*NOTE:* `strace` is already installed on the +Submitty server and many of our sample docker container images for autograding - +hosted on [Dockerhub](https://hub.docker.com/u/submitty) +and created with these +[dockerfiles](https://github.com/Submitty/DockerImages). + + +Then, if this is how you usually run your program: + +``` +my_program.exe argument1 argument2 +``` + +Then you will just prepend `strace` to the command line and capture +the STDERR output stream to a file. + +``` +strace my_program.exe argument1 argument2 2> strace_output.txt +``` + +The captured output is a chronological listing of every system +call. It will look something like this: + +``` +execve("/usr/bin/gcc", ["gcc", "buggy.c"], 0xffffd49434a8 /* 39 vars */) = 0 +brk(NULL) = 0x15d41000 +mmap(NULL, 8192, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0xffff99261000 +faccessat(AT_FDCWD, "/etc/ld.so.preload", R_OK) = -1 ENOENT (No such file or directory) +openat(AT_FDCWD, "/etc/ld.so.cache", O_RDONLY|O_CLOEXEC) = 3 +newfstatat(3, "", {st_mode=S_IFREG|0644, st_size=42636, ...}, AT_EMPTY_PATH) = 0 +mmap(NULL, 42636, PROT_READ, MAP_PRIVATE, 3, 0) = 0xffff99221000 +close(3) = 0 +openat(AT_FDCWD, "/lib/aarch64-linux-gnu/libc.so.6", O_RDONLY|O_CLOEXEC) = 3 +read(3, "\177ELF\2\1\1\3\0\0\0\0\0\0\0\0\3\0\267\0\1\0\0\0\340u\2\0\0\0\0\0"..., 832) = 832 +newfstatat(3, "", {st_mode=S_IFREG|0755, st_size=1637400, ...}, AT_EMPTY_PATH) = 0 +... + +``` + +Once you have the file, you can use the Submitty +`system_call_check.out` utility on a Submitty production installation +or development machine to scan that file and compare it to our current +sytem call categories and generate the set of categories necessary to +allow that program to run within a Submitty autograding configuration. + +``` +/usr/local/submitty/bin/system_call_check.out strace_output.txt +``` + + +### Specifying system calls allowed by student code + +Within the analysis output of the `system_call_checkout.out` utility, +will be the config.json syntax to enable all system calls used by your +program. For example: + +``` +"allow_system_calls" : [ + "COMMUNICATIONS_AND_NETWORKING_INTERPROCESS_COMMUNICATION", + "COMMUNICATIONS_AND_NETWORKING_SIGNALS", + "FILE_MANAGEMENT_MOVE_DELETE_RENAME_FILE_DIRECTORY", + "PROCESS_CONTROL_ADVANCED", + "PROCESS_CONTROL_NEW_PROCESS_THREAD" +] +``` + +You can just copy paste that into your `config.json` either at the +global level, or per test case. + +Alternately, you can simply enable all system calls that are in +*restricted* category: + +``` +"allow_system_calls" : [ "ALLOW_ALL_RESTRICTED_SYSTEM_CALLS" ], +``` + +Again, this can be set at the global level or per-test case. + + +An example autograding configuration using the `"allow_system_calls"` +syntax is here: + +[more_autograding_examples/c_system_call_filtering/config/config.json](https://github.com/Submitty/Submitty/blob/main/more_autograding_examples/c_system_call_filtering/config/config.json) + + +### Attempted use of disallowed system call + +If the execution of student code attempts to use a system call that is +not allowed, the program will be terminated. The error message below +will be placed in the `execute_logfile.txt` for that autograding test +case. This `execute_logfile.txt` will be displayed to the student -- +*unless the autograding configuration specifies that this file should +be hidden from the student*. + +``` +******************************************************************** +* DETECTED USE OF DISALLOWED SYSTEM CALL * +* http://submitty.org/instructor/autograding/system_call_filtering * +******************************************************************** + +Program Terminated +``` + +IMPORTANT NOTE: Unfortunately, the `seccomp` library does not report +*which* disallowed system call was used. + +Students who see this message should first review the programming +assignment instructions and confirm they have followed detailed +instructions about resources and techniques that are allowed. Only +the instructor for the course can modify the list of system calls that +are allowed for autograding that assignment. \ No newline at end of file diff --git a/navtreedata.js b/navtreedata.js index d2bffe15..27ba946c 100644 --- a/navtreedata.js +++ b/navtreedata.js @@ -125,6 +125,7 @@ var NAVTREE = [ "Phases of Autograding", "/instructor/autograding/phases", null ], [ "Autograding Specification", "/instructor/autograding/specification", null ], [ "Distributed / Networked Applications", "/instructor/autograding/networking", null ], + [ "System Call Filtering", "/instructor/autograding/system_call_filtering", null ], [ "Graphics Applications", "/instructor/autograding/graphics", null ], [ "Validation", "/instructor/autograding/validation", null ], [ "Batch Regrade Submissions", "/instructor/autograding/batch_regrade", null ],