Merge pull request #5 from stavinski/master

Adding State Functionality

Author: Hannah-PortSwigger

BappDescription.html

@@ -1,13 +1,15 @@
-<p>This exension allows execution of custom Python scripts to be used with HTTP request and responses plus handling Macro messages.</p>
+<p>This extension allows execution of custom Python scripts to be used with HTTP request and responses plus support for handling Macro messages.</p>
 <p>To use, type or paste a Python script into the &quot;Python Scripts&quot; tab, and use Burp in 
-the normal way. The script will be executed for each HTTP request and response. 
-The following variables are defined in the context of the script:</p>
+the normal way. The script will be executed for each HTTP request and response.</p> 
+<p>Items placed into the 'state' dictionary will be persisted across request/responses.</p>
+<p>The following variables are defined in the context of the script:</p>
 <ul>
-	<li>extender</li>
-	<li>callbacks</li>
-	<li>helpers</li>
-	<li>toolFlag</li>
-	<li>messageIsRequest</li>
-	<li>messageInfo</li>
-	<li>macroItems</li>
+	<li>extender: IBurpExtender</li>
+	<li>callbacks: IBurpExtenderCallbacks</li>
+	<li>helpers: IExtensionHelpers</li>
+	<li>toolFlag: int</li>
+	<li>messageIsRequest: bool</li>
+	<li>messageInfo: IHttpRequestResponse</li>
+	<li>macroItems: IHttpRequestResponse[]</li>
+	<li>state: dict</li>
 </ul>

README.md

@@ -33,6 +33,27 @@ If there was a runtime exception these will also be captured in the `Errors` tex
 
 __Scripts are automatically restored and saved on extension load and unload.__ 
 
+## State Dictionary
+
+There are scenarios when values retrieved from previous requests or responses are required for the next request, this can sometimes be performed using Macros however if this behaviour is used for every endpoint this becomes unworkable as a solution. That is why the `state` dictionary was introduced so that it is possible to persist values that can be later retrieved in a subsequent request/response.
+
+An example of this could be an application that returns a unique token in the response and this must be provided into the next request, this could be handled using the following:
+
+~~~python
+if messageIsRequest:
+    if 'x-req' in state: # see if we have a token from prev resp
+        req = helpers.analyzeRequest(messageInfo)
+        headers = req.headers
+        headers.add('X-Request: {}'.format(state['x-req']))  # put the token into the req
+        body = messageInfo.request[req.bodyOffset:]
+        new_req = helpers.buildHttpMessage(headers, body)
+        messageInfo.request = new_req  # replace the current req with the updated version
+        print('Added X-Request header: {}'.format(state['x-req']))
+else:
+    token = ... # perform retrieval of token (e.g. hidden form field, meta tag etc...); Macro regex generator could help with this ;)
+    state['x-req'] = token  # save in state to be used in next req
+    print('Saved X-Request from response: {}'.format(token))
+~~~
 
 ## FAQs
 

models.py

@@ -5,7 +5,7 @@
 import sys
 import traceback
 
-DEFAULT_SCRIPT = '''# Recommended to use the pyscripterer base script found here https://github.com/lanmaster53/pyscripter-er
+DEFAULT_SCRIPT = '''# Recommended to use the pyscripter-er base script found here https://github.com/lanmaster53/pyscripter-er
 # to be placed into the python environment directory
 
 # from pyscripterer import BaseScript as Script
@@ -123,6 +123,7 @@ def __init__(self, extender, callbacks, helpers, title, enabled=False, content=D
         self.content = content
         self.stderr = sys.stderr
         self.stdout = sys.stdout
+        self.state = dict()
         self._code = None
         self._compiled_content = content
         self._compilation_error = ''
@@ -152,8 +153,9 @@ def processHttpMessage(self, toolFlag, messageIsRequest, messageInfo, macroItems
                         'toolFlag': toolFlag,
                         'messageIsRequest': messageIsRequest,
                         'messageInfo': messageInfo,
-                        'macroItems': macroItems
-                        }
+                        'macroItems': macroItems,
+                        'state': self.state
+                    }
 
             oldstderr = sys.stderr
             oldstdout = sys.stdout
@@ -197,4 +199,4 @@ def from_dict(cls, val, callbacks, helpers, extender):
     class Properties:
 
         COMPILATION_ERROR = 'compilation_error'
-        IS_COMPILED = 'is_compiled'
+        IS_COMPILED = 'is_compiled'