On Fri, Sep 24, 2010 at 01:37:54AM +0200, klondike wrote:
> Well as some of you may remember by June I wrote a document on why
> using gentoo hardened is a good idea explaining some common attacks and
> what were the grsecurity, PAX and hardened features to avoid them.
> 
> I have reread the doc and expanded some parts as work previous to
> formatting it as GuideXML and publishing it on the hardened site
> (probably split in various docs).
> 
> Again I'd like to know your opinions on what should be fixed (if
> anything should).

Hi,

First a few general remarks, not related to the documentation you've 
written. Please, don't hesitate to comment on anything I write, and
don't treat what I write as the absolute truth (I hope it is, but I'm
still only human). Also treat it as constructive criticism.

Oh, and take your time to read it, I don't expect answers within 
minutes ;-)

When we need to write documentation, we should take special care that
the documentation we write is easily maintainable. If there are only a
handful of developers available to maintain the documentation, don't try
to duplicate much of the documentation provided by the projects
themselves (PaX, SELinux, ...) but rather refer to those documents
instead. 

The main reason is that people tend to ignore documentation if they find
something outdated inside it. We don't want people to ignore our
documents because a paragraph on grSecurity is outdated, even though all
Gentoo-related commands (and other info) is still very much valid. You
can easily persuade yourself of this fact if you imagine you're reading
a document on SELinux and it talks about the reference policy, version 1
(rather than 2). I personally tend to skip the document and search for a
more recent one then, even though the document itself may still be 100%
valid.

Because of the maintenance issues we might face, I would suggest a
documentation approach using stages.

First, write up quick reference(s) on how to deal with the various
security projects on Gentoo Hardened. Treat the references as if they
are meant for knowledgeable people (who know how to search for
information) and try sticking with the Gentoo Hardened related
activities & commands. Yes, it's fine to document commands that are not
Gentoo Hardened specific, as long as the commands (and other reference
material) is going to be used by developers and users.

Second (after the quick references), write developer documentation. A
project is only as active as its developers are, so good developer
documentation is a must. Developer documentation has the advantage that
you can assume certain knowledge from the reader, and you don't need to
write it in perfect phrazes. As long as it is understandable (for
non-native English speakers) it's fine.

Only when such documentation is over can we think about user
documentation. User documentation should be focusing on the end goal of
the project (or subprojects). Don't try to duplicate documentation if
the master project (SELinux, grSecurity, ...) offers great
documentation; however, you don't want to refer to documentation of
different distributions (not only for PR reasons, but also because those
documents most often include the policies and principles of those
distributions which may not be up to par with Gentoo Hardened's).

Okay, with that said - good thing it's written, I would hate to repeat
all that verbally ;-) - some feedback on the "GentooHardenedWhy"
document...

- You're starting with the assumption that the reader has knowledge
  about how process memory works. Later on, you explain it a bit more
  but you still use many terms that will be unknown to non-programmers
  (and especially 'standard' system administrators). That's okay, but
  you might want to inform the user about prerequired knowledge before
  diving into the topic.
- I had troubles interpreting the tables that represent the stacks
  first: I didn't really interprete the first headings as being headings
  but rather data (which is really confusing). Also, if one doesn't
  really understand how stacks are used (and how they grow) it might be
  difficult to understand how you come from the "before" to the "after"
  state.
- Of all the protections that Gentoo Hardened provides, I fail to find
  how to enable it (which is what users will look for). I know the
  toolchain provides it, and I assume it is enabled if USE="hardened" is
  set and the correct profile is used.
- Your risk tables do not refer to the method or source used to generate
  the risk numbers. I'm pretty sure you know what you're talking about,
  but it might be interesting to tell the users how you came to the
  numbers, or use online resources to back up the figures

Generally, I get the feeling the document is more an article (one-time
useful read) rather than a to-be-maintained document. It's a good read
to refer people to when they ask what Gentoo Hardened actually does, but
misses some user-related content which might steer away a large number
of interested users.

Wkr,
	Sven Vermeulen