Re: [gentoo-hardened] RFC doc on hardened.

[klondike]

El 27/09/10 20:58, Sven Vermeulen escribió:
>
> 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.
Looks reasonable, the actual idea is splitting the document so it can
replace older grsec / pax guides.
> 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.
No problem with this, though that'd take some time, I usually wrote docs
either by request or because I find something undocumented, I'd like to
know what people misses to write it :/
> 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.
I can help developers with this, but I can't write this kinds of things
because I can't go into the minds of the developers, and I think is
faster and more efficient if they try to say what they are doing rather
than reverse engineering everything. (Needless to say I don't mind
correct, add references and the likes once I have something to start with).
> 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).
Sometimes other distros documents is all the sources we have to say what
things does :(
> 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.
Good idea, I'll do that. Anyway, aside from the attacks section, where
are the odd words?
Obviously to know how things like stack overflows work you must be a
programmer or have some programming knowledge (at least until I have
time to write a more real life like example).
> - 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.
Okay, I'll try to explain that.
> - 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.
True, the original intention of the document was that it was meant for
people who didn't know of hardened, something like a commercial
brochure, though it growed a lot.
> - 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
Mainly it comes from my own experience trying to exploit said
vulnerabilities by my self. Anyway I should do a more serious analysis.
> 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.
>
Originally that was the idea, but I want to split it in smaller
documents. I suppose that adding the "How to enable it" would be a great
idea.