ARPALERT(8)

✨ NAME ✨

arpalert — ARP traffic monitoring, bestie. That's the whole thing. 💖

---

🌸 DESCRIPTION 🌸

okay so picture this: arpalert uses ARP protocol monitoring to stop unauthorized connections from popping up on the local network. And if it does catch an illegal connection? It can launch a program or a script, which you could totally use to send an alert message, for example. It's giving security guard but make it iconic. 👑

---

💅 COMMAND LINE 💅

• -f config_file — specify the config file. 📁
• -i interface — comma separated network interfaces to listen to.
• -p pid_file — use this pid file. This file contains a pid number of the arpalert session. If the file exists and it's locked, the daemon does not run. 🔒
• -e exec_script — script that gets launched when an alert is sent.
• -D log_level — the level logged. Levels run between 0 (emergency) and 7 (debug). If 3 is selected, all levels between 0 and 3 are logged.
• -l leases_file — this file contains a dump of the mac address in memory (check the config file for that one).
• -m module file — specify a module file to load.
• -d — run as daemon. 😴
• -F — run in foreground.
• -v — watch on screen all the options selected (the options specified in the config file and the default options). 👀
• -h — the help command line.
• -w — debug option: print a dump of packets 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 holds 3 types of data: integer, string and boolean. And the boolean type? It can take the values 'oui', 'true', 'yes', '1' for the true values, or 'non', 'no', 'false', '0' for the false values. Choose your fighter. 💅

• user = arpalert — use privileges separation with this user.
• umask = 177 — uses this umask for file creation.
• chroot dir = /home/thierry/arp_test/ — use this directory for program jail.
  • If this option is commented out, the program does not use chroot.
  • The program reads the config file and opens the syslog socket before the chroot.
  • The kill -HUP does not work with chroot.
  • If the syslog program is restarted, the socket changes and the arpalert syslog system can't be connected to the new socket: the logs with syslog are disabled. Prefer to use the log file. 😭
  • The file paths are relative to the chroot dir (except the config file).
• log file = /var/log/arpalert.log — the program logs into this file.
  • If this option is commented out, the internal system log is not used.
  • The internal system logs can be used at the same time as syslog.
• log level = 6 — the level logged. The levels are between 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 file.
• dump inter = 5 — minimum time to wait between two leases dump.
• auth request file = /etc/arpalert/authrq.conf — list of authorized request.
• lock file = /var/run/arpalert.pid — pid file.
• dump packet = false — only for debugging: this dumps packets received on standard output. The syntax "dump paquet" is also available, but is deprecated. ⚠️
• daemon = false — if it's set to true, run the program as daemon.
• interface = "" — comma separated network interfaces leisten to. If this value is not specified, the soft selects the first interface.
• catch only arp = TRUE — configure the network to catch only arp request. The detection type "new_mac" is deactivated. 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 avoids a costly fork/exec.
• mod config = "" — this chain is transferred to the init function of the module loaded.
• action on detect = "" — script launched on each detection. Parameters are:
  • mac address of requestor,
  • ip of requestor,
  • supp. parm.,
  • ethernet device listening on,
  • type of alert,
  • optional: ethernet vendor

type of alert:

1. 0: IP change
2. 1: Mac address already detected but not in white list
3. 2: Mac address in black list
4. 3: New mac address
5. 4: Unauthorized arp request
6. 5: Abusive number of arp request detected
7. 6: Ethernet mac address different from arp mac address
8. 7: Flood detected
9. 8: New mac address without 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 address 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 sends only one mismatch alert in this time (in seconds).
• anti flood global = 50 — if the number of arp request in seconds exceeds this value, all alerts are ignored for "anti flood interval" time.
• mac vendor file = "" — this file contains 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 address 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 address is in black list.
• log new address, alert on new address, mod on new address = true — log/launch script/call module if the address isn't referenced.
• log mac change, alert on mac change, mod on mac change = true — log/launch script/call module if the mac address is different from the last arp request with the same ip address.
• log ip change, alert on ip change, mod on ip change = true — log/launch script/call module if the ip address is different from the last arp request with the same mac address.
• log unauth request, alert on unauth request, mod on unauth request = true — unauthorized arp request: launch if the request is not authorized in auth file.
• ignore unknown sender = true — don't analyse arp request for unknown 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 addresse of the listing interfaces for the authorizations checks.
• unauth ignore time method = 2 — select suspend time method:
  1. 1: ignore all unauth alerts during "anti flood interval" time
  2. 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 is different than the arp mac 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.
• log expire mac address = true, alert on expire mac address = true, mod on expire mac address = true — log/launch script/call module if the ethernet mac address expire.
• expire authorized mac addresses = true — allow authorized mac addresses to expire.

---

🦋 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 abuse for this mac address
• mac_error: Ignore mac error for this mac address
• mac_change: Ignore mac change for this mac address
• mac_expire: Never expire this mac address. Useful if the option "expire authorized mac addresses" is used

/etc/arpalert/authrq.conf:

• All the words after # character are ignored
• All the blank characters are ignored
• The authorisations list for one mac address begins by the mac address into brackets
• All the next values are ip hosts addresses or ip networks addresses (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

---

and that's the whole page, bestie!! this one is from the arp traffic monitoring era, dated 2006-05-09 — vintage but still serving. go secure your network, ily 🫶💜