• Stars
    star
    179
  • Rank 214,039 (Top 5 %)
  • Language
    C
  • License
    BSD 3-Clause "New...
  • Created almost 15 years ago
  • Updated 12 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Erlang packet capture interface using pcap

An Erlang port interface to libpcap.

epcap includes a small example program called sniff.

QUICK SETUP

$ rebar3 compile # or: make

To compile the examples:

$ make examples

# Allow your user to epcap with root privs
sudo visudo
youruser ALL = NOPASSWD: /path/to/epcap/priv/epcap
# And if requiretty is enabled, disable it by using one of these
Defaults!/path/to/epcap/priv/epcap !requiretty
Defaults:youruser !requiretty

rebar3 shell

% Start the sniffer process
sniff:start_link().

% Use your interface, or leave it out and trust in pcap
sniff:start([{interface, "eth0"}]).

% To change the filter
sniff:start([{filter, "icmp or (tcp and port 80)"},{interface, "eth0"}]).

% To stop sniffing
sniff:stop().

USAGE

epcap:start() -> {ok, pid()}
epcap:start(Args) -> {ok, pid()}
epcap:start_link() -> {ok, pid()}
epcap:start_link(Args) -> {ok, pid()}

    Types   Args = [Options]
            Options = {chroot, string()} | {group, string()} | {interface, string()} | {promiscuous, boolean()} |
                        {user, string()} | {filter, string()} | {progname, string()} | {file, string()} |
                        {monitor, boolean()} | {cpu_affinity, string()} | {cluster_id, non_neg_integer()}} |
                        {inject, boolean()} | {snaplen, non_neg_integer} | {buffer, non_neg_integer()} |
                        {time_unit, microsecond | timestamp} | {direction, in | out | inout} |
                        {timeout, pos_integer() | infinity | immediate},
                        {env, string()}

    Packets are delivered as messages:

        {packet, DataLinkType, Time, Length, Packet}

    The DataLinkType is an integer representing the link layer,
    e.g., ethernet, Linux cooked socket.

    The Time can be either in microseconds or a timestamp in the same
    format as erlang:now/0 depending on the value of the time_unit
    option (default: timestamp):

    {MegaSecs, Secs, MicroSecs}

    The Length corresponds to the actual packet length on the
    wire. The captured packet may have been truncated. To get the
    captured packet length, use byte_size(Packet).

    The Packet is a binary holding the captured data.

    If the version of the pcap library supports it, the pcap buffer
    size can be set to avoid dropped packets by using the 'buffer'
    option. The buffer size must be larger than the snapshot
    length (default: 65535) plus some overhead for the pcap data
    structures. Using some multiple of the snapshot length is
    suggested. The timeout used when appending subsequent packets
    to the buffer can be controlled by the 'timeout' option on some
    platforms (value in msecs), the special values 'infinity' (wait
    until the pcap buffer is filled) and 'immediate' (do not wait
    after the first packet). The value 0 is equivalent to
    'immediate' which differs from the definition given in pcap(3PCAP).

epcap:send(Ref, Packet) -> ok

    Types   Ref = pid()
            Packet = binary()

    Inject a packet on the network interface. To enable sending
    packets, start_link/1 must be called with the {inject, true} option
    (default: {inject, false}). When disabled, any data sent
    to the epcap port is silently discarded.

    Packet injection failures are treated as fatal errors, terminating
    the epcap port. Partial writes are not considered to be errors
    and are ignored (an error message will be printed to stderr if
    the verbose option is used).

PF_RING

    In case you want to compile epcap with PF_RING support,
    just specify the path to the libpfring and modified libpcap libraries
    via shell variable PFRING.

        PFRING=/home/user/pfring make

    To complete the configuration you need to set up the cluster_id option.
    The value of the cluster_id option is integer and should be in range between 0 and 255.

        epcap:start_link([{interface, "lo"}, {cluster_id, 2}]).

    You can also specify the option cpu_affinity to set up CPU affinity for epcap port:

        epcap:start_link([{interface, "lo"}, {cluster_id, 2}, {cpu_affinity, "1,3,5-7"}]).

PROCESS RESTRICTION

Setting the RESTRICT_PROCESS environment variable controls which mode of process restriction is used. The available modes are:

  • seccomp: linux

  • pledge: openbsd (default)

  • capsicum: freebsd (default)

  • rlimit: all (default: linux)

  • null: all

For example, to force using the seccomp process restriction on linux:

