Protocol Scripts
Protocols
Virtually any OSI layer 7 protocol can be simulated using the Protocol Script feature of Firebind Recon. Firebind agents can support wire-level protocol exchanges between each other by using a protocol script definition file. The contents of the script definition file describe a structured exchange of messages. Additionally, both the content (in binary form) and sequencing can be explicitly specified.
Firebind maintains a public repository of protocol scripts on Github here: https://github.com/Firebind/firebind-protocols
Scripting
Scripts are simple text files that contain the message contents and sequencing for the exchange between the initiator agent and Firebind public target. A script will define 2 or more message blocks, declare attributes and specify the order the messages are to be exchanged.
Here is an example of a short script:
Name "HTTP"
msg 1, INITIATOR->TARGET {
"GET /" $(GUID) "HTTP/1.1"
0x0D 0x0A 0x0D 0x0A
}
msg 2, INITIATOR<-TARGET {
"HTTP/1.1 200 OK"
0x0D 0x0A 0x0D 0x0A
}
Note the Name attribute and the two message blocks for msg 1 and msg 2.
Attributes
Attributes are name/value pairs declared in the script that specify parameters of the scan. An attribute name is followed by its value. The value is always enclosed in double quotes.
Static Attributes
Static attributes can be defined anywhere in the script. These attributes are simple value substitution mechanisms. They are useful when substituting the same value multiple times. A static attribute is defined like this:
<name> "<value>"
An example usage for a static attribute is like:
DOCUMENT "index.html"
msg 1, INITIATOR->TARGET {
"GET " $(DOCUMENT) " HTTP/1.1" 0x0D 0x0A
"GUID: " $(GUID) 0x0D 0x0A
}
Dynamic (Predefined) Attributes
Example usage:
# attribute test
Name "TEST_SCRIPT"
# attributes
# show just the day/month/year
TimestampFormat "dd-MMM-yyyy"
msg 1, INITIATOR->TARGET {
"FROM-INITIATOR-MSG1 " $(GUID,64) " "
"INITIATOR_IP=" $(INITIATOR_IP)
",TARGET_IP=" $(TARGET_IP)
",TARGET_PORT=" $(TARGET_PORT)
",TIMESTAMP=" $(TIMESTAMP)
}
msg 2, INITIATOR<-TARGET {
"FROM-TARGET-MSG2 " $(GUID,64) " "
"INITIATOR_IP=" $(INITIATOR_IP) ",
TARGET_IP=" $(TARGET_IP) ",
TARGET_PORT=" $(TARGET_PORT) ",
TIMESTAMP=" $(TIMESTAMP)
}
Message Block
A message block describes a one-way transmission between the initiator and target Reflectors. The message block has these parts:
- Message Number, this describes the sequence in ascending order.
- Directionality, either INITIATOR->TARGET (sent from the client) or INITIATOR<-TARGET (sent from the server).
- Contents, the actual wire contents of the message, described using text, hexadecimal, decimal or binary fields. This is enclosed in curly braces.
An example message block describing an RTSP request might look like this:
msg 1, INITIATOR->TARGET {
"SETUP rtsp://firebind?AppUid=" $(GUID.TXT) "&AssetUid=0008000b&NodeGroupId=1&PackageId=0 RTSP/1.0" 0x0D 0x0A
"CSeq: 1" 0x0D 0x0A
"Firebind-Version: 2.0" 0x0D 0x0A
"Transport: MP2T/AVP/UDP;unicast;destination=0.0.0.0;client_port=21310" 0x0D 0x0A
"Firebind-MayNotify: " 0x0D 0x0A
"Firebind-Server-Data:node-group-id=1;device-id=001513d29e27" 0x0D 0x0A
"Firebind-Mod-Data:time-remaining=37;purchase-time=1121374553"
0x0D 0x0A 0x0D 0x0A
}
Note the following parts of this message:
msg 1
Specifies that this is a message block and its number is 1
INITIATOR->TARGET
Specifies the message is sent from the initiator agent to the Firebind target
{
Denotes the beginning of the message content, must be on the same line as the message number
“SETUP rtsp://firebind?AppUid=”
This is a string literal, it will be translated into wire-format using UTF-8 encoding.
$(GUID.TXT)
This is a variable that will substitute the GUID identifier of the scan. This is required for all messages sent from the client to the server so the server can identify which client sent the message. More about this variable is described below.
0x0D
Hexademical literal, this describes a wire-level byte pattern. It will be encoded in binary format on the wire.
}
Denotes the end of the message block. This must be on its own line.
Requirements
# The first message (msg 1) must be sent from the initiator to the target (INITIATOR->TARGET). Subsequent messages may be sent in any direction and in any order. # The $(GUID) variable must be encoded into every message sent to the target (INITIATOR->TARGET). This is required. # Width specifications on the $(GUID) and other attributes must be a multiple of 8 (byte encoding)
Message Content
$(GUID) Requirement
The numeric scan identifier (GUID) is required to be transmitted in every message sent from the initiator to the target. This is how the target will uniquely identify which scan is associated with which initiator. The GUID is substituted into a message using the $(GUID) syntax. Field width can be specified using a comma, for example $(GUID,64) will format the number into 64 bits, zero padded. And $(GUID,16) will format the identifier into 16 bits. The identifier can be expressed using the following formats:
Note that when using the width option with text representations of the identifier, it is specified in bits not characters. Therefore, the specification $(GUID.TXT,144) will format the textual representation of the identifier into 18 characters.
Remember!
- All text is encoded as UTF-8
- $(GUID) is required for all INITIATOR->TARGET messages
- Comments begin with a pound (#) sign and extend to the end of the line
- The Name attribute has some restrictions: no spaces (use underscore) and no special characters (alphanumeric only)