1GETMAC(1) getmac GETMAC(1)
2
6 getmac - Cross-platform Python package to get MAC addresses Latest ver‐
7 sion on PyPI Documentation status Travis CI build status Appveyor build
8 status
9 Get the MAC address of remote LAN hosts and system network interfaces
11 using Python.
12 It provides a platform-independant interface to get the MAC addresses
14 of:
15 • System network interfaces (by interface name)
17 • Remote hosts on the local network (by IPv4/IPv6 address or hostname)
19 It provides one function: get_mac_address()
21 asciicast
23 asciicast
25 • Pure-Python
27 • Supports Python 2.6+, 3.4+, pypy, and pypy3
29 • No dependencies
31 • Small size
33 • Can be used as an independent .py file
35 • Simple terminal tool (when installed as a package)
37
39 from getmac import get_mac_address
40 eth_mac = get_mac_address(interface="eth0")
41 win_mac = get_mac_address(interface="Ethernet 3")
42 ip_mac = get_mac_address(ip="192.168.0.1")
43 ip6_mac = get_mac_address(ip6="::1")
44 host_mac = get_mac_address(hostname="localhost")
45 updated_mac = get_mac_address(ip="10.0.0.1", network_request=True)
46 # Enabling debugging
48 from getmac import getmac
49 getmac.DEBUG = 2 # DEBUG level 2
50 print(getmac.get_mac_address(interface="Ethernet 3"))
51 # Changing the port used for updating ARP table (UDP packet)
53 from getmac import getmac
54 getmac.PORT = 44444 # Default: 55555
55 print(get_mac_address(ip="192.168.0.1", network_request=True))
56
59 getmac --help
60 getmac --version
61 # No arguments will return MAC of the default interface.
63 getmac
64 python -m getmac
65 # Interface names, IPv4/IPv6 addresses, or Hostnames can be specified
67 getmac --interface ens33
68 getmac --ip 192.168.0.1
69 getmac --ip6 ::1
70 getmac --hostname home.router
71 # Running as a Python module with shorthands for the arguments
73 python -m getmac -i 'Ethernet 4'
74 python -m getmac -4 192.168.0.1
75 python -m getmac -6 ::1
76 python -m getmac -n home.router
77 # Getting the MAC address of a remote host obviously requires
79 # the ARP table to be populated. By default, getmac will do
80 # this for you by sending a small UDP packet to a high port (55555)
81 # If you don't want this to happen, you can disable it.
82 # This is useful if you're 100% certain the ARP table will be
83 # populated already, or in red team/forensic scenarios.
84 getmac --no-network-request -4 192.168.0.1
85 python -m getmac --no-network-request -n home.router
86 # Debug levels can be specified with '-d'
88 getmac --debug
89 python -m getmac -d -i enp11s4
90 python -m getmac -dd -n home.router
91 Note: the terminal interface will not work on Python 2.6 and older
94 (Sorry RHEL 6 users!).
95
97 • interface: Name of a network interface on the system.
98 • ip: IPv4 address of a remote host.
100 • ip6: IPv6 address of a remote host.
102 • hostname: Hostname of a remote host.
104 • network_request: If an network request should be made to update and
106 populate the ARP/NDP table of remote hosts used to lookup MACs in
107 most circumstances. Disable this if you want to just use what's al‐
108 ready in the table, or if you have requirements to prevent network
109 traffic. The network request is a empty UDP packet sent to a high
110 port, 55555 by default. This can be changed by setting getmac.PORT to
111 the desired integer value. Additionally, on Windows, this will send a
112 UDP packet to 1.1.1.1:53 to attempt to determine the default inter‐
113 face.
114
116 • If none of the arguments are selected, the default network interface
117 for the system will be used.
118 • "Remote hosts" refer to hosts in your local layer 2 network, also
120 commonly referred to as a "broadcast domain", "LAN", or "VLAN". As
121 far as I know, there is not a reliable method to get a MAC address
122 for a remote host external to the LAN. If you know any methods other‐
123 wise, please open a GitHub issue or shoot me an email, I'd love to be
124 wrong about this.
125 • The first four arguments are mutually exclusive. network_request does
127 not have any functionality when the interface argument is specified,
128 and can be safely set if using in a script.
129 • The physical transport is assumed to be Ethernet (802.3). Others,
131 such as Wi-Fi (802.11), are currently not tested or considored. I
132 plan to address this in the future, and am definitely open to pull
133 requests or issues related to this, including error reports.
134 • Exceptions will be handled silently and returned as a None. If you
136 run into problems, you can set DEBUG to true and get more information
137 about what's happening. If you're still having issues, please create
138 an issue on GitHub and include the output with DEBUG enabled.
139 • Messages are output using the warnings module, and print() if get‐
141 mac.DEBUG enabled (any value greater than 0). If you are using log‐
142 ging, they can be captured using logging.captureWarnings(). Other‐
143 wise, they can be suppressed using warnings.filterwarnings("ignore").
144 https://docs.python.org/3/library/warnings.html
145
147 Run getmac container and provide flags
148 docker run -it ghostofgoes/getmac:latest --help
150 docker run -it ghostofgoes/getmac:latest --version
151 docker run -it ghostofgoes/getmac:latest -n localhost
152 There is a pre-built container located on the Docker hub. Alterna‐
155 tively, you can build the image yourself (from the repository root di‐
156 rectory):
157 docker build . -t getmac
159 • Windows
162 • Commands: getmac, ipconfig
164 • Libraries: uuid, ctypes
166 • Third-party Packages: netifaces, psutil, scapy
168 • Linux/Unix
170 • Commands: arp, ip, ifconfig, netstat, ip link
172 • Libraries: uuid, fcntl
174 • Third-party Packages: netifaces, psutil, scapy, arping
176 • Default interfaces: route, ip route list
178 • Files: /sys/class/net/X/address, /proc/net/arp
180 • Mac OSX (Darwin)
182 • networksetup
184 • Same commands as Linux
186 • WSL: Windows commands are used for remote hosts, and Unix commands
188 are used for interfaces
189 All or almost all features should work on "supported" platforms (OSes).
191 • Windows
193 • Desktop: 7, 8, 8.1, 10
195 • Server: TBD
197 • (Partially supported, untested): 2000, XP, Vista
199 • Linux distros
201 • CentOS/RHEL 6+
203 • Ubuntu 16+ (14 and older should work as well)
205 • Fedora
207 • MacOSX (Darwin)
209 • The latest two versions probably (TBD)
211 • Windows Subsystem for Linux (WSL)
213 • Docker
215 All sub-versions are the latest available on your platform (with the
217 exception of 2.6).
218 • 2.6.6 (CentOS 6/RHEL 6 version)
220 • 2.7
222 • 3.4
224 • 3.5
226 • 3.6
228 • 3.7
230 Please report any problems by opening a issue on GitHub!
232
234 • Depending on the platform, there could be a performance detriment,
235 due to heavy usage of regular expressions.
236 • Platform test coverage is imperfect. If you're having issues, then
238 you might be using a platform I haven't been able to test. Keep
239 calm, open a GitHub issue, and I'd be more than happy to help.
240 • Older Python versions (2.5/3.3 and older) are not officially sup‐
242 ported. If you're running these, all is not lost! Simply copy/paste
243 getmac.py into your codebase and make the necessary edits to be com‐
244 patible with your version and distribution of Python.
245
247 • Hostnames for IPv6 devices are not yet supported.
248 • Windows: the "default" of selecting the default route interface only
250 works effectively if network_request is enabled. Otherwise, Ethernet
251 as the default.
252 • There is are currently no automated tests for Python 2.6, which means
254 there is a much higher potential for regressions. Open an issue if
255 you encounter any.
256 Contributors are more than welcome! See the contribution guide to get
258 started, and checkout the todo list for a full list of tasks and bugs.
259 Before submitting a PR, please make sure you've completed the pull re‐
261 quest checklist!
262 The Python Discord server is a good place to ask questions or discuss
264 the project (Handle: @KnownError).
265
267 • Christopher Goes (@ghostofgoes) - Author and maintainer
268 • Calvin Tran (@cyberhobbes) - Windows interface detection improvements
270 • Izra Faturrahman (@Frizz925) - Unit tests using the platform samples
272 • Jose Gonzalez (@Komish) - Docker container and Docker testing
274 • @fortunate-man - Awesome usage videos
276 • @martmists - legacy Python compatibility improvements
278 Many of the methods used to acquire an address and the core logic
280 framework are attributed to the CPython project's UUID implementation.
281 • https://github.com/python/cpython/blob/master/Lib/uuid.py
283 • https://github.com/python/cpython/blob/2.7/Lib/uuid.py
285
287 • _unix_fcntl_by_interface
288 • _windows_get_remote_mac_ctypes
290 • String joining
292 MIT. Feel free to copy, modify, and use to your heart's content. Enjoy
294 :)
295
297 Christopher Goes
298
300 2018, Christopher Goes
3010.6.0 Oct 06, 2018 GETMAC(1)