# How can you trust this software package?

For a while, Dusk OS was distributed through git with signed commits on
releases. With Dusk itself gaining networking capabilities, it's going to end
up being distributed as unsigned tarballs through a gopher server, running on
Dusk of course.

"Unsigned? that's scary" will you say. Indeed, it is. A middle-man could sneak
in malicious code in there and ruin your day. However, I believe that the
compactness of this code makes the audit approach much more doable than with
other OSes.

As small as Dusk is, it's still a pretty big task to audit it entirely. What if
all you want to do is try it for evaluation purposes? It might not be worth the
trouble.

The good news is, it's possible to do a quick and partial audit of Dusk in
order to protect against the scariest threat: exfiltration of private data
stored on the UNIX system you'll try Dusk on.

This is the threat we're talking about in this document. We don't care about
security threats of a Dusk system running bare metal because it's unlikely that
you'll place important private data on that system before you know Dusk
entirely.

Of course, if this package you've downloaded is compromised, so could this
file. However, the instructions here happen to be self-verifiable. If you
reason about them, you'll know them to be true and complete.

Data exfiltration, if this package is comprimised, can happen at two stages:
build time and run time.

## Build time threats

The README says that to build Dusk, you must run "make". It means that it all
begins with the Makefile. Luckily, Dusk's Makefiles are pretty simple. There's
a few support shell scripts that are ran eagerly, like "getarch.sh",
"getplat.sh" and "embed.sh", but these are trivially auditable.

If you look at the rest of it, except for "runners" (make commands that are
helpers for running Dusk in a certain way), it's 100% cc and cat calls.

I don't think it's possible for C macros to open files in ways that could
result in data exfiltration at build time, but who knows, maybe it's possible.
So what if we worry about that? You can look at the C files referenced in the
Makefile, looking for weird-ass macros. Luckily, there really aren't that many
of those C files. This is a Forth project, remember?

Therefore, if you run the dependency chain of the "dusk" command, you can
pretty quickly come to the conclusion that running "make dusk" is safe.

Now, note that I'm only talking about "make dusk" here. If you look at the
makefiles in the "usermode" directory, you'll see that the "dusk" executable
built with "make dusk" is ran at build time, so in that case, build time
threats and runtime threats are the same.

## Runtime threats

Runtime is trickier. This thing is turing complete and very much can happen
when running code. But if the threat we're looking for is data exfiltration,
we know that file access is required, so we can look for that.

Luckily, the "dusk" executable doesn't need any file access. The file system
it runs on is an in-memory tarball. If your host system has ways to sandbox
that executable to prevent it from any file access, then your problem is
already solved. Sandbox that thing!

Otherwise, an audit is necessary. The nice thing here is that the Forth code
running in that "dusk" executable has few ways to do I/Os. It must use the hooks
that have been defined in the C source files wrapping the thing.

The "dusk" executable is in fact a ARM emulator. Being an emulator nicely
sandboxes the whole thing, which means that those hooks actually are the only
ways that Forth code can escape its little world.

And you know what? those C files are pretty small and auditable. For example,
if that "dusk" executable wants to open a file from the host system, its only
way to do so is in "posix/fd.c". You could replace those hooks with noops.

Of course, because we're dealing with the possibility of malicious code having
been inserted, you have to review all C files, but there's really not that much
code to review and you know what to look for, that is, calls to I/O functions.

So, all in all, I think that ensuring that "make dusk && ./dusk" is safe,
regardless of whether you can trust the integrity of this software package, is
a pretty doable thing.

IMPORTANT NOTE: Here I'm talking exclusively about the "dusk" executable at the
root of the project, which is an emulator. Usermode Dusk is a different beast
that executes code natively. Malicious code running inside Usermode Dusk could
generate binary code doing any kernel syscall and execute that code, bypassing
hooks.

## Building Dusk for a bare-metal target

This is all well and good, but the emulated "dusk" executable isn't really what
Dusk is about. Full Dusk powers show up when ran on real machines, which mean
building Dusk for a particular target. Once you have Dusk running on your
target, then you don't have to worry about data exfiltration anymore.

To do this, you'll have to review the makefile of the particular port you're
building, which again is pretty simple.

But here's, there's one hurdle: you know when you made file I/Os into noops?
We'll, you're likely to have to let them through now because when Dusk builds
an image, it usually does so through these hooks.

The good news however it that it does so on *one* particular file, so you can
transform your hook into something that is very restrictive about what it lets
through.

And then that's it! You have your Dusk build, you can run it on a separate
machine, far from your sensitive data.

## What about buffer overflows?

The man-in-the-middle, if he's fancy, could maliciously insert a buffer
overflow vulnerability in the ARM emulator (or exploit one that's already
there) and then insert binary code that hooks into syscalls, as described
above.

It's a possibility, it's true, and that means that the whole Dusk OS code needs
to be audited to protect against that possibility. However, I believe that this
kind of audit can be done rather quickly.

First of all, this kind of exploit can't possibly not look *weird* compared to
the rest of the Dusk code. It's going to involve binary blobs and stuff. The
thing is, there just isn't that many binary blobs in Dusk! I like to think that
such code would be easy to spot. I like to think that only a cursory look is
required here.

What I'd recommend here is to know beforehand a binary blob generating a
syscall would look like for your host architecture (for example, INT 0x80 for
x86 32-bit) and scan for that kind of thing.

But otherwise, yeah, maybe that running the "dusk" executable in a sandbox is
the easy way. Monitor if it tries to open a file at all to know if that code
has been meddled with.

## This effort is one-time only

Once you've done the audit once, you're good. Further releases are trivial to
audit because the volume of code to diff just isn't that big at all.
