3 # © Copyright 2021-2022, Scott Gasch
5 """A caching layer around the kernel's network mapping between IPs and MACs"""
12 from typing import Any, Optional
14 from overrides import overrides
23 from collect.bidict import BiDict
25 logger = logging.getLogger(__name__)
27 cfg = config.add_commandline_args(
28 f'MAC <--> IP Address mapping table cache ({__file__})',
29 'Commandline args related to MAC <--> IP Address mapping',
32 '--arper_cache_location',
33 default=site_config.get_config().arper_cache_file,
35 help='Where to cache the kernel ARP table',
38 '--arper_supplimental_cache_location',
39 default=site_config.get_config(site_config.other_location()).arper_cache_file,
41 help='Where someone else is caching the kernel ARP table',
44 '--arper_cache_max_staleness',
45 type=argparse_utils.valid_duration,
46 default=datetime.timedelta(seconds=60 * 30),
48 help='Max acceptable age of the kernel arp table cache',
51 '--arper_min_entries_to_be_valid',
53 default=site_config.get_config().arper_minimum_device_count,
54 help='Min number of arp entries to bother persisting.',
58 @persistent.persistent_autoloaded_singleton() # type: ignore
59 class Arper(persistent.Persistent):
60 """A caching layer around the kernel's network mapping between IPs and
61 MACs. This class restores persisted state that expires
62 periodically (see --arper_cache_max_staleness) at program startup
63 time. If it's unable to use the file's contents, it queries the
64 kernel (via arp) and uses an auxillary utility called arp-scan to
65 query the network. If it has to do this there's a latency hit but
66 it persists the collected data in the cache file. Either way, the
67 class behaves as a global singleton hosting this data thereafter.
73 cached_local_state: Optional[BiDict] = None,
74 cached_supplimental_state: Optional[BiDict] = None,
77 if cached_local_state is not None:
78 logger.debug('Loading Arper map from cached local state.')
79 self.state = cached_local_state
81 logger.debug('No usable cached state; calling /usr/sbin/arp')
82 self.update_from_arp_scan()
83 self.update_from_arp()
84 if len(self.state) < config.config['arper_min_entries_to_be_valid']:
85 raise Exception(f'Arper didn\'t find enough entries; only got {len(self.state)}.')
86 if cached_supplimental_state is not None:
87 logger.debug('Also added %d supplimental entries.', len(cached_supplimental_state))
88 for mac, ip in cached_supplimental_state.items():
90 for mac, ip in self.state.items():
91 logger.debug('%s <-> %s', mac, ip)
93 def update_from_arp_scan(self):
94 network_spec = site_config.get_config().network
96 output = exec_utils.cmd(
97 f'/usr/local/bin/arp-scan --retry=6 --timeout 350 --backoff=1.4 --random --numeric --plain --ignoredups {network_spec}',
100 except Exception as e:
103 for line in output.split('\n'):
104 ip = string_utils.extract_ip_v4(line)
105 mac = string_utils.extract_mac_address(line)
106 if ip is not None and mac is not None and mac != 'UNKNOWN' and ip != 'UNKNOWN':
108 logger.debug('ARPER: %s => %s', mac, ip)
111 def update_from_arp(self):
113 output = exec_utils.cmd('/usr/sbin/arp -a', timeout_seconds=10.0)
114 except Exception as e:
117 for line in output.split('\n'):
118 ip = string_utils.extract_ip_v4(line)
119 mac = string_utils.extract_mac_address(line)
120 if ip is not None and mac is not None and mac != 'UNKNOWN' and ip != 'UNKNOWN':
122 logger.debug('ARPER: %s => %s', mac, ip)
125 def get_ip_by_mac(self, mac: str) -> Optional[str]:
127 return self.state.get(mac, None)
129 def get_mac_by_ip(self, ip: str) -> Optional[str]:
130 return self.state.inverse.get(ip, None)
136 freshness_threshold_sec: int,
139 if not file_utils.file_is_readable(cache_file):
140 logger.debug('Can\'t read %s', cache_file)
142 if persistent.was_file_written_within_n_seconds(
144 freshness_threshold_sec,
146 logger.debug('Loading state from %s', cache_file)
148 with open(cache_file, 'r') as rf:
149 contents = rf.readlines()
150 for line in contents:
152 logger.debug('ARPER:%s> %s', cache_file, line)
153 (mac, ip) = line.split(',')
160 logger.debug('%s is too stale.', cache_file)
164 def load(cls) -> Any:
165 local_state: BiDict = BiDict()
166 cache_file = config.config['arper_cache_location']
167 max_staleness = config.config['arper_cache_max_staleness'].total_seconds()
168 logger.debug('Trying to load main arper cache from %s...', cache_file)
169 cls.load_state(cache_file, max_staleness, local_state)
170 if len(local_state) <= config.config['arper_min_entries_to_be_valid']:
171 msg = f'{cache_file} is invalid: only {len(local_state)} entries. Deleting it.'
173 warnings.warn(msg, stacklevel=2)
175 os.remove(cache_file)
179 supplimental_state: BiDict = BiDict()
180 cache_file = config.config['arper_supplimental_cache_location']
181 max_staleness = config.config['arper_cache_max_staleness'].total_seconds()
182 logger.debug('Trying to suppliment arper state from %s', cache_file)
183 cls.load_state(cache_file, max_staleness, supplimental_state)
184 if len(local_state) > 0:
185 return cls(local_state, supplimental_state)
189 def save(self) -> bool:
190 if len(self.state) > config.config['arper_min_entries_to_be_valid']:
191 logger.debug('Persisting state to %s', config.config["arper_cache_location"])
192 with file_utils.FileWriter(config.config['arper_cache_location']) as wf:
193 for (mac, ip) in self.state.items():
195 print(f'{mac}, {ip}', file=wf)
199 'Only saw %d entries; needed at least %d to bother persisting.',
201 config.config["arper_min_entries_to_be_valid"],