A Bash-based defensive network monitoring utility for detecting suspicious changes in the local gateway's ARP mapping.
AADS monitors the relationship between the default gateway IP address and its MAC address. It can detect unexpected gateway MAC changes and suspicious situations where the gateway MAC is also associated with other IP addresses in the local neighbor table.
The project is intended for defensive security education, home laboratories, network monitoring, and authorized environments.
ARP does not provide authentication for IP-to-MAC address mappings.
Because of this, a system on a local IPv4 network can receive forged ARP information and associate a legitimate IP address — such as the default gateway — with an unexpected MAC address.
AADS monitors this relationship and reports suspicious changes.
Normal state
Gateway IP
192.168.1.1
│
▼
aa:bb:cc:dd:ee:ff
Suspicious state
Gateway IP
192.168.1.1
│
▼
66:66:66:66:66:66
▲
│
Unexpected MAC
- Automatic default gateway detection
- Automatic network interface detection
- Gateway MAC monitoring
- Persistent trusted baseline
- Explicit trusted MAC support
- Gateway MAC change detection
- Duplicate gateway MAC detection in the neighbor table
- IPv4 and MAC address validation
- Desktop alerts with
notify-send - Duplicate notification suppression
- Recovery notifications
- Quiet mode
- Continuous monitoring
- Cron-based monitoring
- Separate state for different gateway/interface combinations
- No root privileges required for normal ARP-table inspection
AADS uses two complementary checks.
On the first run, AADS records the current relationship between:
Gateway IP
Network Interface
Gateway MAC
Example:
192.168.1.1 | wlan0 | aa:bb:cc:dd:ee:ff
Future checks compare the current gateway MAC against the stored baseline.
If the mapping changes:
Expected:
aa:bb:cc:dd:ee:ff
Current:
66:66:66:66:66:66
AADS raises an alert.
AADS also examines the IPv4 neighbor table.
If the current gateway MAC is associated with another IP address, the event is marked as suspicious.
Example:
192.168.1.1 66:66:66:66:66:66
192.168.1.77 66:66:66:66:66:66
This can be associated with ARP spoofing.
However, duplicate MAC mappings are treated as a warning rather than definitive proof because technologies such as proxy ARP or unusual network configurations can legitimately produce similar behavior.
AADS/
├── arpDetection.sh
├── run.sh
├── cron.sh
├── cw.txt
└── README.md
Main detection engine.
Responsible for:
- Discovering the default gateway
- Discovering the active network interface
- Reading the Linux neighbor table
- Resolving the gateway MAC address
- Creating and reading gateway baselines
- Comparing current and expected MAC addresses
- Detecting duplicate MAC mappings
- Generating terminal alerts
- Generating optional desktop notifications
Continuous monitoring wrapper.
Runs arpDetection.sh repeatedly at a configurable interval.
Installs or removes a periodic AADS check using the current user's crontab.
AADS is designed for Linux systems.
Required:
- Bash
ipfrom iproute2awksort
Optional:
pingnotify-sendcron
On Debian/Ubuntu systems:
sudo apt update
sudo apt install iproute2 iputils-ping libnotify-bin cronRun a single gateway integrity check:
bash arpDetection.shOn the first run, AADS automatically detects the default gateway and interface and creates a baseline.
Example:
[INFO] Baseline created for 192.168.1.1 on wlan0: aa:bb:cc:dd:ee:ff
[WARN] Verify this MAC independently before treating the baseline as trusted.
Future runs compare the current gateway MAC against that baseline:
[OK] Gateway mapping is unchanged:
192.168.1.1 (wlan0) -> aa:bb:cc:dd:ee:ff
The automatically created baseline is only as trustworthy as the network state at the time it is created.
After the first run, independently verify the legitimate MAC address of your router or gateway.
If you already know the trusted gateway MAC, you can avoid automatic baseline learning entirely:
bash arpDetection.sh \
--gateway 192.168.1.1 \
--trusted-mac aa:bb:cc:dd:ee:ffShow help:
bash arpDetection.sh --helpSpecify a gateway:
bash arpDetection.sh \
--gateway 192.168.1.1Specify an interface:
bash arpDetection.sh \
--interface wlan0Specify both:
bash arpDetection.sh \
--gateway 192.168.1.1 \
--interface wlan0Use a trusted MAC address:
bash arpDetection.sh \
--trusted-mac aa:bb:cc:dd:ee:ffDisable desktop notifications:
bash arpDetection.sh --no-notifySuppress normal status output:
bash arpDetection.sh --quietIf your router is replaced or its legitimate MAC address changes, verify the new address first and then reset the stored baseline:
bash arpDetection.sh --reset-baselineExample:
[OK] Baseline reset:
192.168.1.1 (wlan0) -> 11:22:33:44:55:66
Do not reset the baseline simply because an alert appeared.
Verify that the MAC change is legitimate first.
Use run.sh to repeatedly check the gateway.
Default interval:
bash run.shThe default is:
10 seconds
Use a custom interval:
bash run.sh 5Pass detector options after the interval:
bash run.sh 10 \
--interface wlan0Or use a known trusted gateway MAC:
bash run.sh 10 \
--gateway 192.168.1.1 \
--trusted-mac aa:bb:cc:dd:ee:ffStop the monitor with:
Ctrl+C
AADS can also install a periodic background check.
Install a check every minute:
bash cron.shInstall a check every five minutes:
bash cron.sh --minutes 5Remove the AADS cron entry:
bash cron.sh --removeCron executions disable desktop notifications and write results to:
~/.local/state/aads/aads.log
The installer manages only the cron entry marked as belonging to AADS and leaves unrelated crontab entries untouched.
By default, AADS stores state under:
~/.local/state/aads/
Separate baseline files are created for different gateway/interface combinations.
Example:
baseline_wlan0_192_168_1_1.txt
The stored information contains:
gateway | interface | trusted MAC
AADS also stores a small alert fingerprint next to the baseline.
This prevents the same desktop notification from being generated repeatedly during every monitoring cycle.
If the gateway MAC unexpectedly changes:
[ALERT] Gateway MAC changed.
Gateway: 192.168.1.1
Interface: wlan0
Expected: aa:bb:cc:dd:ee:ff
Current: 66:66:66:66:66:66
If the same suspicious MAC is also associated with another neighbor:
[WARN] The gateway MAC is also associated with other neighbor IP address(es):
- 192.168.1.77
0 Normal state or baseline successfully created/reset
1 Suspicious ARP state detected
2 Configuration or environment error
The exit codes make AADS suitable for use with monitoring scripts and automation.
AADS demonstrates practical knowledge of:
- ARP
- IPv4 networking
- Linux routing
- Linux neighbor tables
- Default gateway discovery
- MAC address validation
- Defensive network monitoring
- Bash scripting
- State management
- Security alerting
- Cron automation
- Network anomaly detection
AADS is a lightweight host-based defensive utility, not a complete network intrusion detection system.
Important limitations include:
- It monitors the local host's view of the ARP/neighbor table.
- The first automatically learned baseline must be independently verified.
- Proxy ARP and unusual network designs can produce duplicate MAC mappings.
- A MAC change is suspicious but should still be investigated before being treated as definitive proof of an attack.
- The project focuses on IPv4/ARP and does not monitor IPv6 Neighbor Discovery.
- A sophisticated attacker may use techniques that cannot be identified by simple neighbor-table monitoring.
For critical environments, AADS should be considered one detection signal among multiple network security controls.
AADS is a defensive monitoring project.
It does not perform ARP poisoning or manipulate network traffic.
The project is intended for:
- Defensive security education
- Personal laboratories
- Authorized network monitoring
- Network security research
- Linux security practice
Cyber Worm
GitHub: @bellurm