[gentoo-hardened] RFC doc on hardened.

[gentoo-hardened] RFC doc on hardened.

[klondike]

[-- Attachment #1.1: Type: text/plain, Size: 612 bytes --]

 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).

If there is no major complaint, these texts will be the ones used on the
GuideXML docs (+ some examples that I'll try to write).

klondike

[-- Attachment #1.2: GentooHardenedWhy.odt --]
[-- Type: application/vnd.oasis.opendocument.text, Size: 26596 bytes --]

[-- Attachment #1.3: GentooHardenedWhy.pdf --]
[-- Type: application/pdf, Size: 161744 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 262 bytes --]

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

[Sven Vermeulen]

[-- Attachment #1: Type: text/plain, Size: 5150 bytes --]

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

[-- Attachment #2: Type: application/pgp-signature, Size: 198 bytes --]

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

[klondike]

[-- Attachment #1: Type: text/plain, Size: 6283 bytes --]

 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.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 262 bytes --]