MuSL Builder

1. MuSL Builder Handcrafting custom Mu Scenarios

2. MuSL in the Mu Scenario Editor

3. 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 from a text template • Classes are chained together to create a complete scenario

4. High Level: The Builder UI

5. Builder UI • The Builder UI puts together properties from the parameters and scenario steps dynamically created by the user • The Builder UI then builds the MuSL file using the MuslBuilder class

6. 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)

7. 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

8. MuSL Builder Source Code • The project is located in mu-labs: • http://code.google.com/p/mu-labs/source/browse/trunk/analyzer/automation/MuSL_Builder • The project contains sample code for a variety of protocols, including SIP, IMAP, FTP, BGP and ICMP

9. MuSL Builder Pieces • A complete set of MuSL Builder components includes: • The MuslBuilder class • the executable run from the command-line • A Base class • defines custom headers, options and variables • A Properties File • defines the scenario • Protocol Message Classes • composes the scenario steps

10. Base Classes • Each component implements its own Base class in order to customize the header with: • transports • options • variables • Base classes derive from a common base class which shares global fields among messages of the same component

11. FTPBase with transport and options

12. 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 • Message classes are always enclosed in module MuslMessage

13. 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

14. A Sample Message Class

15. Sample Message: Counter • The counter is a unique identifier for each message pair, and is tracked globally • 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 =

16. Sample Message: Transport • Each message class has a default transport in its constructor • The default transport can be overridden by specification in the properties file: • messages=FTPMkdir[ALT_FTP_TRANSPORT] <%= @transport %>.client_send becomes ALT_FTP_TRANSPORT.client_send

17. The MuslBuilder Class • muslbuilder.rb is the executable class • reads in a properties file or array • output a complete scenario in the Mu Scenario Language • The builder class creates a Hash (called ‘params’) from the properties which is passed into the Component base class constructor

18. Properties • Properties can be in a text file or passed in to muslbuilder as an array, containing • options • sequences • messages • components • scenario_name • The properties are read by the muslbuilder (executable) and contain the blueprint for constructing the scenario • Properties files can have any name

19. Properties: Parameters • Parameters are passed along to base class constructors, and typically contain global Scenario option or variable names and default values: • domain=mydomain.com • sender=joe_sender • recipient=joanna-recipient • The only required properties are “messages” and “components”, which defines the name of the protocol(s) to be used • components=FTP,HTTP

20. 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

21. 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

22. Building a Scenario • From the command-line in the root directory, invoke ruby specifying and a properties file name. ruby muslbuilder.rb properties/sip.properties • The resulting text is a complete scenario in the Mu Scenario Language

23. 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

24. 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

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

26. 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

27. 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 } }

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

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

30. MuslParser: From Pcap To MuslBuilder • MuslBuilder message classes can be built readily from existing pcaps • 1. import pcap into the MuSL Editor • 2. save the left-pane as a text file (e.g. “a.msl”) • 3. ruby musl_parser.rba.msl output_ • MuslParser splits the .msl file into individual message step text files • Use these as the template strings in your message class files • ** You will still need to edit the strings to • a) create unique message and struct names with <%= @base.counter %> • b) insert your global options and variables