Open Source


System Integration


Aquinas is a system which aims to help teach people how to program. Teachers define programming projects, and students complete the projects and submit their work using Git. Aquinas provides a website which lists the projects and provides a summary of each student’s progress.

A number of goals drove the design of Aquinas:

  1. Allow for projects which involve network programming and exploit development.

  2. Facilitate easy-to-define projects with a consistent specification language.

  3. Ease reuse of projects across many programming languages.

  4. Allow for high-quality assignment instructions.

  5. Provide a web- and Git-based interface to students.

  6. Provide for automated grading and student feedback.

  7. Apply the principle of least privilege and use a type-safe language.

Installing Aquinas

  1. Edit aquinas.json to facilitate installing Aquinas at your site.

  2. Run “make”. This will build some utilities and the Aquinas VMs.

  3. Install each disk image (e.g., aquinas-git-openwrt-x86-64-combined-ext4.img) and each domain configuration (e.g., vm-aquinas-git.cfg) so that they can be run by your hypervisor.

  4. Update your DHCP service to provide the correct IP address to each domain. Refer to each domain configuration for the host’s MAC address.

  5. Update your DNS service to provide an appropriate A record for each domain. Refer to each domain configuration for the host’s name.

  6. Configure syslog-ng on each VM. The aquinas-user and aquinas-target VMs must be configured to reference a log server by IP address, as their firewall prohibits DNS queries.

  7. Start each configured VM.

  8. On your development computer, run “./aquinas-setup-ssh”.

  9. On aquinas-www, run “sudo -u http aquinas-add-student test PASSWORD”.

  10. On your development computer, run “./aquinas-add-teacher ~/.ssh/”.

  11. Push a projects repository to aquinas-git:/mnt/xvdb/teacher/projects.

  12. Push a records repository to aquinas-git:/mnt/xvdb/teacher/records.

  13. Push the HTML documents to aquinas-www.

  14. On your development computer and from directory test/, run “./test-all.”

Writing a project

Writing a project is a matter of creating a machine-readable JSON file to define the project and a LaTeX fragment to instruct students in how to complete the project.

Project definition

Here is the definition of a very simple project named unix. The absence of the checks keyword means that Aquinas will not grade this project. Because languages is set to none, Aquinas will generate no language-specific variants of this project. Perhaps this project could guide the student through an introduction to UNIX without requiring a graded deliverable.

        "name": "unix",
        "languages": [ "none" ]

Here is another language-agnostic project. This project, git, assumes the completion of unix. Aquinas will take this into account when ordering the list of projects presented to a student. This project provides a check (checks); running the command cat NOTES from the root of the student’s Git repository should print “In case of fire: git commit, git push, and leave the building!” to standard out. (I.e., the file NOTES should exist in the Git repository and it should contain “In case of fire: …”)

