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