pcap.html

<!--
  Copyright 2016 Nicholas Humfrey

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->

<script type="text/x-red" data-template-name="pcap">
    <div class="form-row">
        <label for="node-input-ifname"><i class="fa fa-sign-in"></i> Interface</label>
        <select class="form-control" id="node-input-ifname">
          <option selected="selected" disabled="disabled" style="font-style: italic" value="">Loading...</option>
        </select>
    </div>
    <div class="form-row">
        <label for="node-input-output"><i class="fa fa-sign-out"></i> Output</label>
        <select class="form-control" id="node-input-output">
          <option value="raw">Raw Network packet as Buffer</option>
          <option value="object">Decoded pcap Object</option>
          <option value="string">String</option>
        </select>
    </div>
    <div class="form-row">
        <label for="node-input-filter"><i class="fa fa-filter"></i> Filter</label>
        <input type="text" id="node-input-filter" placeholder="optional pcap filter">
    </div>
    <div class="form-row">
        <label for="node-input-path"><i class="fa fa-ellipsis-h"></i> Path</label>
        <input type="text" id="node-input-path" placeholder="payload.shost">
    </div>
    <div class="form-row">
        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
        <input type="text" id="node-input-name" placeholder="Name">
    </div>
</script>

<script type="text/x-red" data-help-name="pcap">
    <p>Capture and decode raw packets from a network interface.</p>

    <p>
      A single <b>Interface</b> can be chosen for each node instance.
      The list shows the network interfaces and MAC address of the 
      interfaces on the Node-RED host system.
    </p>

    <p>
      There are three different <b>Output</b> options:
      <ul>
        <li>Raw Network packet - outputs a Buffer object containing the binary packet.</li>
        <li>Decoded pcap objects - the <a href="https://www.npmjs.com/package/pcap">pcap npm package</a>
            contains a set of packet decoder objects.</li>
        <li>String - converts the decoded packet objects to string representation.
            Use the <b>path</b> setting below to choose specific fields.</li>
      </ul>
    </p>
    
    <p>
       The <b>Filter</b> setting can be used to filter the network packets received
       before they get to Node-RED. The syntax is the same as tcpdump/libpcap/wireshark.
       See the <a href="http://www.tcpdump.org/manpages/pcap-filter.7.html">pcap-filter(7)</a>
       man page for details of this syntax.
    </p>
    
    <p>
       The <b>Path</b> setting is only used for the String/Decoded packet outputs. It allows you 
       you choose a sub-property of packet, rather than outputting the whole packet.
       The structure is based on the <a href="https://github.com/mranney/node_pcap/tree/master/decode">decode objects</a>
       within the pcap package. This can be slightly tricky to work out, the documentation
       recommends exploring the structure using <code>sys.inspect</code>.
       Call <code>.payload</code> repeatedly to get to higher level protocol headers.
    
       <h4>Path Examples</h4>
       <ul>
         <li><code>pcap_header.tv_sec</code> the time the packet was recieved</li>
         <li><code>payload.shost</code> the Layer 2 MAC address of the source of the packet</li>
         <li><code>payload.dhost</code> the Layer 2 MAC address of the destination of the packet</li>
         <li><code>payload.ethertype</code> the Layer 2 Ethernet packet type identifier</li>
         <li><code>payload.payload.saddr</code> the source IP address of the packet</li>
         <li><code>payload.payload.daddr</code> the destination IP address of the packet</li>
       </ul>
    </p>

</script>

<script type="text/javascript">
    RED.nodes.registerType('pcap',{
        category: 'network',
        color: '#CC8F8F',
        defaults: {
            name: {value:""},
            ifname: {value:"", required:true},
            output: {value:"object", required:true},
            filter: {value:""},
            path: {value:""}
        },
        inputs:0,
        outputs:1,
        icon: "ethernet-socket.png",
        align: "left",
        label: function() {
            return this.name || this.ifname || "pcap";
        },
        labelStyle: function() {
            return this.name?"node_label_italic":"";
        },
        oneditprepare: function() {
            function loadInterfaces(selectedInterface) {
                $.getJSON("pcap/interfaces").done(function(data) {
                    $("#node-input-ifname").empty();
                    $.each(data['interfaces'], function(key, value) {
                        var option = $('<option/>').text(value);
                        option.attr('value', key);
                        if (key == selectedInterface) {
                            option.attr('selected', 'selected');
                        }
                        $("#node-input-ifname").append(option);
                    });
                });
            };

            loadInterfaces(this.ifname);
        }
    });
</script>