Firebind Reflector Documentation

INTRODUCTION

Firebind Reflector is a network path testing solution that evaluates network performance and security policies over any or all TCP and UDP ports. The companion Firescan client is used on a remote compute instance to initiate traffic to Reflector and to execute one or more user-configured test sequences.

Information that can be generated about the network path between Firescan and Reflector includes:

    • Network security policy settings (e.g. Firewall port blocking, IPS rules, etc.)

    • TCP bandwidth capacity

    • UDP packet loss

    • TCP latency and jitter

    • UDP latency and jitter

Firescan can also initiate tests to user-specified network targets to determine:

    • HTTP response time

    • Open port listeners

Applications for Reflector include but are not limited to testing network performance and security for:

    • Wide area networks including last mile circuits

    • Local area networks

    • Inter-cloud and intra-cloud connections

    • Mobile and fixed wireless

    • Satellite

Reflector is a single executable file, Java-based software appliance with a built-in database and HTTP server. It can be deployed virtually anywhere, including compute instances as small as a Raspberry Pi or a $5/month single core cloud VM. Reflector’s native charts allow users to see results over an extended period of time to help isolate causes of network performance degradation.

SYSTEM REQUIREMENTS 

Firebind Reflector (Server-Side) Requirements:

    • x64 or ARM processor running 64-bit Linux or 64-bit Windows 10 or newer (Raspberry Pi 3 or newer is supported)
    • Java 8 or above (requirement subject to change in a future release)
    • 512 MB RAM
    • 2 core or better CPU recommended but not required
    • 5 GB storage recommended
    • Note: On Windows the latest Microsoft Visual C++ Redistributable package (X64) may need to be installed for Reflector’s database to work properly

Firescan (Client-Side) Requirements:

    • x86, x64 or ARM processor (Raspberry Pi 2 or above is supported)
    • Java 8 or above (requirement subject to change in a future release)
    • Linux, Windows, or macOS
    • 1 core or better CPU

Up-to-date versions of the following browsers are supported:

    • Microsoft Edge
    • Mozilla Firefox
    • Google Chrome
    • Apple Safari
    • Brave

REFLECTOR HELP

				
					

Usage: java -jar firebind-reflector-2.0.0.jar [OPTIONS]

OPTIONS
 -c                      Log access to Reflector HTTP server in file 'http-access-log'.
 -h, --help              Show help and version
 -l LISTEN_ADDRESS       Hostname or IP address that Reflector will use to perform tests.
 -p ADMIN_PORT           TCP port where Reflector will service test requests and serve the
                         Reflector web pages. Default is 8080.
 -x PROXY_ECHO_ADDRESS   When used behind a proxy (or forwarding firewall) this argument
                         specifies the external IP address or hostname that will be given
                         to the Firescan client to perform tests. This is useful when
                         Reflector is running on a publicly available host and privileged
                         port testing is desired. The PROXY_ECHO_ADDRESS is usually the IP
                         address of the firewall that forwards traffic to Reflector.
EXAMPLES
    java -jar reflector.jar
    java -jar reflector.jar -l 192.168.2.200
    java -jar reflector.jar -l 192.168.2.200 -p 80 -x 10.20.2.11

				
			

START-UP

Deploy Firebind Reflector jar file to a compute instance that meets the previously stated requirements.

Basic Start-up

				
					java -jar firebind-reflector-2.0.0.jar  -l 192.168.100.10 -p 80
				
			

Advanced Start-up (run as background process, assign 512 MB memory, generate stdout, stderr, and access logs).

				
					nohup java -Xmx512m -jar firebind-reflector-2.0.0.jar -l 192.168.100.10 -p 80 > stdout.log -c access.log 2> stderr.log &
				
			

An example URL to access the instance of Firebind Reflector above.  Note that at this time Reflector does not have built-in support for HTTPS but one or more options will be provided in a future release.

				
					http://192.168.100.10
				
			

INITIAL CONFIGURATION

Upon start-up, navigate to the Reflector home page.  See Reflector log for address.

Choose Admin then Advanced.  Optionally set Reflector name.

Enable Authentication if desired.  Default username / password is admin / admin.

If you’d like users to be able to test without providing user credentials on the Firescan command line, then enable Anonymous Quality Library access as well.

Multiple Diagnostics options exist.

FIREBIND REFLECTOR LICENSE

Select Admin then License Info to see Firebind Reflector License and Capabilities.  The parameters below are the defaults.  In the future Firebind will offer enhanced licensing that can exceed the limits set below.

    • Tests operating concurrently – how many Firescan instances can be engaged in a test with Reflector at a time
    • Test history – how many historical test records are saved
    • Test components per suite – how many unique test components can be configured in a single suite
    • Configured suites – how many suites can be configured in this instance of Firebind Reflector
    • Configured users – how many total users can be configured
    • Maximum TCP Speed Test download threads – how many unique download threads can be configured for a single TCP Speed test component
    • Maximum TCP Speed Test upload threads – how many unique upload threads can be configured for a single TCP Speed test component
    • Port delay – For Firewall test component, how many milliseconds to wait between each successive port being tested
 

