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.

IMPORTANT: As of October 2011, the CVE data in data/ and the bin/update and
bin/check-todo-issues utilities are deprecated. They have been replaced by
functionality in GLSAMaker 2.

[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 and code copy list)
* lib   -> support libraries for the tools in bin


====== 2b. Dependencies for the scripts =======================================

For ./bin/update:
  * dev-perl/XML-Simple

For ./bin/check-todo-issues:
  * app-portage/eix
  * www-client/pybugz (optional)


====== 3. Workflow ============================================================

The master database lies in data/CVE/list. Its format is
explained in data/README.

====== 3.1 Updating ===========================================================

Make sure to run ./bin/update -f before using the other tools for the first
time, to populate the cache directory.

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

Please separate update (sync) commits from manual changes.


====== 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]
 	RESERVED
+	BUG: 194278



====== 4. TODOs ===============================================================

* Give everyone logins.
* Extend docs.
* Create a commit list for review.