Permalink
Browse files

initial public release

  • Loading branch information...
chair6 committed Aug 6, 2012
1 parent 536954d commit b0bb1ad9f2f3d39dd9c56779cbd5092bc120367a
View
@@ -0,0 +1,8 @@
+*.pyc
+*.class
+*.db
+*.xlsx
+.DS_Store
+*.bak
+
+burpsuite_*.jar
View
@@ -0,0 +1,15 @@
+Credits
+=======
+
+* Hiccup wouldn't exist, and application security testing would be significantly less pleasant, if it wasn't for Burp Suite (http://portswigger.net) by Dafydd Stuttard.
+
+* Based on initial work by David Robert (http://blog.ombrepixel.com/post/2010/08/30/Extending-Burp-Suite-in-Python).
+
+* Uses Jython (http://jython.org) 2.5.3b with additional libraries:
+ - OpenPyXL (http://packages.python.org/openpyxl/)
+ - PyYaml (http://pyyaml.org/)
+ - json.py (http://sourceforge.net/projects/json-py/)
+ - PyAMF (http://www.pyamf.org/)
+
+* Includes SQLiteJDBC (http://www.zentus.com/sqlitejdbc/).
+
View
@@ -0,0 +1,20 @@
+Copyright (c) 2012 Zynga Inc. http://zynga.com/
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in 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:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+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 AUTHORS 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 IN THE SOFTWARE.
View
@@ -1,4 +1,97 @@
-hiccup
-======
+Hiccup - Burp Suite Python Extensions
+=====================================
-Hiccup is a framework that allows the Burp Suite (a web application security testing tool, http://portswigger.net/burp/) to be extended and customized, through the interface provided by Burp Extender (http://portswigger.net/burp/extender/). Its aim is to allow for the development and integration of custom testing functionality into the Burp tool using Python request/response handler plugins.
+Hiccup is a framework that allows the Burp Suite (a web application security testing tool, [http://portswigger.net/burp/](http://portswigger.net/burp/)) to be extended and customized, through the interface provided by Burp Extender ([http://portswigger.net/burp/extender/](http://portswigger.net/burp/extender/)). Its aim is to allow for the development and integration of custom testing functionality into the Burp tool using Python request/response handler plugins.
+
+
+Installing and Using Hiccup
+---------------------------
+
+1. Clone/unzip this repository/file into its own directory, retaining the existing subdirectory structure.
+2. Copy a Burp Suite JAR file (free or professional, see [http://portswigger.net/burp/download.html](http://portswigger.net/burp/download.html)) into this same directory.
+3. Review the hiccup.yaml configuration file and make any immediate changes that might be necessary.
+4. From a shell or window, run the hiccup.sh (Mac OS X or Linux) or hiccup.bat (Windows) file, and start using Burp. Watch the terminal/DOS window for confirmation that Hiccup has initialized and for output from the plugins.
+5. Use web browser and Burp as usual. Hiccup plugin output will appear in the terminal/DOS window.
+6. Move plugins in and out of the plugins/ directory to enable or disable them (plugins located in the plugins/disabled/ directory, or other sub-directories, will not be loaded). Modify, or create new plugins as necessary. Movements and edits to plugins are detected and reloaded automatically.
+
+
+Extensions Framework
+--------------------
+
+The framework is made up of components as follow:
+
+* hiccup/hiccup.yaml
+
+ Base configuration file for the Hiccup framework. The YAML file contains global settings along with plugin-specific configuration items, and is easily extended with new sections added as required for additional plugins. Hiccup will detect any changes to the configuration file during runtime and reload as required.
+
+* hiccup/BurpExtender.py
+
+ Main interface from Hiccup to Burp Extender. Defines the processProxyMessage and processHttpMessage functions, which create the Message object with the request/response data and passes it to the PluginManager for handling. It also registers the Burp Extender callbacks object (through the registerExtenderCallbacks function) which exposes all IBurpExtenderCallbacks functions ([http://portswigger.net/burp/extender/burp/IBurpExtenderCallbacks.html](http://portswigger.net/burp/extender/burp/IBurpExtenderCallbacks.html)), and initializes GlobalConfig and PluginManager at load time.
+
+* hiccup/MenuItemHandler.py
+
+ Secondary interface from Hiccup to Burp Extender. Defines the menuItemClicked function, which creates an array of Message objects with associated request/response data and passes it to the PluginManager for handling.
+
+* hiccup/Message.py
+
+ The object that stores various data associated with the request/response being processed. Data values stored include ref, method, url, headers (raw and parsed), body, contenttype, resourcetype, statuscode, remotehost, and remoteport. Various helper methods are provided to aid in ease of plugin development, and additional helper methods can be added to the base object as necessary.
+
+ Plugins make their changes directly to this object as processing occurs.
+
+* hiccup/PluginManager.py
+
+ Locates, loads, reloads, and unloads plugins according to file existence/changes as monitored by FileWatcher. Pushes messages from Burp Extender through to individual plugins.
+
+ See plugins/README.md for detailed documentation.
+
+* hiccup/FileWatcher.py
+
+ Generic file change tracker, used by various Hiccup elements to detect changes to files.
+
+* hiccup/GlobalConfig.py
+
+ Defines configuration options and state-related objects that are used globally by Hiccup. A GlobalConfig object is initialized when Hiccup is first loaded, and is passed to each plugin for reference as appropriate.
+
+ Configuration is read in from the YAML configuration file, hiccup.yaml.
+
+* hiccup/SharedFunctions.py
+
+ Stores generic shared functions.
+
+* hiccup/BasePlugin.py
+
+ The base class from which plugins should be defined as subclasses.
+
+* plugins/
+
+ Holds Python request/response handler plugins.
+
+ The plugins directory will be automatically monitored by the PluginManager, which will load, unload, and reload plugins automatically (as they are moved into or out of the directory, or as changed are detected to individual plugin files).
+
+ See plugins/README.md for detailed documentation.
+
+* plugins/disabled/
+
+ Plugins that should not be loaded by PluginManager are stored in this directory (or other sub-directories that are created).
+
+
+Plugins
+-------
+
+See plugins/README.md.
+
+
+Authors
+=======
+Hiccup was developed by Jamie Finnigan (http://twitter.com/chair6), based on initial work by David Robert (http://blog.ombrepixel.com/post/2010/08/30/Extending-Burp-Suite-in-Python), and is continued as an official Zynga OpenSource (http://code.zynga.com/) project.
+
+
+License
+=======
+Copyright (c) 2012 Zynga Inc. http://zynga.com/
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in 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:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+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 AUTHORS 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 IN THE SOFTWARE.
View
@@ -0,0 +1,49 @@
+@echo off
+
+set COUNT=0
+
+set STARTDIR=%CD%\
+set BATDIR=%~dp0
+cd /D %BATDIR%
+
+for /f "tokens=*" %%a in (
+'forfiles /P %BATDIR% /M burpsuite_*.jar /C "cmd /c echo @fname" ^| find /C "burpsuite"'
+) do (
+set COUNT=%%a
+)
+
+
+if %COUNT%==1 goto ONE
+if %COUNT% gtr 1 goto MANY
+goto NONE
+
+:ONE
+for %%X in (burpsuite_*.jar) do set BURP_PACKAGE=%%X
+goto EXECBURP
+
+:MANY
+for %%X in (burpsuite_*.jar) do (
+ choice /C:ny /M "Found %COUNT% Burp packages; use %%X"
+ if ERRORLEVEL 2 (
+ set BURP_PACKAGE=%%X
+ goto EXECBURP
+ )
+)
+goto NONE
+
+
+:NONE
+echo ERROR: A necessary Burp Suite package could not be located, or was not selected; download from http://portswigger.net/burp/download.html, or view README file for more instructions.
+cd /D %STARTDIR%
+pause
+goto EOF
+
+:EXECBURP
+echo Initializing Burp with package %BURP_PACKAGE%...
+java -Xmx1024m -classpath %BURP_PACKAGE%;lib\BurpExtender.jar;lib\sqlitejdbc-v056.jar -Dpython.path=%CD%;%CD%\lib;%CD%\hiccup;%CD%\plugins burp.StartBurp
+goto EOF
+
+
+:EOF
+cd %STARTDIR%
+exit /B
View
@@ -0,0 +1,28 @@
+#!/bin/sh
+
+BURP_PACKAGE="";
+
+BURP_COUNT=`ls burpsuite_*.jar | wc -l`;
+
+if [ $BURP_COUNT = 1 ]; then
+ BURP_PACKAGE=`ls burpsuite_*.jar`;
+else
+ for i in ls burpsuite_*.jar; do
+ if [ -e ${i} ]; then
+ echo "Found ${BURP_COUNT#"${BURP_COUNT%%[![:space:]]*}"} Burp packages; use ${i}? (y/n): \c"
+ read answer
+ case ${answer} in
+ y*|Y*) BURP_PACKAGE=${i}; break; ;;
+ n*|N*) ;;
+ *) : ;;
+ esac
+ fi
+ done
+fi
+
+if [ "x$BURP_PACKAGE" == "x" ]; then
+ echo "ERROR: A necessary Burp Suite package could not be located, or was not selected; view README file, or download from http://portswigger.net/burp/download.html.";
+ exit 1;
+fi
+
+java -Xmx1024m -classpath $BURP_PACKAGE:lib/BurpExtender.jar:lib/sqlitejdbc-v056.jar -Dpython.path=$PWD:$PWD/lib:$PWD/hiccup:$PWD/plugins burp.StartBurp
View
@@ -0,0 +1,40 @@
+####################
+defaults:
+ default_plugin_scope: proxy_only #all, proxy_only, or http_only
+ intercept_enabled: False #automatically enable/disable intercepts on load - True or False
+ log_format: '[%(module)s] %(message)s'
+ log_level: info #info or debug
+ plugin_directory: plugins
+ auto_delete_class_files: True #True or False - autodelete stale class files for disabled plugins
+ default_intercept_action: FOLLOW_RULES
+ #burp_scope_include: ['http://www.google.com',] #must be at least valid scheme://host URL
+ #burp_scope_exclude: ['http://www.microsoft.com',]
+internals: [] # reserved for internal Hiccup use
+state: [] # reserved for internal Hiccup use
+callbacks: [] # reserved for internal Hiccup use
+####################
+ConditionalIntercepts:
+ body_contains: ['internal only']
+ header_exists: [x-hacker] #triggered by wordpress.com
+ headers_contain: ['DROP TABLE '] #triggered by reddit.com
+ host_contains: [google.com]
+ url_contains: [admin]
+ContentReplace:
+ targets:
+ - [' the ', ' FOO ']
+ - [' and ', ' MEH ']
+CookieProfiler:
+ output_file: cookie-summary.xlsx
+ write_after: 20
+DatabaseLogger:
+ storable_types: [ 'text/','application/json', 'application/javascript', 'application/x-javascript', 'application/ecmascript', 'application/x-www-form-urlencoded' ]
+ output_file: logger.db
+DropMatches:
+ domains: [domaintodrop.com, otherdomaintodrop.com]
+ hosts: [specific.hostname.com, specific2.hostname.com]
+HeaderReplace:
+ targets:
+ - ['Firefox', 'FireDUCK']
+JsonManipulation:
+ delete_keys: [about] #test against jsonip.com
+ set_values: {ip: foo, nokey: noworries } #test against jsonip.com
View
@@ -0,0 +1,51 @@
+# Hiccup - Burp Suite Python Extensions
+# Copyright 2012 Zynga Inc.
+
+import SharedFunctions as shared
+import logging
+
+class BasePlugin:
+
+ required_config = []
+ config_complete = False
+ plugin_name = None
+ logger = None
+ plugin_scope = None
+
+ plugin_scopes = {
+ 'all': 0,
+ 'proxy_only': 1,
+ 'http_only': 2
+ }
+
+ def __init__(self, global_config, reqdconf=[], plugin_scope=None):
+ self.logger = logging.getLogger()
+ self.logger.debug("initializing '%s', required_config %s" % (self.__module__, reqdconf))
+ self.global_config = global_config
+ self.plugin_name = self.__module__
+ if plugin_scope == None:
+ plugin_scope = global_config['defaults']['default_plugin_scope']
+ self.logger.debug("plugin did not provide scope, using default: %s" % plugin_scope)
+ elif plugin_scope not in self.plugin_scopes:
+ self.logger.error("plugin provided invalid scope '%s', using default '%s'" % (plugin_scope, global_config['defaults']['default_plugin_scope']))
+ plugin_scope = global_config['defaults']['default_plugin_scope']
+ self.plugin_scope = plugin_scope
+ self.required_config = reqdconf
+ if self.global_config.test_plugin_config(self.plugin_name, reqdconf):
+ self.config_complete = True
+ self.logger.debug("'%s' plugin initialized" % (self.__module__))
+
+ def __del__(self):
+ pass
+
+ def required_config_loaded(self):
+ return self.config_complete
+
+ def scope_proxy_only(self):
+ return self.plugin_scopes[self.plugin_scope] == self.plugin_scopes['proxy_only']
+
+ def scope_http_only(self):
+ return self.plugin_scopes[self.plugin_scope] == self.plugin_scopes['http_only']
+
+ def scope_all(self):
+ return self.plugin_scopes[self.plugin_scope] == self.plugin_scopes['all']
Oops, something went wrong.

0 comments on commit b0bb1ad

Please sign in to comment.