USERS

Select Admin then Users to create new users, set passwords, and designate whether a user has admin privileges.  When authentication is enabled, a user can have one of three permission levels:

      1. Anonymous – a user who isn’t logged in when authentication is enabled can only see the Suites page in order to retrieve the command line arguments to execute a suite.
      2. Logged-in, non-admin user – this user has the capabilities of the anonymous user and can also see all test results.
      3. Logged-in, admin user – this user has the capabilities of the above users plus full administrative control over the instance of Firebind Reflector.

Important Note: If authentication is enabled, suites can be executed only if one of the following two conditions are met:

      1. Allow Anonymous Quality Library Access is enabled on the Advanced page.  In this case, username and password do not need to be included in the Firescan command line.
      2. If Allow Anonymous Quality Library Access is not enabled, then the username and password of a configured user (admin or non-admin) must be including in the Firescan command line using the -n (username) and -p (password) flags.

SYSTEM STATUS

Select Admin then Status.

View key informational aspects of Firebind Reflector.

CONFIGURATION

Select Admin then Config.

CREATE A NEW SUITE

EDIT SUITE

Optionally edit an existing suite by selecting the Edit button as seen in blue below.

FIREWALL TEST

This test component will send a Firebind generated payload between the Firescan client and Reflector over all of the configured TCP and UDP ports.  It will wait up to Timeout seconds for the payload to be echoed back to Firescan before moving on to the next port.  If a port is designated as open, that means that the payload was able to traverse the network between Firescan and Reflector in both directions without being blocked or modified.

As of v2.0.2 of Firebind Reflector, users can chose a protocol script that can be “played back” between Firescan and Reflector, simulating real-world traffic.  Scripts can be sourced from Firebind’s Github page or user provided via the script upload option.

TCP SPEED TEST

Firescan will send data over the chosen TCP port as fast as possible for the configured duration and over the configured number of threads.  If the given upload or download threshold is not met, the test will fail.

UDP PACKET LOSS TEST (UDP SPEED TEST)

Firescan will stream UDP traffic using the configured parameters while monitoring for packet loss.

TCP LATENCY AND JITTER

Test TCP latency and jitter between Firescan and Reflector.

UDP LATENCY AND JITTER

Test UDP latency and jitter between Firescan and Reflector.

TCP PORT CHECK

Firescan will attempt a TCP handshake with the target host to check for active TCP port listeners.

HTTP CHECK

Test HTTP(S) response time between Firescan and the configured target host.  Note that the CPU speed of the Firescan host machine will greatly affect response time.  For example, an older Raspberry Pi may require 2,000+ milliseconds to load a web page that a typical laptop CPU could load in less than 500 milliseconds.

SUITE EDIT

After the suite is configured, you may Edit, Duplicate, or Delete a component, or use the Move buttons to change the order of execution of the components.

RUN A SUITE

Once your suite is configured, go to the Suites page.

The Firescan client can be downloaded from this page.  Click Show to view the command line that will be used by Firescan to execute the suite.  Copy the command line to the clipboard and then paste the command line into the Firescan machine in order to start testing.

FIRESCAN HELP

				
					

Usage: firescan [options]

Options
    -g, --tag TAG                   Tag the scan with value
    -h, --help                      Show help and version
    -l, --local-address ADDRESS     Local address to bind for client networking
    -lc, --loop-count COUNT         Perform requested operation N times in a loop (use zero for infinite)
    -ld, --loop-delay DELAY         When looping, delay by this many seconds between iterations
    -n, --username USERNAME         Specify a username (to connect to command server)
    -p, --password PASSWORD         Specify a password (to connect to command server)
    -s, --command-server ADDRESS    Address:port or hostname:port of command server, default port is 80
    -suite, --run-suite CODE        Run a quality suite by code
    -t, --tcp PORT_LIST             TCP Port specification (list), use commas and dashes to specify a list of ports
    -u, --udp PORT_LIST             UDP Port specification (list), use commas and dashes to specify a list of ports

Examples:
    java -jar firebind-firescan-2.0.0.jar -s 192.168.100.50:80 -t 400-500,610,750-788
    java -jar firebind-firescan-2.0.0.jar -s 192.168.100.50:80 -suite mysuite -n myuser -p mypassword
    java -jar firebind-firescan-2.0.0.jar -s 192.168.100.50:80 -suite mysuite -lc 3 -ld 2

				
			

GRAPHS

TCP Speed Test

UDP Packet Loss Test (UDP Speed Test)

TCP Latency and Jitter

UDP Latency and Jitter

HTTP Check

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)