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 protocol messages from text template files • Messages 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 Files • compose 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 Files • There are two types of messages: • Client messages are sent to a Server • Server messages are sent to a Client • Each message file creates a complete protocol message in MuSL • Message files are simple .txt files containing messages in the Mu Scenario Language

13. A Sample Message File # Request: USER anonymous FTP_Client_Send_<%= @step %> = <%= @transport %>.client_send { # ftp|File Transfer Protocol (FTP) "USER "$user"\\r\\n" } FTP_Server_Receive_<%= @step %> = FTP_Client_Send_<%= @step %>.server_receive

14. Sample Message: Step • The ‘step’ 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_<%= @step %> = • Is transformed at runtime, replacing <%= @step %> with the value of the global ‘step’ field. • The resulting line might look like this: • SIP_Client_Send_2 =

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

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

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

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

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

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

21. Properties Files: Additional Transports • Sometimes you may want to add a transport later in the scenario. In the properties files, transports look similar to sequences: • transport=key:value • The transport can be added to a ‘sequence’ or put directly into ‘messages’. The transport can be used in any following step, using the alternate transport syntax • Musl_Builder changes the transport to a string in the form of “key = value” and inserts it into the scenario • Example: • transport=FTP_2:tcp(dst_port: 21) • messages=FTPReady,FTPUser,FTP_2,FTPGoodbye[FTP_2] • FTP_2 = tcp(dst_port: 21)

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, including the erb substitutions needed for step counters and transports • Use these as the template strings in your message class files • ** You will still need to edit the strings to • a) create unique struct names (if any) with <%= @step %> • b) insert your global options and variables