Documentation should explain why things are security issues, at least briefly
In my discussion of Apache suexec I
mentioned the apache2-suexec-custom Debian package, which allows
you to change suexec's idea of its docroot and thus use suexec
to run virtual host CGIs that aren't located under
you're using suexec-custom, one of the obvious questions is what
it's safe to set the suexec docroot to. If you read the manpage,
you will hit this paragraph:
Do not set the [suexec] document root to a path that includes users' home directories (like /home or /var) or directories where users can mount removable media. Doing so would create local security issues. Suexec does not allow to set the document root to the root directory /.
This is all that the manpage has to say about this. In fact, this is all of the documentation you get about the security issues involved, period.
Perhaps the people who wrote this documentation felt that the
security issues created here are obvious to everyone. If so, they
were wrong. I at least have no idea what specifically makes including
user home directories dangerous. It seems unlikely to be that users
can create new executables, because if you're doing virtual hosting
and using suexec, you're presumably already giving all of those
different virtual hosting UIDs write access to their subdirectory
/var/www so they can set up their own CGIs. After all, suexec
explicitly requires all of those CGIs and their containing
directories to be owned by the target user, not you. And after that,
what is there that applies to user home directories but not
(It can't be that suexec will run arbitrary programs under user
home directories, because suexec has to be run through Apache and
you should not be telling Apache 'treat anything at all under this
entire general directory hierarchy as a CGI through these URL'. If
you tell Apache that your CGI-BIN directory is
or the like, you have already made a horrible mistake.)
This is a specific example of what is a general failing, namely not explaining why things are security issues. When you don't explain why things are a security problem, you leave people uncertain about what's safe and what isn't. Here, I've been left with no idea about what the important security properties of suexec's docroot actually are. The authors of the manpage have in mind some dangers, but I don't know what they are and as a result I don't know how to avoid them. It's quite possible that this will result in me accidentally configuring Apache and suexec in a subtly insecure way.
The explanation of why things are a security issue doesn't have to be deep and detailed; I don't demand, say, an example of how to exploit an issue. But it should be detailed enough that an outsider can see clearly what they need to avoid and broadly why. If you say 'avoid this general sort of setup', you need to explain what makes that setup dangerous so that people can avoid accidentally introducing a dangerous bit in another setup. Vagueness here doesn't help anyone.
(As a corollary, if you say that a general sort of setup is safe, you should probably explain why that's so. Otherwise you risk people making some small, harmless looking variant of the setup that is in fact not safe because it violates one of the assumptions.)
By the way, all of this applies to local system setup documentation too. If you know why something has to be done or not done in a particular way to preserve security, write it down in specific (even if it seems obvious to you now). Future readers of your documentation will thank you for being clear, and as usual this may well include your future self.
PS: It's possible that you don't know of any specific issues in your program but feel that it's probably not safe to use outside of certain narrow circumstances that you've considered in detail. If so, the documentation should just say this outright. Sysadmins and other people who care about the security properties of your program will appreciate the honesty.
A thought on the apparent popularity of new static typing languages
Like [Elben Shira], I've noticed that despite the fact that there have been an enormous number of new programming languages coming out recently, the overwhelming majority of them are statically typed. [...]
I'm an outsider bystander on all of this, but it strikes me that one possible contributing reason for lots of people creating new statically typed languages is that there is a significant body of academic research that has not yet made it into a popular, mainline programming language. Here I'm thinking primarily of sophisticated type systems and type inference. As long as this situation exists, people tempted to create languages have a clear void that their new modern statically typed language might possibly fill (at least in theory).
(And then they can mingle in some degree of immutability and this and that from other academic research. There's a lot of academic work on statically typed languages that hasn't gotten into popular languages yet. There's also a bunch of people who are grumpy about this lack of popularity, which is another crucial ingredient for creating new languages; see, for example, all of the people who are unhappy at Go for having such a simple and 'primitive' type system in the face of much more powerful ones being out there.)
(Arguably you're not very likely to get significant traction for an advanced statically typed language if so many other ones before you have not been hits, but that's somewhat different in that hope springs eternal. It's the same impulse that keeps people writing new Lisp like languages that they want to be popular.)
PS: I could be totally wrong on this in that maybe there's a pile of good academic research on dynamic languages that's begging to be implemented and made popular. I'd actually like that; it'd mean we have the prospect of significantly better and nicer dynamic languages.