RESTRICT_PROCESS=rlimit rebar3 do clean, compile

The null mode disables process restrictions and can be used for debugging.

RESTRICT_PROCESS=null rebar3 do clean, compile

epcap:start([{exec, "sudo strace -f -s 4096 -o rlimit.trace"}, {filter, "port 9997"}]).

RESTRICT_PROCESS=seccomp make clean all

epcap:start([{exec, "sudo strace -f -s 4096 -o seccomp.trace"}, {filter, "port 9997"}]).

SCREENSHOT

=INFO REPORT==== 27-Oct-2013::11:47:43 ===
    pcap: [{time,"2013-10-27 11:47:43"},
           {caplen,653},
           {len,653},
           {datalink,en10mb}]
    ether: [{source_macaddr,"F0:BD:4F:AA:BB:CC"},
            {destination_macaddr,"B3:4B:19:00:11:22"}]
    ipv6: [{protocol,tcp},
           {source_address,"2607:F8B0:400B:80B::1000"},
           {destination_address,"2002:26F:92:AE::123"}]
    tcp: [{source_port,80},
          {destination_port,47980},
          {flags,[ack,psh]},
          {seq,686139900},
          {ack,725208397},
          {win,224}]
    payload_size: 567
    payload: "HTTP/1.0 301 Moved Permanently..Location: http://www.google.ca/..Content-Type: text/html; charset=UTF-8..Date: Sun, 27 Oct 2013 15:47:49 GMT..Expires: Tue, 26 Nov 2013 15:47:49 GMT..Cache-Control: public, max-age=2592000..Server: gws..Content-Length: 218..X-XSS-Protection: 1; mode=block..X-Frame-Options: SAMEORIGIN..Alternate-Protocol: 80:quic....<HTML><HEAD><meta http-equiv=\"content-type\" content=\"text/html;charset=utf-8\">.<TITLE>301 Moved</TITLE></HEAD><BODY>.<H1>301 Moved</H1>.The document has moved.<A HREF=\"http://www.google.ca/\">here</A>...</BODY></HTML>.." 

And a screenshot of the number of packets epcap is processing on a production system:

IPTraf Screenshot

TODO

  • return error atoms/tuples instead of using errx

  • add support for retrieving packet statistics using pcap_stats(3PCAP)

More Repositories

1

procket

Erlang interface to low level socket operations
C
285
star
2

pkt

Erlang network protocol library
Erlang
151
star
3

gen_icmp

Erlang interface to ICMP sockets
Erlang
100
star
4

evum

["Linux VM", ["Erlang Process", ["Erlang VM"]]].
Erlang
87
star
5

tunctl

Erlang TUN/TAP interface
Erlang
77
star
6

sods

Socket over DNS tunnel
C
69
star
7

verx

Erlang implementation of the libvirtd remote protocol
Erlang
60
star
8

srly

Native Erlang Unix serial interface
Erlang
57
star
9

alcove

Control plane for system processes
C
48
star
10

prx

an Erlang library for interacting with Unix processes
Erlang
36
star
11

erlang-libvirt

Erlang binding to libvirt virtualization API
Erlang
36
star
12

libkeepalive

LD_PRELOAD library for enabling TCP keepalive socket options
C
34
star
13

emdns

Erlang multicast DNS and DNS-SD (DNS Service Discovery)
Erlang
33
star
14

ewpcap

Portable native Erlang raw socket interface using pcap
Erlang
33
star
15

gen_unix

Erlang Unix socket interface
Erlang
30
star
16

wierl

Erlang interface for manipulating 802.11 wireless devices
Erlang
24
star
17

libproxyproto

Proxy protocol v1 and v2 support via an LD_PRELOAD library
C
23
star
18

xmppipe

stdio over XMPP
C
23
star
19

erlxc

Simple, safe erlang interface for managing Linux Containers
Erlang
22
star
20

stk500

Enough of the STK500 protocol in Erlang to control the Arduino boot loader
Erlang
21
star
21

inert

An Erlang library for notification of events on file descriptors
Erlang
20
star
22

seds

Erlang socket over DNS tunnel server
Erlang
19
star
23

perc

Erlang interface for controlling Unix processes
Erlang
16
star
24

epcap_compile

Compile pcap-filter(7) expressions to BPF programs
Erlang
15
star
25

reuseport

SO_REUSEPORT socket load distribution using LD_PRELOAD
C
15
star
26

spoofed