The value in the stdout field is this string, base64 encoded (but not depicted in its entirety here). The base64 encoding is to allow such values to contain binary data.

    "name": "git",
    "languages": [ "none" ],
    "prerequisites": [ "unix" ],
    "checks": [{ "command": "cat NOTES",
                 "stdin": null,
                 "stdout": "SW4gY2Fz...",
                 "stderr": null,
                 "exitCode": 0

A student may submit the following project in C or Python. In the case of C, the submission should contain hello.c, and this file should compile to a program which prints “Hello, world\n”. A Python submission should take the form of hello as an executable script (i.e., with shebang). As with the previous example, the value of stdout is base64 encoded to support binary data.

    "name": "hello",
    "languages": [ "C", "Python" ],
    "prerequisites": [ "git" ],
    "checks": [{ "command": "./hello",
                 "stdin": null,
                 "stdout": "SGVsbG8sIHdvcmxkIQo=",
                 "stderr": null,
                 "exitCode": 0

Project instructions

Teachers write project instructions in the form of a LaTeX fragment, which Aquinas combines with a template before processing into a HTML document. It is a good practice to use \section* to provide three sections: Command (or Function) summary, Lesson, and Assignment. Aquinas will provide the prelude and epilog material; here it is sufficient to begin with the first \section*.

Aquinas provides the following LaTeX commands for use in a project’s instructions:

Typeset the argument as a command.
Typeset the argument as a project name.
Typeset the argument as a configuration file.
Typeset the argument as a file name.
Typeset the argument as a directory name.
Typeset the argument as a function name.
Typeset the argument as a host name.
Typeset the argument as if it were a key to be pressed.
Typeset the work UNIX.
Typeset a Bourne shell prompt.
Define a command within a LaTeX description list. Like \item, except Aquinas notes occurences of \cmddesc to produce a command reference page.
Define a C function within a LaTeX description list. Like \item, except Aquinas notes occurences of \fncdesc to produce a C function reference page.
Define a Python function within a LaTeX description list. Like \item, except Aquinas notes occurences of \fncdesc to produce a Python function reference page.
If the language associated with the current project variant matches the first argument, then print the second argument. Otherwise print nothing.
If the language can make use of a shebang, then print the second argument. Otherwise print nothing.
Provide instructions on how to clone the current project using Git.
Print instructions on how to submit a project solution.
Print instructions on how to submit a language-agnostic project solution.

The Aquinas VMs

The HTTP server which allows users to read project assignments and view submission results.
The Git server to which users make project submissions.
The host which runs project submissions during the grading process.

System inputs

(unauthenticated) http://aquinas-www/landing.html
Allows a user to either log in or register.
(unauthenticated) http://aquinas-www/login.html
Accepts student email and password. Allows a student to log in to the web interface. Transitions state of HTTP session to authenticated.
(unauthenticated) http://aquinas-www/register.html
Accepts an email address. Allows a registering student to initiate the registration process. Sends an email to the registering student which allows him to complete the registration.
(unauthenticated) http://aquinas-www/register3.html
Accepts an email address, nonce, hashed token, and password. Allows a registering student to prove ownership of an email address and thus complete the registration process.
(authenticated) http://aquinas-www/index.html
Allows a student to select a project page.
(authenticated) http://aquinas-www/p.html, where p is a project
Allows a student to view information which describes project p.
ssh://s@aquinas-git/mnt/xvdb/s/p, where s is a student and p is a project
Interact with student s’s project p submission using Git/git-shell. Git hook invokes grader, run as teacher, with s and p as its input.
ssh://t@aquinas-git/mnt/xvdb/teacher/projects, where t is a teacher
Interact with the project definitions using Git/git-shell. Git hook invokes aquinas-initialize-projects, run as root.
ssh://t@aquinas-git/mnt/xvdb/teacher/records, where t is a teacher
Interact with the project submission records using Git/git-shell.
Allows developers shell access.

Sudo permissions


SSH keys

generated by openwrt-build
generated by openwrt-build
generated by openwrt-build

Permitted SSH connections

From To Installed by Purpose
Developers root@aquinas-git openwrt-build/manual Development/administration
http@aquinas-www http@aquinas-git setup-ssh Httpd uses to run httpsh:
check for student
check for SSH key
add a new student
deploy SSH key
remove a student
Developers test@aquinas-git test case Pushing solutions during
Teachers teacher@aquinas-git add-teacher Project deployment
Developers root@aquinas-user openwrt-build/manual Development
teacher@aquinas-git root@aquinas-user setup-ssh Used by initialize-project
to pull host key and user
key from aquinas-user
(Cannot use test@, because
test has shell set to
Also used by grader to place
user-submitted code on
root@aquinas-git root@aquinas-user setup-ssh Add or remove user.
teacher@aquinas-git test@aquinas-user add-student Grader uses to run buildrunsh
on user VM; Git hook runs as
user, and uses sudo to run
grader as teacher
Developers root@aquinas-www openwrt-build/manual Development/administration
Teachers teacher@aquinas-www add-teacher Updating HTML documents
teacher@aquinas-git teacher@aquinas-www setup-ssh Used by grader to update
records on aquinas-www

Firewall rules

The host firewalls on aquinas-user and aquinas-target prohibit all outgoing connections with the exception of a connection to a syslog server. All interaction with these hosts is by way of incoming SSH connections or project-specific services. The aim of this is to prevent a user-written program from exfiltrating data from either host while being executed for the purpose of grading.

Email: — ✉ 6110 Campfire Court; Columbia, Maryland 21045; USA