1 |
On Fri, Sep 24, 2010 at 01:37:54AM +0200, klondike wrote: |
2 |
> Well as some of you may remember by June I wrote a document on why |
3 |
> using gentoo hardened is a good idea explaining some common attacks and |
4 |
> what were the grsecurity, PAX and hardened features to avoid them. |
5 |
> |
6 |
> I have reread the doc and expanded some parts as work previous to |
7 |
> formatting it as GuideXML and publishing it on the hardened site |
8 |
> (probably split in various docs). |
9 |
> |
10 |
> Again I'd like to know your opinions on what should be fixed (if |
11 |
> anything should). |
12 |
|
13 |
Hi, |
14 |
|
15 |
First a few general remarks, not related to the documentation you've |
16 |
written. Please, don't hesitate to comment on anything I write, and |
17 |
don't treat what I write as the absolute truth (I hope it is, but I'm |
18 |
still only human). Also treat it as constructive criticism. |
19 |
|
20 |
Oh, and take your time to read it, I don't expect answers within |
21 |
minutes ;-) |
22 |
|
23 |
When we need to write documentation, we should take special care that |
24 |
the documentation we write is easily maintainable. If there are only a |
25 |
handful of developers available to maintain the documentation, don't try |
26 |
to duplicate much of the documentation provided by the projects |
27 |
themselves (PaX, SELinux, ...) but rather refer to those documents |
28 |
instead. |
29 |
|
30 |
The main reason is that people tend to ignore documentation if they find |
31 |
something outdated inside it. We don't want people to ignore our |
32 |
documents because a paragraph on grSecurity is outdated, even though all |
33 |
Gentoo-related commands (and other info) is still very much valid. You |
34 |
can easily persuade yourself of this fact if you imagine you're reading |
35 |
a document on SELinux and it talks about the reference policy, version 1 |
36 |
(rather than 2). I personally tend to skip the document and search for a |
37 |
more recent one then, even though the document itself may still be 100% |
38 |
valid. |
39 |
|
40 |
Because of the maintenance issues we might face, I would suggest a |
41 |
documentation approach using stages. |
42 |
|
43 |
First, write up quick reference(s) on how to deal with the various |
44 |
security projects on Gentoo Hardened. Treat the references as if they |
45 |
are meant for knowledgeable people (who know how to search for |
46 |
information) and try sticking with the Gentoo Hardened related |
47 |
activities & commands. Yes, it's fine to document commands that are not |
48 |
Gentoo Hardened specific, as long as the commands (and other reference |
49 |
material) is going to be used by developers and users. |
50 |
|
51 |
Second (after the quick references), write developer documentation. A |
52 |
project is only as active as its developers are, so good developer |
53 |
documentation is a must. Developer documentation has the advantage that |
54 |
you can assume certain knowledge from the reader, and you don't need to |
55 |
write it in perfect phrazes. As long as it is understandable (for |
56 |
non-native English speakers) it's fine. |
57 |
|
58 |
Only when such documentation is over can we think about user |
59 |
documentation. User documentation should be focusing on the end goal of |
60 |
the project (or subprojects). Don't try to duplicate documentation if |
61 |
the master project (SELinux, grSecurity, ...) offers great |
62 |
documentation; however, you don't want to refer to documentation of |
63 |
different distributions (not only for PR reasons, but also because those |
64 |
documents most often include the policies and principles of those |
65 |
distributions which may not be up to par with Gentoo Hardened's). |
66 |
|
67 |
Okay, with that said - good thing it's written, I would hate to repeat |
68 |
all that verbally ;-) - some feedback on the "GentooHardenedWhy" |
69 |
document... |
70 |
|
71 |
- You're starting with the assumption that the reader has knowledge |
72 |
about how process memory works. Later on, you explain it a bit more |
73 |
but you still use many terms that will be unknown to non-programmers |
74 |
(and especially 'standard' system administrators). That's okay, but |
75 |
you might want to inform the user about prerequired knowledge before |
76 |
diving into the topic. |
77 |
- I had troubles interpreting the tables that represent the stacks |
78 |
first: I didn't really interprete the first headings as being headings |
79 |
but rather data (which is really confusing). Also, if one doesn't |
80 |
really understand how stacks are used (and how they grow) it might be |
81 |
difficult to understand how you come from the "before" to the "after" |
82 |
state. |
83 |
- Of all the protections that Gentoo Hardened provides, I fail to find |
84 |
how to enable it (which is what users will look for). I know the |
85 |
toolchain provides it, and I assume it is enabled if USE="hardened" is |
86 |
set and the correct profile is used. |
87 |
- Your risk tables do not refer to the method or source used to generate |
88 |
the risk numbers. I'm pretty sure you know what you're talking about, |
89 |
but it might be interesting to tell the users how you came to the |
90 |
numbers, or use online resources to back up the figures |
91 |
|
92 |
Generally, I get the feeling the document is more an article (one-time |
93 |
useful read) rather than a to-be-maintained document. It's a good read |
94 |
to refer people to when they ask what Gentoo Hardened actually does, but |
95 |
misses some user-related content which might steer away a large number |
96 |
of interested users. |
97 |
|
98 |
Wkr, |
99 |
Sven Vermeulen |