CONTACTS:

Primary Developer:
    Scott Weston, scott.david.weston@gmail.com

Copyright Holder:
    Steve Parker, steve@energysec.org


PRELIMINARIES:

This is pre-release software. By obtaining and using this software, you assume
all responsibility for all outcomes. Before using, you are (as always) advised
to study the sourcecode. You will hold the developers and sponsors of openics
innocent of any damages (however unlikely) that you may incur as a demonstrable
consequence of using openics, or any derived artifacts thereof.


WHAT IS IT?

ICS stands for Industrial Control System.

openics is a library that attempts to decode sniffed control network traffic.
Industrial control protocols are complex beasts; therefore openics is a work
in progress. Currently openics supports MODBUS, DNP3, EIP/CIP. Other protocols
are planned, the architecture is extensible. The authors and sponsors of openics
do not make any claims as to the completeness of any supported protocol 
implementations.


HOW TO BUILD:

The build has only been tested on RedHat, CentOS, and Fedora so far. 
The fasted way to build is by running rebuild.sh


PREREQUISITES:

openics requires pcre-devel, libpcap-devel, libnet-devel, and libnids-1.24 with
the tcp restart patch. libnids-1.24 is included under openics/nids, along with a 
build script that builds and installs libnids in the manner that openics intends
to use it.


SAMPLE IDS

A simple IDS is included in the distribution. 

This IDS is based on 'scenarios', which from conventional IDS signatures in that 
they support a rich predicate syntax. For example, the look for the condition in 
which somebody successfully put a MODBUS controller in listen mode, we could write

    modbus.header.function == diagnostic && 
    modbus.request.subcode == force_listen_mode &&
    modbus.response.status == status_ok

By default, scenarios are read from /etc/ics/scenario.d, although this can be
changed with the -S parameter. Each scenario file should be named as follows:

    domain.organization.ics

i.e.

    org.energysec.ics

This gives any given organization an opportunity to contribute scenarios to 
the commonwealth.

Scenarios are evaluated in the order they are read from each file. Files are
sourced in alphabetical order.

A full scenario is formed as follows (must currently all be on a single line):

    protocol<tab>syslog-priority<tab>reference<tab>description<tab>predicate

Example:

    modbus  alert   cvs-2014-0000000    Modbus listen mode   modbus.header.function == diagnostic && modbus.request.subcode == force_listen_mode && modbus.response.status == status_ok

By default, icsids uses syslog facility 'user', but this can be changed with 
the -f parameter. At the time of this writing, syslog is the only supported 
logging mechanism.

Syntax information can be found in openics/doc. Check the data dictionary files 
for the various protocols (work in progress).


TESING USING PACKET CAPTURES:

Some packet captures are included for testing (openics/testdata). Quality varies.
If you possess anonymized packet captures of control network traffic, please
make them available to help enhance openics. As good way to anonymize packet 
capture files, you can download and use scrub-tcpdump 

    (http://scrub-tcpdump.sourceforge.net/)

The following bash script does a decent job:

    #!/bin/bash
    if [[ "x$1" == "x" || "x$2" == "x" ]]; then
        echo usage: anonymize file1.pcap file2.pcap
        exit 1
    fi
    scrub-tcpdump -r $1 -w $2 -o "srcip pp dstip pp"


HOW TO CONTRIBUTE

1) Send anonymized packet capture files (pcap) of any and all control
   protocols you can get your hands on.

2) Test the openics api and the standalone icsids; make suggestions and 
   report bugs.

3) Let me know if you want to take on a new protocol (yikes!)

4) Consider funding continuing development through EnergySec.org. To 
   give you an idea, minimum expense of a senior developer is $80/h.
   Adding an additional protocol, depending on complexity, can range
   from 100 to 500 man hours, at a cost of between $8,000 and $40,000.