erspan 0.2.2

Unwraps original data packet from GRE/ERSPAN packet
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

# ERSPAN-RS

This is a helper library to unwraps original packet from GRE encapsulated packet. This is a handy utility 
for network monitoring apps receiving spanned traffic from a router in a remote destination.

The data encapsulated into
a GRE packet might be SPAN data generated by Cisco or other supported routers. Encapsulated data can be delivered
over TCP/IP network to a remote destination. In contrast to local SPAN port on router this is more flexible
solution for network monitoring. The library enabled a Rust based service to decapsulate the original
data from GRE encapsulated packet like ERSPAN.

The library was tested on ERSPAN Type II and III only on linux and Cisco router.

The entrypoint into the library is `erspan_decap(packet_bytes)` function that returns a `Result` with 
either *ErspanHeader* header or *ErspanError*. The header provides details from the encapsulation packet
binary and the *original_data_packet* with spanned traffic from a router. The error come otherwise if the packet
is an invalid data structure.

Parsing of the `ipv6erspan` is not covered yet.

More documentation

- GRE packet structure and RFC
  see [description on wikipedia](https://en.wikipedia.org/wiki/Generic_Routing_Encapsulation)
- Introduction to [SPAN and remote ERSPAN](https://ipwithease.com/introduction-to-span-and-rspan/)
- Setting up ERSPAN on Cisco routers
  like [Nexus 7000](https://www.cisco.com/c/en/us/td/docs/switches/datacenter/nexus7000/sw/system-management/config/cisco_nexus7000_system-management_config_guide_8x/configuring_erspan.html)
- Cisco Network Analytics (aka Stealthwatch) ERPSAN decapsulation configuration guide
  see [SNA Configuration Guide](https://www.cisco.com/c/dam/en/us/td/docs/security/stealthwatch/system_installation_configuration/7_4_2_System_Configuration_Guide_DV_1_2.pdf)
- ERSPAN packets are supported on by Linu kernel as well, see `ip-link` [man pages](https://manpages.ubuntu.com/manpages/impish/en/man8/ip-link.8.html)

## Usage

See examples in the project for Type2 or Type3 ERSPAN packet unwrapping

For type 2 packet run:

    cargo run --example type_2

For type 3 packet run:

    cargo run --example type_3

Monitoring GRE/ERSPAN packets from local interface

    cargo run --example packet_capture <interface name>

Note: the example needs libpcap to be installed on *nix systems and Mac. For Widnows installation please refer to
the `libpnet`'s installation steps for WinPcap [installation manual here](https://github.com/libpnet/libpnet#windows)

## Building and testing

    cargo build
    cargo test

# Configuring Linux machine to generate ERSPAN packets

Linux kernel has module to generate ERSPAN traffic as a copy of traffic on a local interface. Those steps shows
configuration tested on Ubuntu 22 LTS for creating *erspan* network interface:

Creates new *erspan* interface reporting ERSPAN packets from `10.0.10.140` to ip `10.0.10.135` with version 2 and 
session id 1 from original interface `ens4`

    sudo ifconfig ens4 mtu 1900
    sudo ip link add dev erspan mtu 1900 type erspan seq key 10 local 10.0.10.140 remote 10.0.10.135 erspan_ver 2 erspan 1 dev ens4 erspan_dir egress erspan_dir ingress

This prevents kernel from dropping packets

    sudo ip link set dev erspan type erspan noiseq

Sets interface up and running

    sudo ip link set erspan up

Monitoring processing traffic using tcpdump

    sudo tcpdump -i erspan

Duplicating traffic from *ens4* to the *erspan* interface

    tc qdisc add dev ens4 handle ffff: ingress
    tc filter add dev ens4 parent ffff: matchall skip_hw action mirred egress mirror dev erspan


# Contributing

Check out our [contributing guidelines](CONTRIBUTING.md) for this project

# License

See [LICENSE](LICENSE)