Le blog des experts sécurité Wavestone

[EN] GRASSMARLIN, an open-source tool for passive ICS network mapping

This blog post is also available in French here.

The first step of an industrial control system (ICS) cybersecurity project is most of the time the creation, or the consolidation, of the inventory of all networked components.GRASSMARLIN answers to this need by giving a network mapping solution based on passive detection

 GRASSMARLIN presentation

GRASSMARLIN is a passive network mapper dedicated to industrial networks and developed by the National Security Agency (NSA). The tool has recently become open-source and is directly available on GitHub (
GRASSMARLIN gives a snapshot of the industrial IS including:

Devices part of the network;
Communications between these devices;
Metadata extracted from these communications.

Currently GRASSMARLIN is available on Windows (7 and +, exclusively 64bits), some version of Linux (Fedora, Ubuntu), and can be downloaded from:

Maintaining ICS availability is a paramount necessity. In fact any failure can lead to important consequences going from loss of service to loss of life. Thus in order to not disrupt the availability of industrial devices all the mapping is done passively by GRASSMARLIN. In fact, GRASSMARLIN record and analyse passively the communications unlike active mapping tools, such as nmap or plcscan, which send packets over the network and analyse the potential answers.


GRASSMARLIN gives two types of views:

The “Logical View”: lists all the devices and the communications between them.
The “Physical View”: lists the physical links between the industrial and network devices.

Passive detection

Since the detection method is passive GRASSMARLIN does not generate any traffic on the network. Thus in order to get the results of the logical view GRASSMARLIN simply sniffs the traffic over the network like a classical packet analyser. This means also that GRASSMARLIN can only analyse traffic that it is actually able to sniff on his host machine.

GRASSMARLIN’s visibility scope

The logical view can be obtained during a live traffic capture or thanks to capture files (PCAP files) generated at a later time on another point of the network. Such as the logical view, the physical view is also generated passively thanks to the logs of Cisco routers.

Logical View

In this view, the network topology is presented as follows:

Figure 2 : Logical view with 2 Siemens PLC

This topology is generated from a packet capture of 2 industrials devices which use the industrial communication protocol S7Comm. Those PCAP files can be downloaded from:
The main map (at the right of Figure 2) shows the devices on the network and the communication between the devices and sub-networks, each device is identified by its IP address.
Moreover, GRASSMARLIN can recognize industrial devices and protocols thanks to integrated signatures:

Logical View and details provided by GRASSMARLIN

In this case, the protocol used is well-recognized as S7Comm. Besides, the role of devices is detailed: the master (Human Machine Interface - HMI) gives orders whereas the slave (Programmable Logical Controller - PLC) executes them. The Vendor Name is also informed to help ICS managers locate the devices. If the IP addresses are public (which is not the case here) the countries are also informed with their respective flags.
All this information is generated after the confrontation between the captured packets and GRASSMARLIN’s signatures. Thus the attribute confidence going from 1 (not confident) to 5 (confident) gives the trust that user can put on the provided details.
It is also possible to isolate communications linked to a particular device and get a first analysis: packets’ size, instant of emission, packets’ origin (if more than one PCAP file is used):

Figure 4 : Analysis data provided by GRASSMARLIN

 Protocols signatures

GRASSMARLIN comes with signatures or fingerprints that allow identifying the protocols used on the logical view. Each signature is composed with two types of elements:
The filter element: describes the element to detect
The payload element: returns information to user
One signature can be composed of more than one filter and each payload is linked to one filter:

MODBUS signature example

Filters can essentially describe the protocols attributes of the layer 2 to 4 of the OSI model. Here is a list of all the filters available:

Available filters

Payloads aim to give more information to the user by extracting for example some bytes from the packets or checking the existence of patterns.

Current version of GRASSMARLIN (v3) has 54 fingerprints ready to be used out-of-the-box including most of the industrial protocols. The tool has recently become open-source (01/28/16) and it is likely that the number of signatures will increase and their accuracy improve with the years coming.
Signatures are edited on the XML format nevertheless a graphical tool, FingerPrint Editor, is proposed by GRASSMARLIN in order to help signatures creation:

Fingerprint Editor a graphical tool to edit signatures

Physical View

This view gives the physical links existing between devices:

Physical view

More focused on the network aspect this view informs about the physical connection between the industrial devices and network equipment. On V3 of GRASSMARLIN only Cisco routers are supported and the physical view is generated from the output of 3 commands:
“show running-config”
“show ip arp” (OU) “show mac address-table”
“show interfaces”
Once the outputs of these commands are saved on a simple text file, GRASSMARLIN can generate the physical view.

Data export 

Data can be exported from GRASSMARLIN thanks to 3 types of export:
  • Views export on PNG format
  • Data export on XML format:
    • Save the data of the entire connection tree on the logical view.
    • This data can then be used as session data by GRASSMARLIN.
  • Data export on an archive; including: the data on XML format and the PCAP files generated during the live captures.

Bench Testing

Tests have been performed on one of the ICS model of Solucom in order to confront GRASSMARLIN to a practical use case.

Presentation of ICS test bench
The ICS model simulates a railway switch and it is composed of:
1 human interface machine (HIM) Siemens ;
1 Siemens PLC ;
2 Schneider PLC ;
1 switch.

ICS test bench

A workstation with GRASSMLARIN installed is directly connected to a mirroring port on the switch and can thus access to the entire communication on the ICS model. Since the model has no Cisco devices only the logical view has been tested.


After a live capture, GRASSMARLIN has generated the following view:

Figure 9 : Logical view of the test bench

And, after a (manual) reorganization the view becomes:
Reorganized logical view

Devices appear on the map quickly after communications are intercepted. GRASSMARLIN has correctly identified all the devices and correctly given the protocols used. Moreover, the XML file given on output is also well generated with all the information extracted by GRASSMARLIN and allows to re-use them later:

XML file output

Nevertheless, some limitations have been observed:
  • Non-concurrence of signatures
    If a device matches more than one signature only one is chosen by GRASSMARLIN. This can be an issue for an HMI which potentially communicates with more than one PLC using different communication protocols.
  • Lack of verbosity of some signatures:
    Most signatures have description fields on their payload in order to describe the identified device. It is possible that these fields are leaved blank or poorly informed which can complicate the identification of industrial devices. 
  • Limited analysis function
    GRASSMARLIN only gives the first elements for communication analysis such as: packets’ size, received time. One possible way to improve this function is to add for example a communication pattern recognition between the HIM and PLC’s.


Others tools based on passive detection methods are available on the market. Nevertheless, GRASSMARLIN is one of the rare, if not the only one, to be both dedicated to industrial IS and Open-Source.

For example another tool named NetworkMiner allows getting networks topologies using signatures from other well-known tools such as: nmap, p0f and Ettercap. Nevertheless, NetworkMiner does not have any industrial signatures ready out-of-the-box and thus is less accurate than GRASSMARLIN.

Output of NetworkMiner with 2 Siemens PLC

Other example – output of p0f with 2 Siemens PLC

Output of GRASSMARLIN with 2 Siemens PLC

Mention can also be made of the commercial solution Sentryo, completely dedicated to ICS. This solution does not only generate a map at one instant but also keep track of any changes on the communications patterns and gives alerts if anything unusual is detected. During one live demonstration that we have seen the accuracy of details was well above GRASSMARLIN’s output (vendor name, model, PLC’s components, and firmware version was informed for example).


2 commentaires:

  1. Very good article, this software seems very interesting.

    Do you now how to install it on linux ? There's no executable file for linux in the github repo

  2. You can download the package and install it as usual using dpkg command, please refer to: