metron-deployment/roles/sensor-stubs/README.md

# Sensor Stubs

A service has been created to simulate the behavior of a sensor by sending canned telemetry data to a Kafka topic.  These "Sensor Stubs" consume fewer resources than the actual sensor that they replace.
 
### (Q) How do the sensor stubs work?

The stubs are installed with a set of canned data for each sensor type; Bro, Snort and YAF.  A subset of this canned data is randomly selected and sent to the Kafka topic in batches.  The timestamp of each message is updated to match current system time.  

### (Q) How do I configure the message rate?

The number of telemetry messages sent in each batch, along with the time delay between batches is configurable.  Before installation, these values can be configured by redefining `sensor_stubs_delay` and `sensor_stubs_count`.  The values can also be configured by altering the deployed system service script at `/etc/init.d/sensor-stubs`.

### (Q) How do I install the sensor stubs?

Using the default playbooks, this role can be installed by using the Ansible tag `sensor-stubs`.  This service is installed on the same hosts where the sensors would be; defined by the `sensors` host group.

The defaults for the "Quick Dev" and "Full Dev" environments have been changed so that  the Sensor Stubs are installed by default, rather than the sensors themselves.  The Amazon EC2 environment continues to install the original sensors by default.

### (Q) How do I use the sensor stubs?

Start all sensor stubs.  The output includes the PID for each running sensor stub.
```
$ service sensor-stubs start
Starting sensor-stubs...
       bro: Ok [26505]
       yaf: Ok [26507]
     snort: Ok [26509]
```

Check the status of each sensor stub.
```
$ service sensor-stubs status
Checking sensor-stubs...
       bro: Running [26505]
       yaf: Running [26507]
     snort: Running [26509]
```

Stop all sensor stubs.
```
$ service sensor-stubs stop
Stopping sensor-stubs...
..       bro: Ok [26505]
..       yaf: Ok [26507]
..     snort: Ok [26509]
```

Check the status.  All sensor stubs should be stopped.
```
$ service sensor-stubs status
Checking sensor-stubs...
       bro: Not running
       yaf: Not running
     snort: Not running
```

Start only the Bro sensor stub.
```
$ service sensor-stubs start bro
Starting sensor-stubs...
       bro: OK [11616]
```

Stop the Bro sensor stub.
```
$ service sensor-stubs stop bro
Stopping sensor-stubs...
..       bro: Ok [11616]
```

### (Q) How do I install the original sensors?

The default behavior can be changed by skipping the `sensor-stubs` flag and including the `sensors` flag. For example, to deploy "Quick Dev" with the original sensors run the following command.

```
cd metron-deployment/vagrant/quick-dev-platform
vagrant --ansible-skip-tags="sensor-stubs,solr" up
```

### (Q) Where does the mock data come from?

The data produced by the sensor stubs was generated by running the sensors against the example pcap file that is distributed with Metron.  This ensures that the data produced by the sensor stubs is similar to the data produced when using the actual sensors.