Skip to content

Commit e3ba92e

Browse files
bmcutlerbmcutler
authored
[Documentation:Autograding] documentation of system call filtering (#680)
Co-authored-by: Barb Cutler <Barb Cutler>
1 parent aa0de19 commit e3ba92e

File tree

3 files changed

+155
-5
lines changed

3 files changed

+155
-5
lines changed

‎_docs/instructor/autograding/specification.md

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -146,11 +146,8 @@ executables.
146146

147147
The instructor can also override / customize the default
148148
restrictions on use of system calls within the student code by
149-
whitelisting additional categories of system calls:
150-
[grading/system_call_categories.cpp][grading/system_call_categories.cpp]
151-
[grading/seccomp_functions.cpp][grading/seccomp_functions.cpp]
152-
153-
_FIXME: UPDATE & DOCUMENT_
149+
allowing additional categories of system calls.
150+
*See also:* [System Call Filtering](/instructor/autograding/system_call_filtering)
154151

155152

156153

‎_docs/instructor/autograding/system_call_filtering.md

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
category: Instructor > Autograding
3+
title: System Call Filtering
4+
---
5+
6+
7+
8+
We use the GNU/Linux [seccomp](https://en.wikipedia.org/wiki/Seccomp)
9+
"Secure Computing" library to monitor and limit the Linux system calls
10+
that are allowed within untrusted student code. This feature helps
11+
provide server security, manage compute resources, and ensure
12+
adherence to programming assignment requirements.
13+
14+
15+
### What are GNU/Linux system calls? What are the Submitty categories of system calls?
16+
17+
Computer programs access resources from the operating system (e.g.,
18+
memory, disks, files, processes, networks, etc.) through
19+
[system calls](https://en.wikipedia.org/wiki/System_call).
20+
21+
Submitty has organized all available Linux system calls into
22+
categories by purpose. The list of available system calls changes
23+
over time with new versions of the operating system kernel. New
24+
system calls are added *and* the system calls used by
25+
publicly-available programs and libraries may also change accordingly
26+
with new releases.
27+
28+
The current categories and lists of calls within each category can be
29+
inspected in the Submitty source code:
30+
[grading/system_call_categories.cpp](https://github.com/Submitty/Submitty/blob/main/grading/system_call_categories.cpp)
31+
32+
33+
### What system calls are used by a specific program?
34+
35+
The GNU/Linux [strace](https://strace.io/) utility can be used to
36+
collect all system calls made in a run of a program. First, install
37+
strace on your machine.
38+
39+
```
40+
sudo apt-get install strace
41+
```
42+
*NOTE:* `strace` is already installed on the
43+
Submitty server and many of our sample docker container images for autograding -
44+
hosted on [Dockerhub](https://hub.docker.com/u/submitty)
45+
and created with these
46+
[dockerfiles](https://github.com/Submitty/DockerImages).
47+
48+
49+
Then, if this is how you usually run your program:
50+
51+
```
52+
my_program.exe argument1 argument2
53+
```
54+
55+
Then you will just prepend `strace` to the command line and capture
56+
the STDERR output stream to a file.
57+
58+
```
59+
strace my_program.exe argument1 argument2 2> strace_output.txt
60+
```
61+
62+
The captured output is a chronological listing of every system
63+
call. It will look something like this:
64+
65+
```
66+
execve("/usr/bin/gcc", ["gcc", "buggy.c"], 0xffffd49434a8 /* 39 vars */) = 0
67+
brk(NULL) = 0x15d41000
68+
mmap(NULL, 8192, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0xffff99261000
69+
faccessat(AT_FDCWD, "/etc/ld.so.preload", R_OK) = -1 ENOENT (No such file or directory)
70+
openat(AT_FDCWD, "/etc/ld.so.cache", O_RDONLY|O_CLOEXEC) = 3
71+
newfstatat(3, "", {st_mode=S_IFREG|0644, st_size=42636, ...}, AT_EMPTY_PATH) = 0
72+
mmap(NULL, 42636, PROT_READ, MAP_PRIVATE, 3, 0) = 0xffff99221000
73+
close(3) = 0
74+
openat(AT_FDCWD, "/lib/aarch64-linux-gnu/libc.so.6", O_RDONLY|O_CLOEXEC) = 3
75+
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
76+
newfstatat(3, "", {st_mode=S_IFREG|0755, st_size=1637400, ...}, AT_EMPTY_PATH) = 0
77+
...
78+
<snip>
79+
```
80+
81+
Once you have the file, you can use the Submitty
82+
`system_call_check.out` utility on a Submitty production installation
83+
or development machine to scan that file and compare it to our current
84+
sytem call categories and generate the set of categories necessary to
85+
allow that program to run within a Submitty autograding configuration.
86+
87+
```
88+
/usr/local/submitty/bin/system_call_check.out strace_output.txt
89+
```
90+
91+
92+
### Specifying system calls allowed by student code
93+
94+
Within the analysis output of the `system_call_checkout.out` utility,
95+
will be the config.json syntax to enable all system calls used by your
96+
program. For example:
97+
98+
```
99+
"allow_system_calls" : [
100+
"COMMUNICATIONS_AND_NETWORKING_INTERPROCESS_COMMUNICATION",
101+
"COMMUNICATIONS_AND_NETWORKING_SIGNALS",
102+
"FILE_MANAGEMENT_MOVE_DELETE_RENAME_FILE_DIRECTORY",
103+
"PROCESS_CONTROL_ADVANCED",
104+
"PROCESS_CONTROL_NEW_PROCESS_THREAD"
105+
]
106+
```
107+
108+
You can just copy paste that into your `config.json` either at the
109+
global level, or per test case.
110+
111+
Alternately, you can simply enable all system calls that are in
112+
*restricted* category:
113+
114+
```
115+
"allow_system_calls" : [ "ALLOW_ALL_RESTRICTED_SYSTEM_CALLS" ],
116+
```
117+
118+
Again, this can be set at the global level or per-test case.
119+
120+
121+
An example autograding configuration using the `"allow_system_calls"`
122+
syntax is here:
123+
124+
[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)
125+
126+
127+
### Attempted use of disallowed system call
128+
129+
If the execution of student code attempts to use a system call that is
130+
not allowed, the program will be terminated. The error message below
131+
will be placed in the `execute_logfile.txt` for that autograding test
132+
case. This `execute_logfile.txt` will be displayed to the student --
133+
*unless the autograding configuration specifies that this file should
134+
be hidden from the student*.
135+
136+
```
137+
********************************************************************
138+
* DETECTED USE OF DISALLOWED SYSTEM CALL *
139+
* http://submitty.org/instructor/autograding/system_call_filtering *
140+
********************************************************************
141+
142+
Program Terminated
143+
```
144+
145+
IMPORTANT NOTE: Unfortunately, the `seccomp` library does not report
146+
*which* disallowed system call was used.
147+
148+
Students who see this message should first review the programming
149+
assignment instructions and confirm they have followed detailed
150+
instructions about resources and techniques that are allowed. Only
151+
the instructor for the course can modify the list of system calls that
152+
are allowed for autograding that assignment.

‎navtreedata.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,7 @@ var NAVTREE =
125125
[ "Phases of Autograding", "/instructor/autograding/phases", null ],
126126
[ "Autograding Specification", "/instructor/autograding/specification", null ],
127127
[ "Distributed / Networked Applications", "/instructor/autograding/networking", null ],
128+
[ "System Call Filtering", "/instructor/autograding/system_call_filtering", null ],
128129
[ "Graphics Applications", "/instructor/autograding/graphics", null ],
129130
[ "Validation", "/instructor/autograding/validation", null ],
130131
[ "Batch Regrade Submissions", "/instructor/autograding/batch_regrade", null ],

0 commit comments

Comments
 (0)