Update docs

svn path=/; revision=9

1 files changed, 97 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..d4d2c0d
--- /dev/null
+++ b/README
@@ -0,0 +1,97 @@
+This overlays contains scripts and data that support Developers and Padawans
+of the Gentoo Security project [1] with their work. It does not currently
+contain any ebuilds.
+
+[1] http://www.gentoo.org/proj/en/security/
+
+
+====== 1. Goals ===============================================================
+
+* Minimize work Gentoo Security puts into assessing which
+  vulnerabilities in the CVE database affect us.
+* Document those assessments even if an issue does not
+  affect us (avoids duplicate bugs and duplicate work).
+* Don't miss any issues.
+
+
+====== 2. Contents of the directory ===========================================
+
+* bin   -> scripts to work on the data
+* cache -> place for files not for inclusion in the SVN
+* data  -> plain text data (currently CVE list)
+* lib   -> support libraries for the tools in bin
+
+
+====== 3. Workflow ============================================================
+
+The master database lies in data/CVE/list. Its format is
+explained in data/README.
+
+====== 3.1 Updating ===========================================================
+
+The text database is updated against the MITRE CVE database and
+the more often updated NVD CVE database everytime ./bin/update is run.
+
+This update-script also refreshes the local cache of the NVD, so
+it should be run before working with the other tools.
+
+Every new entry is marked with "TODO: check" and a diff is displayed. Example:
+
+CVE-2007-5091 (Multiple cross-site scripting (XSS) vulnerabilities in ...)
+	TODO: check
+
+
+====== 3.2 Working on TODOs ===================================================
+
+For working on TODOs, there's ./bin/check-todo-issues
+
+When you start it, it will read the text file and go through each open TODO,
+querying or guessing the program name of the CVE. It will display vulnerability
+information and the results of an `eix' search.
+
+After that, the issue should to be marked 'NOT-FOR-US: <program name>' if the
+program is not in our tree (by pressing .n). Example:
+
+CVE-2007-5138 (PHP remote file inclusion vulnerability in forum/forum.php ...)
+	NOT-FOR-US: lustig cms
+
+
+If the issue affects a program in our tree, a bug should be opened and the
+entry marked 'BUG: <bugnumber>' by pressing .e (Editor). If the issue does
+not affect any Gentoo system (it's old, or similar), you can add a
+'NOTE: <note>' saying so. You can add any number of 'BUG:' and 'NOTE:' lines.
+
+Examples:
+
+CVE-2007-5106 (Cross-site scripting (XSS) vulnerability in wp-register.php ...)
+	NOTE: WordPress 2.0 not in the tree anymore
+
+CVE-2007-4889 (The MySQL extension in PHP 5.2.4 and earlier allows remote ...)
+	BUG: 191034
+	NOTE: UNFIXED. This is a mySQL configuration issue
+
+Please read the '-h' output of check-todo-issues.
+
+====== 3.3 CVEs without entry =================================================
+
+In case a CVE name is public, but has no entry in our database (or is RESERVED)
+you can add an entry by hand (or remove the RESERVED), handling it like
+usual. To add a CVE description that does not get removed at the next update,
+put it in square brackets. The description will get updated once it's in the
+MITRE database.
+
+Example:
+
+-CVE-2007-4996
+-	RESERVED
++CVE-2007-4996 [Remote Denial of Service vulnerability in Pidgin < 2.2.1]
++	BUG: 194278
+
+
+
+====== 4. TODOs ===============================================================
+
+* Give everyone logins.
+* Extend check-todo-issues with possibility to file bugs.
+* Extend docs.
+* Create a commit list for review.