Writing Your Own PuppyScripts

Writing Your Own PuppyScripts

The default PuppyScript and the other examples that ship with Sleepy Puppy should cover most use cases. However for some circumstances you may need to customize these PuppyScripts or create your own.

For reference, lets step through one of the PuppyScripts: Default without Screenshot. We will use this one because it is very straightforward.

##Default Without Screenshot

function capture(){
          var user_agent = navigator.userAgent;
          var uri = document.URL;
          var referrer = document.referrer;
          var cookies = document.cookie;
          var dom = document.documentElement.outerHTML;
          var payload = {{payload}};
          var assessment = {{assessment}};
        $.ajax({
                type: "POST",
                url: "{{callback_protocol}}://{{hostname}}/callbacks",
                data: {
                  uri: uri,
                  payload: payload,
                  referrer: referrer,
                  cookies: cookies,
                  user_agent: user_agent,
                  dom: dom,
                  assessment: assessment
                  }
          }).done(function (respond) {
            console.log(respond);
        });
}
//invocation
$(document).ready(capture());

The script 'default without screenshot', provides comprehensive metadata collection without generating a screenshot. When we use the capture model, we can post the required metadata back to /callbacks and screenshots with identifier back to /up.

We have included all required metadata including uri,payload,referrer,cookies,user_agent,dom,assessment. We also leveraged the templates {{callback_protocol}} and {{hostname}} so those fields will be filled in correctly by Sleepy Puppy.

We wait until the client is ready, then invoke the function to perform the capture.

##Generic Collector For more advanced use cases, you may need to collect additional metadata outside the typical capture. An example may be specific text scraped from a client or local storage data.

The generic collector provides a way for you to record this data in text format. Let's look at an example script that leverages the generic collector.

##Generic Collector: IP Address This example script uses Ajax to another web service to determine the user's IP address. Although pretty impractical, this does demonstrate how you can leverage this endpoint for collecting arbitrary data.

function capture() {
    var puppyscript_name = "Generic Collector: IP Address"
    var uri = document.URL;
    var referrer = document.referrer;
    var payload = {{payload}};
    var assessment = {{assessment}};
            $.ajax({
                url: 'http://ipinfo.io',
                dataType: 'jsonp',
                success: function(stuff) {
                    // call next ajax function
                    $.ajax({
                        type: "POST",
                        url: "{{callback_protocol}}://{{hostname}}/generic_callback",
                        data: {
                            uri: uri,
                            payload: payload,
                            referrer: referrer,
                            puppyscript_name: puppyscript_name,
                            data: stuff.ip,
                            assessment: assessment
                        }
                    }).done(function(respond) {
                        console.log(respond);
                    });
                }

            });
        }
//invocation
$(document).ready(capture());

This example shows how you can log arbitrary data to the Generic Collector.

Simply specify the following parameters in your POST request to https://server/generic_collector:

payload: the payload that was triggered in the user's browser. Use {{payload}} template to fill this in automatically.

assessment: the assessment that is associated with this generic collector. Use {{assessment}} template to fill this in automatically.

puppyscript_name: the name of your puppyscript file that was used to generate the generic collection

data: any data in Text/Json format. Do not send binary data.

(optional) uri: If you are using the ALLOWED_DOMAINS filter, you must specify a uri or Sleepy Puppy will not filter the generic collection