Arpalert

This software is used for monitoring ethernet networks. It listens on a network interface (without using 'promiscuous' mode) and catches all conversations of MAC address to IP request. It then compares the mac addresses it detected with a pre-configured list of authorized MAC addresses. If the MAC is not in list, arpalert launches a pre-defined user script with the MAC address and IP address as parameters. This software can run in deamon mode; it's very fast (low CPU and memory consumption). It responds at signal SIGHUP (configuration reload) and at signals SIGTERM, SIGINT, SIGQUIT and SIGABRT (arpalert stops itself)

Supported and tested platforms

Linux 2.4 on x86
Solaris 8 on UltraSPARC-IIi
Solaris 10 on x86
FreeBSD 5.4 on x86
OpenBSD 3.7 on x86
NetBSD 3.0 on x86

New branche 2.0: what's new ?

  • version 2.0.11 (stable): (31/03/2008)
    Don't erase configure when make mrproper is calledw
    Update error in man
    minor orthographic correction in doc
  • version 2.0.10 (stable): (28/03/2008)
    bug into leases file reading
    new script in contribs by mikuskuikku
    (found here: http://ubuntuforums.org/showthread.php?t=464883)
    this script send a zenity alert on Ubuntu.
  • version 2.0.9 (stable): (17/11/2007)
    fix an error message
    update script API documentation
    API documentation
    new API functions : mod conf
    set lockfile optional
  • version 2.0.8 (stable): (27/08/2007)
    Install API includes
    close and reopen the logfile on SIGHUP
    change type of ip arg passed to module
    bugfix in module options
  • version 2.0.7 (stable): (03/08/2007)
    minor openbsd bugfix (thanks Andy)
    very minor code optimization
    check string representation of mac adress memory size
    allocate static memory for many buffers
    openbsd Makefile compatibility
  • version 2.0.6 (stable): (07/06/2007)
    default config file syntax correction and comments
    display list of mac vendor loaded only in debug compil mode
    add vim syntax file
    would not require manually editing the script to fix the sender and receiver's email adress.
  • version 2.0.5 (stable): (12/03/2007)
    bugfix in arp selftest detection
    bugfix in scheduler
    code cleanup
  • version 2.0.4 (stable): (05/02/2007)
    segfault when config is dumped
    compilation error on ppc processors (sign error)
  • version 2.0.3 (beta): (24/11/2006)
    man corrections
    arpalert don't quit if the leases file is not found at start. just send an notice.
    variable type correction
    alerts identifiers defined
    alert bug in "reference" field
    put also mac address without ip in leases file
  • version 2.0.2 (beta): (04/11/2006)
    serialization of sigchld signal and sigkill, sighup
    option for force run in foreground
    update man
  • version 2.0.1 (beta): (29/10/2006)
    retrieve mac vendor name
    load leases files and remember the mac already discovered
    port on solaris8 ultrasparc IIi
    reload "white list", "black list", "authorizations" and "oui.txt" when a sighup is received
    generalise use of errno
    code cleaning
    change install system
    generate default config
    scheduler bug in dump leases time
    launch a laeses file dump before quit
  • version 2.0.0 (beta): (16/10/2006)
    permit to listen more than one interface
    port on solaris10
    analyse arp reply (usefull if the arpalert is running on router)
    format of config files updated for use of the ethernet interfaces name
    the option "ignore me" is only used for the "unauth_rq" alerts
    new debug format (like tcpdump trace)
    new core sheduler for more speed
    all internal times in µseconds (in place of seconds)
    change internal storage structurs for more speed
    clean configure.in file
    new defines for more code readability

New branche 1.0: what's new ?

  • version 1.1.3 (stable): (12/10/2006)
    minor bugfix: harmonie of file arpalert.lock
    minor change in arpalert.8
  • version 1.1.2: (12/10/2006)
    bug in config whith "" file notation
  • version 1.1.1: (06/10/2006)
    little bug in syntax of config file
  • version 1.1.0: (05/10/2006)
    new function: permit to listen only ARP traffic (alert new_mac disabled)
    new function: permit to call a .so extension
    normalize code with use "struct in_addr" for the ip address
    normalize code with use "struct ether_header" for the mac address
    normalize code with use "struct arphdr" for decoding ethernet header
    changing hash algoritm for homogeneously reparttion of mac adresses
    normalize macro case
    change test for testing bitfield
    flood alert: remove parameter
    mac change alert: add parameter
    add api for mod alerts
    clean code
  • version 1.0.3: (01/09/2006)
    add option -V to return arpalert version
    syntax updates in man
    change condition order in alert detection routine
    change log syntax for the loading file function
    bug in parsing of config file
    bug in mac change detection
    bug in ip change detection
  • version 1.0.2 (beta): (11/05/2006)
    complete inline help
    minor security fix: changes from sprintf to snprintf in data.c
    minor bugfix in compilation in debug code
    add header at file arpalert.h
    add header at sens_timeouts.c (for mac OS X)
    add copyright informations at file arpalert.h
  • version 1.0.1 (beta): (10/05/2006)
    error in log format for "unknow_address" alert
    error in pid structur initialization
  • version 1.0.0 (beta): (09/05/2006)
    rewrite detection code.
    rewrite data storage code.
    rewrite pid gestion code.
    possibility to write comments in allow / deny files.
    possibility to ignore mac only new detection
    possibility to ignore certains types of detection by mac address (solution for ip alias)
    add new detection function: detect mac change
    add exemple mail alert script.
    add variable in Makefile.
    add suse start script
    add FC4 start script
    add 2 management scripts

Stable version 0.4: what's new ?

  • version 0.4.15-2: (03/11/2006)
    bugfix: bug zombies
    version 0.4.15-1: (01/08/2006)
    bugfix: new mac detection error
    version 0.4.15: (28/11/2005)
    bugfix: probleme in function data_cmp
    rewrite many parts of code.
  • version 0.4.14: (14/11/2005)
    Anti flood system for unauthorized detection by couple mac sender / ip requested. This system permit to watch all alerts.
    Anti flood system only by mac sender is also available.
    Unauthorized request configuration file format change. Now accept the syntax with network mask.
  • version 0.4.13: (01/11/2005)
    command line errors more verbose
    bugfix: Command line bug with -f parameter corrected
  • version 0.4.12: (30/10/2005
    unauthorized request detection: possibility to ignore self request generated by windows dhcp client
    unauthorized request file support comment every where
    when the program is not running in deamon mode, the logs are displayed on standard output
    bugfix: segfault problem in sens_hash
    bugfix: segfault in debug message
    bugfix: error in log function
  • version 0.4.11: (10/10/2005)
    Use priveleges separation
    Use chroot
    Apply mask on files
    Port on openbsd, freebsd, netbsd
  • version 0.4.10: (19/07/2005)
    I write the man
  • version 0.4.9: (19/07/2005)
    Reload the authorized_request list if the SIGHUP is send
  • version 0.4.8: (11/07/2005)
    Don't quit the program with if the link is down ... they're attempt to reconnect
  • version 0.4.7: (10/07/2005)
    Send an alert code 8 if the new mac adress is detected whithout his ip address
  • version 0.4.6: (30/06/2005)
    Launched floods alerts scripts also if the numbers of launched scripts are excedant
    Detect global flood
    Min time from two sames alert (mac source, type of alert)
    Don't alert if the mac adress is the mac of the listening interface
  • version 0.4.5: (26/06/2005)
    Invalid mac address detection based on ethernet header.
    Detection of different address from ethernet header to arp request.
  • version 0.4.4: (16/06/2005)
    Conceptual error in non authorized Arp request detection.
    The requestor are now designed by his mac adress (replace the ip address).
  • version 0.4.3: (09/06/2005)
    A little function in unauthorized request detection: the target 255.255.255.255 permit to ignore a mac adress
  • version 0.4.2: (05/06/2005)
    Detection of non authorized Arp request
  • version 0.4.1: (17/04/2005)
    Patch many bugs (error in set signals)
  • version 0.4.0: (12/04/2005)
    Patch many bugs
    Use white list / black list
    Learn network and stock result in leases file
    More configuration options
    More options in command line
    Translated to english (only logs messages)
    Lesson must than one interface

Stable version 0.3: what's new ?

  • version 0.3.4:
    First stable realease

Compilation / Installation:

The configuration / installation is standard: ./configure && make && make install
The avalaible options for the ./configure are:
  • --with-syslog: Use the SysLog system. (enabled by default)
  • --enable-debug: The logs are more verbose. (disabled by default)
  • --prefix: Installation directory (by default: /opt/arpalert)

Download sources:

Version 2:

  • arpalert-2.0.11    md5sum: 4b2b7682b27c7f260716f59ecfa50ecc
  • arpalert-2.0.10    download avalaible on demand
  • arpalert-2.0.9    download avalaible on demand
  • arpalert-2.0.8    download avalaible on demand
  • arpalert-2.0.7    download avalaible on demand
  • arpalert-2.0.6    download avalaible on demand
  • arpalert-2.0.5    download avalaible on demand
  • arpalert-2.0.4    download avalaible on demand
  • arpalert-2.0.3 (beta)    download avalaible on demand
  • arpalert-2.0.2 (beta)    download avalaible on demand
  • arpalert-2.0.1 (beta)    download avalaible on demand
  • arpalert-2.0.0 (beta)    download avalaible on demand

Version 1:

  • arpalert-1.1.3    download avalaible on demand
  • arpalert-1.1.2    download avalaible on demand
  • arpalert-1.1.1    download avalaible on demand
  • arpalert-1.1.0    download avalaible on demand
  • arpalert-1.0.3    download avalaible on demand
  • arpalert-1.0.2 (beta)    download avalaible on demand
  • arpalert-1.0.1 (beta)    download avalaible on demand
  • arpalert-1.0.0 (beta)    download avalaible on demand

Version 0:

  • arpalert-0.4.15-2    download avalaible on demand
  • arpalert-0.4.15-1    download avalaible on demand
  • arpalert-0.4.15    download avalaible on demand
  • arpalert-0.4.14 << Bugged    download avalaible on demand
  • arpalert-0.4.13    download avalaible on demand
  • arpalert-0.4.12    download avalaible on demand
  • arpalert-0.4.11    download avalaible on demand
  • arpalert-0.4.10    download avalaible on demand
  • arpalert-0.4.9    download avalaible on demand
  • arpalert-0.4.8    download avalaible on demand
  • arpalert-0.4.7    download avalaible on demand
  • arpalert-0.4.6    download avalaible on demand
  • arpalert-0.4.5    download avalaible on demand
  • arpalert-0.4.4    download avalaible on demand
  • arpalert-0.4.3    download avalaible on demand
  • arpalert-0.4.2    download avalaible on demand
  • arpalert-0.4.1    download avalaible on demand
  • arpalert-0.4.0    download avalaible on demand

Version 0.3:

  • arpalert-0.3.4

Packages:

Live distrib:

Various:

MAN ARPALERT

NAME

arpalert - ARP traffic monitoring

DESCRIPTION

Arpalert uses ARP protocol monitoring to prevent unauthorized connections on the local network. If an illegal connection is detected, a program or script is launched, which could be used to send an alert message, for example.

COMMAND LINE

-f config_file
Use this config file

-i interface
Comma separated network interfaces to lesson

-p pid_file
Use this pid file. this file contain a pid number of the arpalert session. if the file exist and his locked, the deamon do not run.

-e exec_script
Script launched when an alert is send

-D log_level
The level logged. the level are bitween 0 (emergency) and 7 (debug). if 3 is selected all levels bitween 0 and 3 arre logged.

-l leases_file
This file contain a dump of the mac address in memory (see config file).

-m module file
Specify a module file to load

-d
Run as daemon

-F
Run in foreground

-v
Watch on screen all the option selected (the options specified in config file and the default options)

-h
The help command line.

-w
Debug option: print a dump of paquets captured.

-P
Set the interface in promiscuous mode (don't set this if only the arp analyse is used)

-V
Print version and quit

CONFIGURATION FILE

The config file contain 3 types of data: integer, string and boolean. The boolean type can take values 'oui', 'true', 'yes', '1' for the true values or 'non', 'no', 'false', '0' for the falses values.
user = arpalert
Use privileges separation whith this user

umask = 177
Uses this mask for the files created

chroot dir = /home/thierry/arp_test/
Use this directory for program jail
If this option is commented the program does not chroot
The program read the config file and open the syslog socket before the chroot:
The kill -HUP does not run with chroot.
If the syslog program is restarted, the socket change and the arpalert syslog system can't be connect to the new socket: the logs with syslog are disabled. Prefere to use the log file.
All the path file are relative to the chroot dir (but not the config file)

log file = /var/log/arpalert.log
The program log into this file
If this option is commented, the internal system log is not used
The internal system logs can be used in same time that syslog.

log level = 6
The level logged. the level are bitween 0 (emergency) and 7 (debug). if 3 is selected all levels between 0 and 3 are logged.

use syslog = true
If this option is false, the syslog system is disabled

maclist file = /etc/arpalert/maclist.allow
white list

maclist alert file = /etc/arpalert/maclist.deny
black list

maclist leases file = /var/lib/arpalert/arpalert.leases
dump fil

dump inter = 5
minimun time to wait between two leases dump

auth request file = /etc/arpalert/authrq.conf
list of authorized request"

lock file = /var/run/arpalert.lock
pid file

dump paquet = false
Only for debugging: this dump paquet received on standard output

daemon = false
if is set to true, run the program as daemon

interface = ""
Comma separated network interfaces to lesson. If this value is not specified, the soft select the first interface.

catch only arp = TRUE
Configure the network for catch only arp request. The detection type "new_mac" is desactived. This mode is used for CPU saving if Arpalert is running on a router

mod on detect = ""
Module file loaded by arpalert. This module is launched on each valid alert. This system permit to avoid a costly fork/exec

mod config = ""
this chain is transfered to the init function of module loaded

action on detect = ""
Script launched on each detection. Parameters are: mac adress of requestor, ip of requestor, supp. parm., type of alert .IP type of alert:
0: IP change
1: Mac address already detected but not in white list
2: Mac address in black list
3: New mac address
4: Unauthorized arp request
5: Abusive number of arp request detected
6: Ethernet mac address different from arp mac address
7: Flood detected
8: New mac address whithout ip address

execution timeout = 10
script execution timeout (seconds)

max alert = 20
maximun simultaneous lanched script

dump black list = false
dump the black listed mac address in leases file

dump white list = false
dump the white listed mac address in leases file

dump new address = true
dump the new mac address in leases file

mac timeout = 259200
after this time a mac adress is removed from memory (seconds) (default 1 month)

max entry = 1000000
after this limit the memory hash is cleaned (protect to arp flood)

anti flood interval = 10
this permit to send only one mismatch alert in this time (in seconds)

anti flood global = 50
if the number of arp request in seconds exceed this value, all alerts are ignored for "anti flood interval" time

mac vendor file = ""
This file contain the association from mac address to vendor name. This file can be downloaded here: http://standards.ieee.org/regauth/oui/oui.txt

log mac vendor = false
log vendor name

alert mac vendor = false
give vendor name to script

mod mac vendor = false
give vendor name to module

log referenced address, alert on referenced address, mod on referenced address = false
log/launch script/call module if the adress is referenced in hash but is not in white list

log deny address, alert on deny address, mod on deny address = true
log/launch script/call module if the mac adress is in black list

log new address, alert on new address, mod on new address = true
log/launch script/call module if the adress isn't referenced

log mac change, alert on mac change, mod on mac change = true
log/launch script/call module if the ip adress id different from the last arp request with the same mac adress

log ip change, alert on ip change, mod on ip change = true
log/launch script/call module if the ip adress id different from the last arp request with the same mac adress

log unauth request, alert on unauth request, mod on unauth request = true
unauthorized arp request: launch if the request are not authorized in auth file

ignore unknown sender = true
dont analyse arp request for unknow hosts (not in white list)

ignore self test = true
Ignore ARP self test generated by windows dhcp for unauthorized request detection

ignore me = true
ignore arp request with mac adresse of the listened interfaces for the authorizations checks

unauth ignore time method = 2
select suspend time method:
1: ignore all unauth alerts during "anti flood interval" time
2: ignore only tuple (mac address, ip address) during "anti flood interval" time

log request abus, alert on request abus, mod on request abus = true
log/launch script/call module if the number of request per seconds are > "max request"

max request = 1000000
maximun request authorized by second

log mac error, alert on mac error, mod on mac error = true
log/launch script/call module if the ethernet mac address are different than the arp amc address (only for requestor)

log flood = true
alert on flood = true mod on flood = true log/launch script/call module if have too many arp request per seconds

DATA FILES FORMATS

/etc/arpalert/maclist.allow and /etc/arpalert/maclist.deny:
all the line with # as a first caracter are ignored
The data on this file take this form
<MAC_ADRESS> <IP_ADDRESS> <DEVICE> [<FLAG> <FLAG> <FLAG> ...]
The available flags are:
ip_change: Ignore ip change alert for this mac address
black_listed: Ignore black list alerts for this mac address
unauth_rq: Ignore unauthorized requests for this mac address
rq_abus: Ignore request abus for this mac address
mac_error: Ignore mac error for this mac address
mac_change: Ignore mac change for this mac address

/etc/arpalert/authrq.conf:
all the word after # caracter are ignored
all the blank characters are ignored
The authorisations list for one mac address begin by the mac address into brackets
All the next values are ip hosts address or ip networks address (with /xx notion)
[<MAC_ADRESS> <DEVICE>] <IP_ADRESS>
<IP_ADRESS>/<BITS>

FILES

sbin/arpalert: binary file
etc/arpalert/arpalert.conf: default config file
var/run/arpalert.pid: pid file
var/state/arpalert.leases: leases file


English howto (corrected by Chris)

You are the administrator of a big LAN for which physical access is difficult to control. You know that viruses and data theft can happen due to external machines that connect to the LAN without authorization. You must to monitor these illegal connections. This is where Arpalert can help you.

Start by downloading the Arpalert archive on the official web site. You must compile the source code because packages are not provided. A simple ./configure --prefix=/usr/local/arpalert && make && make install with root privileges will install the application on your computer. You can specify the install base directory with the parameter --prefix after the ./configure command. By default the base directory is /usr/local/arpalert.

A default config file is located in /usr/local/arpalert/etc/arpalert/arpalert.conf. These defaults parameters are usable in most configurations.

Continuing with root privileges, launch the program with the command /usr/local/arpalert/sbin/arpalert -d. The option -d launches the program in daemon mode. If you always want to run Arpalert in daemon mode, you must to edit config file and replace daemon = false by daemon = true. If you watch the /var/log/messages file, you will see all the machines detected on the network. These machines are recorded in the /usr/local/arpalert/var/lib/arpalert/arpalert.leases file.

When all the local network machines are discovered, copy the file /usr/local/arpalert/var/lib/arpalert/arpalert.leases into the maclist.allow file (cat /usr/local/arpalert/var/lib/arpalert/arpalert.leases > /usr/local/arpalert/etc/arpalert/maclist.allow). Don't hesitate to add new mac addresses to this file. Restart the deamon, and the program will run. Now all the new computers detected are probably intruders and they are logged. You can run Arpalert with a script to alert you by e-mail (for example). Script examples are in the directory "scripts".

French howto

Vous êtes administrateur d'un lan relativement vaste mais aux accès particulièrements incontrolables. Sachant que les contaminations virales et les vols de données viennent le plus souvent de machines etrangères au réseau qui se connectent sans autorisation, il faut impérativement monitorer ces connexions illicites. C'est à ce niveau là qu'intervient ArpAlert.

Commencez par télécharger la dernière révision du programme sur le site officiel. Vous devrez passer par les sources, les différentes formes de packaging ne sont pas gérées. Un traditionel ./configure --prefix=/usr/local/arpalert && make && make install avec les droits root installera l'application sur votre machine. Vous pouvez préciser dans le ./configure l'emplacement du répertoire de base, par défaut celui ci sera /usr/local/arpalert.

Un fichier de configuration par défaut sera placé dans /usr/local/arpalert/etc/arpalert/arpalert.conf. Celui ci est fonctionnel pour la plupart des configurations.

Toujours sous le compte root, démmarrez maintenant le programme par un simple /usr/local/arpalert/sbin/arpalert -d. le -d permettra le lancement en mode daemon. Pour automatiser le mode deamon au démarage editez le fichier de configuration et remplacez la ligne daemon = false par daemon = true. Vous pouvez faire un tail -f /var/log/messages (ou /var/log/syslog selon les distributions) et vous verrez toute les machines de votre réseau détectées. Ces nouvelles machines seront stockées dans le fichier /usr/local/arpalert/var/lib/arpalert/arpalert.leases quelques cat sur ce fichier vous laisserons voir la liste des machines detectées.

Lorsque toutes les machines du réseau local ont été découvertes recopiez le contenu de ce fichier dans le fichier maclist.allow (cat /usr/local/arpalert/var/lib/arpalert/arpalert.leases > /usr/local/arpalert/etc/arpalert/maclist.allow), n'hésitez pas à compléter ce fichier à la main. Redémarrez le démon, l'application fonctionne. À partir de maintenant toutes les nouvelles machines détectées sont des intrus potentiel et un message sera émis dans les logs.

Links and various documentation page

Documentation

In press:

Products using Arpalert

Other solutions:

  • Arpwatch NG

    arpwatch monitors mac adresses on your network and writes them into a file. last know timestamp and change notification is included. use it to monitor for unknown (and as such, likely to be intruder's) mac adresses or somebody messing around with your arp_/dns_tables.
    http://freequaos.host.sk/arpwatch/
  • Darpwatch (Distributed Arpwatch)

    Darpwatch is a solution for monitoring ethernet activity across many different ethernet networks. Darpwatch is based on the original arpwatch source from UCB.
    http://sourceforge.net/projects/darpwatch/
  • XArp

    XARp is a graphical tool to watch the ARP cache of your local computer. It remembers all IP to MAC adress mappings and periodically compares them against new ones. Thus it can detect changes in the mapping of IP to MAC adresses and reports them. XArp 0.1.5 can also detect MACs that are set to the broadcast or a multicast MAC address. Further XArp versions will have more monitoring like 'dublicate MAC', 'is the IP in the subet', 'has the default route changed'.
    http://www.chrismc.de/developing/xarp/
  • arphound

    Arphound is a tools that listens to all traffic on an ethernet network interface, and reports IP/MAC address pair, as well as events such as IP conflict, IP changes, IP addresses with no RDNS, various ARP spoofing, and packets not using the expected gateway. Reporting is done to stdout, to a specified file and/or to syslog.
    http://www.nottale.net/index.php?project=arphound

Various links