MozDef/examples/alerts/AlertDevelopment.ipynb

{
 "metadata": {
  "name": ""
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "#Step one: \n",
      "#Copy the 'lib' directory from the alerts directory in the mozdef github repo into the directory with this\n",
      "#ipython notebook file.\n",
      "#The directory structure should look like: \n",
      "# .\n",
      "# ..\n",
      "# lib/\n",
      "# lib/__init__.py\n",
      "# lib/alerttask.py\n",
      "# lib/config.py"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 1
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "#Step Two: \n",
      "#Edit the lib/config.py file \n",
      "#\n",
      "#In particular: \n",
      "# Make sure ALERTS={}\n",
      "# to avoid sending off celery jobs by accident\n",
      "\n",
      "# Edit the ES={'servers'} to match your destination elastic search server/cluster\n",
      "\n",
      "# Change the timezone to match if needed:\n",
      "# OPTIONS = {\n",
      "#    'defaulttimezone': 'UTC',\n",
      "# }"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 2
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "#Step Three: \n",
      "#Iterate your alerts to search for the right events\n",
      "#aggregate on the right 'details' field\n",
      "#and output the right alert text"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 3
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "#import the alerts library for mozdef\n",
      "#inheriting the configuration from config.py\n",
      "#You may receive errors about being unable to connect to celery/kombu\n",
      "#which you can safely ignore\n",
      "from lib.alerttask import AlertTask\n",
      "import pyes"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stderr",
       "text": [
        "ERROR:lib.alerttask.AlertTask:Exception while configuring kombu for alerts: [Errno 61] Connection refused\n"
       ]
      },
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "{}\n",
        "[]\n"
       ]
      }
     ],
     "prompt_number": 4
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "#setup a base class to begin prototyping our alert\n",
      "#that does nothing but connect to ElasticSearch\n",
      "class AlertTest(AlertTask):\n",
      "    def main(self):\n",
      "        self.log.debug('running main')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stderr",
       "text": [
        "ERROR Exception while configuring kombu for alerts: [Errno 61] Connection refused\n"
       ]
      },
      {
       "output_type": "stream",
       "stream": "stderr",
       "text": [
        "ERROR:lib.alerttask.AlertTest:Exception while configuring kombu for alerts: [Errno 61] Connection refused\n"
       ]
      }
     ],
     "prompt_number": 5
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "#instanciate our alert class\n",
      "testAlert=AlertTest()\n",
      "#set the logging level\n",
      "testAlert.log.setLevel('INFO')\n",
      "#setup a query\n",
      "#with a time period (X minutes ago)\n",
      "#and a term search\n",
      "#and a search for a field that must exist\n",
      "testAlert.filtersManual(dict(minutes=60),\n",
      "                        must=[pyes.TermFilter('summary', 'sometext'),\n",
      "                              pyes.ExistsFilter('details.somefield')])\n",
      "#search for events\n",
      "testAlert.searchEventsSimple()"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stderr",
       "text": [
        "ERROR Exception while configuring kombu for alerts: [Errno 61] Connection refused\n"
       ]
      },
      {
       "output_type": "stream",
       "stream": "stderr",
       "text": [
        "ERROR:lib.alerttask.AlertTest:Exception while configuring kombu for alerts: [Errno 61] Connection refused\n"
       ]
      }
     ],
     "prompt_number": 6
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "#sample the events that matched the search\n",
      "testAlert.events[0:2]"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 7,
       "text": [
        "[]"
       ]
      }
     ],
     "prompt_number": 7
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# aggregate on a field in the 'details' section of the json: \n",
      "testAlert.searchEventsAggreg('http_user_agent')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 8
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "#sample the aggregations\n",
      "testAlert.aggregations[0:2]"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 9,
       "text": [
        "[]"
       ]
      }
     ],
     "prompt_number": 9
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "#create a test alert\n",
      "#using the aggregation and events\n",
      "testAlert.createAlertDict('alert summary goes here','aggregatedAlert','alert',testAlert.events[0:2])"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "metadata": {},
       "output_type": "pyout",
       "prompt_number": 10,
       "text": [
        "{'category': 'aggregatedAlert',\n",
        " 'events': [],\n",
        " 'severity': 'NOTICE',\n",
        " 'summary': 'alert summary goes here',\n",
        " 'tags': 'alert',\n",
        " 'utctimestamp': '2014-12-12T23:19:13.029914+00:00'}"
       ]
      }
     ],
     "prompt_number": 10
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "#If the events, aggregations and resulting alert are satisfactory\n",
      "#make a myalertname.py file using some of the github files as a reference that includes your \n",
      "#'filtersManual', and aggregation choices\n",
      "# and add the .py file to the config.py ALERTS={} section: \n",
      "#ALERTS = {\n",
      "#    'pyfilename.py.classname': crontab(minute='*/1')\n",
      "# }"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    }
   ],
   "metadata": {}
  }
 ]
}