MuSL Builder Handcrafting custom Mu Scenarios. MuSL in the Mu Scenario Editor.

MuSL Builder

Handcrafting customMu Scenarios

MuSL in the Mu Scenario Editor

MuSL Builder Overview

• MuSL_Builder is a Ruby project that creates scenarios in the Mu Scenario Language (MuSL)

• Each MuSL_Builder component class creates a single protocol message

• Classes are chained together to create a complete scenario

The Power of MuSL_Builder

• From a few message classes, it is easy to create a wide variety of scenarios

• For example, to create a simple ‘ping’ flood, one would only need to use a single ICMP message class and a one-line statement in a MuSL_Builder properties file: messages=IcmpPing(100)

A SIP Example

• Given the sample SIP message templates, you could easily create a wacky scenario from properties files entries such as:

sequence=wacky:SipInvite(17),SipPrack(3),SipBye,SipRegister(2),SipAck,SipBye,SipTrying(12)

messages=wacky(114)

• A scenario created from this definition would contain 4,218 messages

MuSL Builder Source Code

• The project is located in mu-labs:– http://code.google.com/p/mu-labs/source/brows

e/trunk/analyzer/automation/MuSL_Builder

• The project contains sample code for a variety of protocols, including SIP, IMAP, FTP, BGP and ICMP

MuSL Builder Pieces

• A complete set of MuSL Builder components includes:– A Builder class

• the executable run from the command-line

– A Base class• custom headers, options and variables

– A Properties File• defines the scenario

– Protocol Message Classes• compose the scenario steps

Base Classes

• Each component implements its own Base class in order to customize the header with:– global transports– options– variables

• Base classes derive from a common base class which contains the main processing methods

SipBase with transport and options

Message Classes

• There are two types of messages:– Client messages are sent to a Server– Server messages are sent to a Client

• Each message class creates a complete protocol message in MuSL

A Sample Message

• Each message class consists of:– a constructor (def initialize)– a configure() method, which produces a protocol

message in text from a template object, and increments a step counter

• Templates often contain some embedded ruby code, which is replaced at runtime by option or variable values

A Sample Message Class

A Sample Message

• In the example template, the following line in the template:– SIP_Client_Send_<%= @base.counter %> =

• Is transformed at runtime, replacing <%= @base.counter %> with the value of the base class’s ‘counter’ field.

• The resulting line might look like this:– SIP_Client_Send_2 =

Builder Classes

• Each component implements its own Builder class – this is the executable class

• Builder classes:– derive from a common base class– read in a properties file– output a complete scenario in the Mu Scenario

Language• Builder classes create a Hash (called ‘params’)

from the properties file which is passed into the Component base class constructor

A Sample Builder Class

Properties Files

• A properties file is a text file containing– parameters– sequences – messages

• The properties file is read by the builder (executable) and contains the blueprint for constructing the scenario

• Properties files can have any name

Properties Files: Parameters

• Parameters are passed along to base class constructors, and typically contain global option and variable names and default values:– domain=mydomain.com– sender=joe_sender– recipient=joanna-recipient

Properties Files: Sequences

• Sequences– Sequences are comma-separated lists of component

message class names, in the format– sequence=sequence_name:Class1,Class2,Class3…

• sequence=bye:SipBye,SipOk• A properties file can contain any number of user defined

sequences

– Sequences also provide a repeat syntax, which causes the specified message to be repeated as many times in a row as indicated• sequence=flood:SipInvite(1000),SipBye(12),SipOk

Properties Files: Messages

• Messages are a comma-separated list containing any combination of message class and/or sequence names

• There can be only one messages line per properties file messages=bye,SipAck(12),flood,SipRinging,SipAck(2)

• Using messages and sequences, all sorts of message patterns can be arbitrarily constructed

Building a Scenario

• From the command-line in the root directory, invoke ruby specifying a builder class filename and a properties filename. ruby sipbuilder.rb properties/sip.properties

• The resulting text is a complete scenario in the Mu Scenario Language

Load the scenario into the MuSL Editor

• Open the Mu Scenario Editor in pcapr.net• Copy and Paste your MuSL Builder scenario

into the left pane• Any syntax errors will be caught and indicated

by the editor• The right pane will show the actual hex or text

output of the scenario

Importing into Studio

• In order to import your scenario into Studio from the Mu Scenario Editor, you must have first opened pcapr from the Mu

• Click the ‘studio’ link above the right pane• The scenario will be imported into the Mu and

opened in a new browser window

Executing the Scenario

• In Mu Studio, set your testbed appropriately and run the scenario as usual– Scenario -> Verify

Customizing the Scenario

• Assertions are placed in Component Server classes

• Global options and variables are placed in Component Base classes

• Captured variables are placed in Component Server classes

Sample Assertions and Variables

SIP_Client_Receive=SIP_Server_Send.client_receive{ assertions { /SIP\\/2.0 (\\d+)/:1 == "200" } variables { @to_tag = /To:.*?tag=(\\w+)/:1 } }

Sample Global Options

template = 'scenario(name: "SIP") { options { $domain="<%= @domain %>” $sender="<%= @sender %>" $recipient="<%= @recipient %>" } steps { SIP = udp(src_port: 5060, dst_port: 5060) }}'

Sample Global Variables

template ='scenario(name: "ICMP") { variables { @data = random_bytes(56) @id = random_integer(4096) } steps { ICMP = ip(protocol: 1) }}'