Spoof the Erlang Distribution Protocol!
Erlang
14
star
27

herp

Erlang user space bridge
Erlang
14
star
28

execve

Go package for fexecve(3) and execveat(2)
Go
13
star
29

islet

Simple, safe isolation using Erlang
Erlang
13
star
30

erpcgen

RPC/XDR protocol compiler (from jungerl)
Erlang
13
star
31

tuntap

Erlang "Universal TUN/TAP device" driver from Jungerl
C
12
star
32

crypt

Erlang NIF wrapping Unix crypt(3)
Erlang
12
star
33

sut

Six (IPv6 in IPv4) Userlspace Tunnel
Erlang
11
star
34

erlang-notify-osd

Erlang NIF interface for sending desktop notifications
Erlang
11
star
35

farp

Poison the ARPs, courtesy of Erlang
Erlang
10
star
36

perv

Media captured from the ether for your viewing pleasure
Erlang
9
star
37

runcron

simple, safe, container-friendly cron alternative
C
8
star
38

cerck

Password quality checks for Erlang
Erlang
8
star
39

spood

The spoofing DNS proxy with a vaguely obscene name
Erlang
8
star
40

totp.c

simple, standalone TOTP without dependencies
C
7
star
41

drench

Makes things go ... down
C
7
star
42

libenospace

Process-based disk usage limits
C
7
star
43

sredird

RFC 2217 network serial port redirector
C
6
star
44

everl

Async socket notifications for Erlang using libev
C
6
star
45

runlet

Event stream query and flow control
Elixir
6
star
46

ampule

An elixir library for linux containers
Elixir
6
star
47

trep

Selectively stream stdin to stdout/stderr based on regular expressions
C
5
star
48

librlimit

rlimit sandbox for any process
C
5
star
49

rst

Think of it as peer to peer QoS
C
5
star
50

cm17a

Erlang X10 Firecracker (CM17A) Interface
Erlang
4
star
51

wat

A simple example of an Erlang NIF for creating mutable variables
C
4
star
52

embedexe

Run an executable embedded in a Go binary
Go
4
star
53

pseudocron

sleep(1) using a cron expression
C
3
star
54

libsockfilter

Connection filtering for dynamically linked applications
C
3
star
55

stdio

Reliably reap, restrict and isolate system tasks: Stdio is a control plane for processes
Elixir
3
star
56

runlet_sh

Generate runlets from containerized Unix processes
Elixir
3
star
57

wwallo

Tag cloud for your geo location
JavaScript
2
star
58

libnoexec

Prevent dynamically linked executables from calling exec(3)
C
2
star
59

collectd-prv

stdout to collectd notification
C
1
star
60

tscat

Timestamp stdin to stdout/stderr
C
1
star
61

runhash-go

runhash: command line interface for distributed node selection
Go
1
star
62

noprivexec

noprivexec: disable setuid privileges
C
1
star
63

pdeathsigexec

signal process when parent exits
C
1
star
64

tcpexec-rs

tcpexec: a minimal, UCSPI inetd
Rust
1
star
65

unixexec

attach stdin/stdout of a command to a Unix socket
C
1
star
66

pipewatch

pipewatch: supervise pipelines of processes
C
1
star
67

fchmodexec

fchmod(2) inherited file descriptors before exec(3)'ing a command
C
1
star
68

prv

pressure relief valve for Unix process pipelines
C
1
star
69

closefrom

close(2) a range of file descriptors before exec(2)
C
1
star
70

xmppipe-go

stdio over XMPP
Go
1
star
71

runlimit

restart intensity limits for supervised Unix processes
C
1
star
72

tcpexec

tcpexec: a minimal, UCSPI inetd
C
1
star
73

logsurfer-

Rules based log file monitoring and alerting tool
C
1
star
74

imappipe

poll IMAP mailbox to stdout
Go
1
star
75

hexlog

Hexdump stdin and/or stdout to stderr
C
1
star
76

runlock

rate limit command invocation based on the last successful run time
C
1
star
77

eventbot

A bot for generating and interacting with event streams using XMPP
Elixir
1
star
78

goreap

User init to supervise and terminate subprocesses
Go
1
star
79

dnsup

Publish an IP address using the Cloudflare API
Go
1
star
80

genlb-ptrace

connect(2) load balancer for Unix processes
C
1
star
81

runlet_net

Miscellaneous network related commands for runlets
Erlang
1
star
82

rotatee

tee(1) with file rotation
Go
1
star