Moves installation/config instructions to README.

evennia/contrib/auditing/README.md

@@ -0,0 +1,67 @@
+# Input/Output Auditing
+
+Contrib - Johnny 2017
+
+This is a tap that optionally intercepts all data sent to/from clients and the 
+server and passes it to a callback of your choosing.
+
+It is intended for quality assurance, post-incident investigations and debugging 
+but obviously can be abused. All data is recorded in cleartext. Please 
+be ethical, and if you are unwilling to properly deal with the implications of 
+recording user passwords or private communications, please do not enable
+this module.
+
+Some checks have been implemented to protect the privacy of users.
+
+
+Files included in this module:
+
+    outputs.py - Example callback methods. This module ships with examples of
+            callbacks that send data as JSON to a file in your game/server/logs 
+            dir or to your native Linux syslog daemon. You can of course write 
+            your own to do other things like post them to Kafka topics.
+    
+    server.py - Extends the Evennia ServerSession object to pipe data to the
+            callback upon receipt.
+	
+	tests.py - Unit tests that check to make sure commands with sensitive
+	        arguments are having their PII scrubbed.
+	
+
+Installation/Configuration:
+
+Deployment is completed by configuring a few settings in server.conf. In short,
+you must tell Evennia to use this ServerSession instead of its own, specify
+which direction(s) you wish to record and where you want the data sent.
+
+    SERVER_SESSION_CLASS = 'evennia.contrib.auditing.server.AuditedServerSession'
+    
+    # Where to send logs? Define the path to a module containing your callback
+    # function. It should take a single dict argument as input.
+    AUDIT_CALLBACK = 'evennia.contrib.auditing.outputs.to_file'
+    
+    # Log user input? Be ethical about this; it will log all private and 
+    # public communications between players and/or admins.
+    AUDIT_IN = True/False
+    
+    # Log server output? This will result in logging of ALL system
+    # messages and ALL broadcasts to connected players, so on a busy game any
+    # broadcast to all users will yield a single event for every connected user!
+    AUDIT_OUT = True/False
+    
+    # The default output is a dict. Do you want to allow key:value pairs with
+    # null/blank values? If you're just writing to disk, disabling this saves 
+    # some disk space, but whether you *want* sparse values or not is more of a 
+    # consideration if you're shipping logs to a NoSQL/schemaless database.
+    AUDIT_ALLOW_SPARSE = True/False
+    
+    # If you write custom commands that handle sensitive data like passwords, 
+    # you must write a regular expression to remove that before writing to log.
+    # AUDIT_MASKS is a list of dictionaries that define the names of commands 
+    # and the regexes needed to scrub them.
+    #
+    # The sensitive data itself must be captured in a named group with a
+    # label of 'secret'.
+    AUDIT_MASKS = [
+        {'authentication': r"^@auth\s+(?P<secret>[\w]+)"},
+    ]

evennia/contrib/auditing/server.py

@@ -52,49 +52,7 @@ class AuditedServerSession(ServerSession):
     have their arguments masked by default, but you must mask or mask any
     custom commands of your own that handle sensitive information.
     
-    Installation:
+    See README.md for installation/configuration instructions.
-
-    Designate this class as the SERVER_SESSION_CLASS in `settings.py`, then set
-    some additional options concerning what to log and where to send it.
-    
-    settings.py:
-    SERVER_SESSION_CLASS = 'evennia.contrib.auditing.server.AuditedServerSession'
-    
-    # Where to send logs? Define the path to a module containing a function 
-    # called 'output()' you've written that accepts a dict object as its sole 
-    # argument. From that function you can store/forward the message received
-    # as you please. An example file-logger is below:
-    AUDIT_CALLBACK = 'evennia.contrib.auditing.outputs.to_file'
-    
-    # Log all user input? Be ethical about this; it will log all private and 
-    # public communications between players and/or admins.
-    AUDIT_IN = True/False
-    
-    # Log server output? This will result in logging of ALL system
-    # messages and ALL broadcasts to connected players, so on a busy MUD this 
-    # will be very voluminous!
-    AUDIT_OUT = True/False
-    
-    # The default output is a dict. Do you want to allow key:value pairs with
-    # null/blank values? If you're just writing to disk, disabling this saves 
-    # some disk space, but whether you *want* sparse values or not is more of a 
-    # consideration if you're shipping logs to a NoSQL/schemaless database.
-    AUDIT_ALLOW_SPARSE = True/False
-    
-    # Any custom regexes to detect and mask sensitive information, to be used
-    # to detect and mask any custom commands you may develop.
-    # Takes the form of a list of dictionaries, one k:v pair per dictionary
-    # where the key name is the canonical name of a command which gets displayed
-    # at the tail end of the message so you can tell which regex masked it--
-    # i.e. for a log entry with a typoed `connect` command:
-    # `conncect johnny *********** <Masked: connect>`
-    #
-    # The sensitive data itself must be captured in a named group with a
-    # label of 'secret'.
-    AUDIT_MASKS = [
-        {'authentication': r"^@auth\s+(?P<secret>[\w]+)"},
-    ]
-    
     """
     def audit(self, **kwargs):
         """