initial docs

LICENSE.txt

@@ -0,0 +1,32 @@
+Copyright (c) 2014 University of Illinois/NCSA
+All rights reserved.
+
+Developed by:   NCSA Cyber Security
+                NCSA
+                www.ncsa.illinois.edu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal with
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimers.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimers in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the names of <Name of Development Group, Name of Institution>, nor
+  the names of its contributors may be used to endorse or promote products
+  derived from this Software without specific prior written permission. 
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE
+SOFTWARE. 

README.md

@@ -0,0 +1,64 @@
+BHR Site
+========
+
+This is the BHR site / API endpoint.
+
+It does not make any policy decisions except for the block duration auto scaling.
+
+It basically acts as a message queue between bhr clients adding blocks, and bhr
+clients implementing blocks.
+
+Blocks flow through the system like so:
+
+* A BHR Client calls block(cidr='192.168.254.254', source='readme', why='because!', duration=300)
+* This entry is now in the system but not marked as blocked.
+* A BHR Client calls `get_block_queue()` which will return a list containing that record
+* That BHR Client will then add a firewall rule, bgp entry, whatever
+* That BHR Client calls `set_blocked` and marks it as blocked
+
+300 seconds pass
+
+* A BHR client calls `get_unblock_queue` which returns a list containing that record
+* That BHR client will remove the firewall rule, bgp entry, whatever
+* That BHR client calls `set_unblocked` and marks it as unblocked
+
+Bhr clients have an 'ident' associated with them, and blocks/unblocks are
+tracked per ident.  This enables a single BHR system to be used to apply blocks
+across multiple backend systems.
+
+Configuration
+=============
+
+Create `bhr_site/settings_local.py` with something like:
+
+    DEBUG = False
+    ALLOWED_HOSTS = ['bhr.example.com', 'bhr']
+
+    STATIC_ROOT="/home/bhr/static"
+
+    ADMINS = (("You", "root@localhost"), )
+
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.db.backends.postgresql_psycopg2',
+            'NAME': 'bhr',
+        }
+    }
+
+    BHR = {
+        'time_multiplier':              2.0,
+        'time_window_factor':           2.0,
+        'minimum_time_window':          43200.0,
+        'penalty_time_multiplier':      2.0,
+        'return_to_base_multiplier':    2.0,
+        'return_to_base_factor':        2.0,
+    }
+
+And configure apache similar to examples/apache.conf
+
+Related projects
+================
+
+* [bhr-client](https://github.com/JustinAzoff/bhr-client) - BHR python client
+* [bhr-client-exabgp](https://github.com/JustinAzoff/bhr-client-exabgp) - ExaBGP block manager
+* [bhr-bro](https://github.com/JustinAzoff/bhr-bro) - Basic Bro integration for BHR

examples/apache.conf

@@ -0,0 +1,63 @@
+<VirtualHost *:80>
+  ServerName bhr.example.com
+
+  ## Vhost docroot
+  DocumentRoot /home/bhr/static
+
+  <Directory /home/bhr/static>
+    Options Indexes FollowSymLinks MultiViews
+    AllowOverride None
+    Order allow,deny
+    Allow from all
+  </Directory>
+
+  ## Load additional static includes
+
+  ## Logging
+  ErrorLog /var/log/apache2/bhr_error.log
+  ServerSignature Off
+  CustomLog /var/log/apache2/bhr_access.log combined
+
+  ## Redirect rules
+  Redirect permanent / https://bhr.example.com/
+</VirtualHost>
+
+<VirtualHost *:443>
+  ServerName bhr.example.com
+
+  ## Vhost docroot
+  DocumentRoot /home/bhr/static
+  ## Alias declarations for resources outside the DocumentRoot
+  Alias /static /home/bhr/static
+  Alias /robots.txt /home/bhr/static/robots.txt
+  Alias /favicon.ico /home/bhr/static/favicon.ico
+
+  <Directory /home/bhr/static>
+    Options Indexes FollowSymLinks MultiViews
+    AllowOverride None
+    Order allow,deny
+    Allow from all
+  </Directory>
+
+  ## Load additional static includes
+
+
+  ## Logging
+  ErrorLog /var/log/apache2/bhr_error.log
+  ServerSignature Off
+  CustomLog /var/log/apache2/bhr_access.log combined
+
+  ## SSL directives
+  SSLEngine on
+  SSLCertificateFile      /home/bhr/ssl/bhr.crt
+  SSLCertificateKeyFile   /home/bhr/ssl/bhr.key
+  SSLCACertificatePath    /etc/ssl/certs
+
+  #python
+  WSGIDaemonProcess bhr display-name=%{GROUP} group=bhr maximum-requests=1000 processes=2 python-path=/home/bhr/bhr_project:/home/bhr/bhr_env/lib/python2.7/site-packages threads=8 user=bhr
+  WSGIProcessGroup bhr
+  WSGIScriptAlias / /home/bhr/bhr_project/bhr_site/wsgi.py
+  ## Custom fragment
+  WSGIPassAuthorization On
+
+</VirtualHost>