		   LHEx Requirements Specification
		   ===============================

			     Andrew Snare
			  13th January, 1999
			     Revision 0.1

Introduction
============

One of the tasks associated with administering and running an IRC
server is enforcing server policy and preventing the various forms of
IRC-based abuse. As part of this, events often occur (such as a warbot
being found) that require action to be taken to prevent similar events 
from occurring again in the future. At its most simplest, the action
usually involves a ban being placed against a certain hostmask.

While this is usually adequate, over time the number of bans in place
can become quite large. In addition, the duration of a ban should
usually vary depending on the severity of the original offence and the 
number of people affected by it.

Unfortunately, the way most bans are put in place is too inflexible to
allow for satisfactory reviewing and expiry of bans as appropriate. In 
addition, the bans are typically placed only on a single IRC server
with the result that the offending user(s) can simply switch to
another server and cause more problems.

The purpose of the LHEx software is to provide a mechanism through
which incidents can be reported and appropriate meta-information
stored. The meta-information to be provided should be enough to allow
for appropriate reviewing and expiry of bans as appropriate. A
secondary (future) aim of the software is to allow for distribution of
the intact meta-information to other IRC servers in an automated
manner.

The purpose of this document is to specify the design of the software
being designed to aid in the administration of IRC servers through the
management of incident reports. Broadly speaking, the software is
initially being designed for a typical IRC server and the management
of its K-Lines, but it is anticipated that eventually distributed
functionality will be developed.

Glossary
========

Throughout this document, the following terms have the given
meanings. Hopefully this is enough to prevent ambiguous use of the
terms throughout this document.

    Admin: The superuser of the software, responsible for system
        configuration as well as creation of users, etc. Traditionally
        this person might correspond to the person deemed the "IRC
	Admin."

    Hostmask: A glob that represents a hostname or IP address.
        eg, *.ozemail.com.au or 203.2.194.*

    Incident: An incident refers to an event that prompts an Operator
        or Administrator to file a report in LHEx.

    K-Line: A term traditionally referring to an entry in the
        configuration file that bans a certain usermask.

    LHEx: The software package being developed, as a whole.

    User: A user of the software, with the ability to create new
        incident reports and edit existing ones. Traditionally this
	role might correspond to that of a person deemed an "IRC
	Operator."

    Usermask: Like a hostmask, but with a user component as well.
        eg, *meow@*.ozemail.com.au -- as with hostmasks, globs are
        allowed.

Functional Requirements
=======================

User Functionality
------------------

The software should allow the user to:

    Report Incident: The software shall allow the user to create an
	incident report and record all appropriate meta-information.

    Edit Incidents: The software shall allow the user to change the
        meta-information associated with an incident report they
	"own".

    Review Incidents: The software shall allow the user to review
        incidents that are outstanding.

    Search Incidents: The software shall allow the user to search for
        incidents matching the given criteria.

    Change Password: The software shall allow the user to change their
        own password, used for authentication purposes.

Reporting Incidents :-

The software shall allow users known to the system to report new
incidents and enter the appropriate meta-information. Included in this 
meta-information will be information about how often the incident
should be reviewed by the owner.

The user who enters the report shall be deemed the "owner" of the
incident report. However, the user shall be able to give the report
away to other users. In addition the user should be able to denote
whether other users are able to edit the incident report.

Edit Incident :-

The software shall allow users known to the system to edit the
meta-information associated with existing reports that they own, or
add new information to reports owned by others if they allow.

Review Incidents :-

The software shall allow users to view a list of their own incidents
that are due for review. In addition, the software shall allow
outstanding incidents to be reviewed by other users.

Search Incidents :-

The software shall allow users to search for incidents both owned by
themselves and others. The user shall be able to configure how many
results are displayed at once.

Change Password :-

Users shall be able to change the password they use to authenticate
themselves with the system. Appropriate restrictions shall be placed
on the choice of password possible.

Admin Functionality
-------------------

The software shall allow the administrator to:

    Create Users: The software shall allow the admin to create new
        users.

    Edit Users: The software shall allow the admin to change the
        details associated with any user of the system.

    Configure LHEx: The software shall allow the admin to configure
        various aspects of the software dynamically at runtime.

In addition to these functions, the admin shall be able to do anything 
a user can, as if they were that user.

Non-Functional Requirements
===========================

The software shall be designed using a client-server model, with the
client being a standard web browser. Where possible, the output from
the web-browser shall conform to the HTML4 standard with
"transitional" extensions only used when unavoidable.

The server software shall be based upon the Zope system
(http://www.zope.org/) and implemented in python. Some components of
the system may optionally have drop-in replacements that can be
compiled for performance reasons. Due to the way Zope works, the
software shall be able to run standalone or as a standard CGI program
sitting behind another web server.
