1GETMAC(1)                           getmac                           GETMAC(1)
2
3
4

NAME

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
10       Get  the  MAC address of remote LAN hosts and system network interfaces
11       using Python.
12
13       It provides a platform-independant interface to get the  MAC  addresses
14       of:
15
16       • System network interfaces (by interface name)
17
18       • Remote hosts on the local network (by IPv4/IPv6 address or hostname)
19
20       It provides one function: get_mac_address()
21
22       asciicast
23
24       asciicast
25
26       • Pure-Python
27
28       • Supports Python 2.6+, 3.4+, pypy, and pypy3
29
30       • No dependencies
31
32       • Small size
33
34       • Can be used as an independent .py file
35
36       • Simple terminal tool (when installed as a package)
37

PYTHON EXAMPLES

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
47          # Enabling debugging
48          from getmac import getmac
49          getmac.DEBUG = 2  # DEBUG level 2
50          print(getmac.get_mac_address(interface="Ethernet 3"))
51
52          # 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
57

TERMINAL EXAMPLES

59          getmac --help
60          getmac --version
61
62          # No arguments will return MAC of the default interface.
63          getmac
64          python -m getmac
65
66          # 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
72          # 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
78          # 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
87          # 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
92
93       Note:  the  terminal  interface  will  not work on Python 2.6 and older
94       (Sorry RHEL 6 users!).
95

GET_MAC_ADDRESS()

97interface: Name of a network interface on the system.
98
99ip: IPv4 address of a remote host.
100
101ip6: IPv6 address of a remote host.
102
103hostname: Hostname of a remote host.
104
105network_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

NOTES

116       • If none of the arguments are selected, the default network  interface
117         for the system will be used.
118
119       • "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
126       • 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
130       • 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
135       • 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
140       • 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

DOCKER EXAMPLES

147       Run getmac container and provide flags
148
149          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
153
154       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
158          docker build . -t getmac
159
160
161       • Windows
162
163         • Commands: getmac, ipconfig
164
165         • Libraries: uuid, ctypes
166
167         • Third-party Packages: netifaces, psutil, scapy
168
169       • Linux/Unix
170
171         • Commands: arp, ip, ifconfig, netstat, ip link
172
173         • Libraries: uuid, fcntl
174
175         • Third-party Packages:  netifaces, psutil, scapy, arping
176
177         • Default interfaces: route, ip route list
178
179         • Files: /sys/class/net/X/address, /proc/net/arp
180
181       • Mac OSX (Darwin)
182
183networksetup
184
185         • Same commands as Linux
186
187       • WSL: Windows commands are used for remote hosts,  and  Unix  commands
188         are used for interfaces
189
190       All or almost all features should work on "supported" platforms (OSes).
191
192       • Windows
193
194         • Desktop: 7, 8, 8.1, 10
195
196         • Server: TBD
197
198         • (Partially supported, untested): 2000, XP, Vista
199
200       • Linux distros
201
202         • CentOS/RHEL 6+
203
204         • Ubuntu 16+ (14 and older should work as well)
205
206         • Fedora
207
208       • MacOSX (Darwin)
209
210         • The latest two versions probably (TBD)
211
212       • Windows Subsystem for Linux (WSL)
213
214       • Docker
215
216       All  sub-versions  are  the latest available on your platform (with the
217       exception of 2.6).
218
219       • 2.6.6 (CentOS 6/RHEL 6 version)
220
221       • 2.7
222
223       • 3.4
224
225       • 3.5
226
227       • 3.6
228
229       • 3.7
230
231       Please report any problems by opening a issue on GitHub!
232

CAVEATS

234       • Depending on the platform, there could be  a  performance  detriment,
235         due to heavy usage of regular expressions.
236
237       • 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
241       • 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

KNOWN ISSUES

247       • Hostnames for IPv6 devices are not yet supported.
248
249       • 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
253       • 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
257       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
260       Before  submitting a PR, please make sure you've completed the pull re‐
261       quest checklist!
262
263       The Python Discord server is a good place to ask questions  or  discuss
264       the project (Handle: @KnownError).
265

CONTRIBUTORS

267       • Christopher Goes (@ghostofgoes) - Author and maintainer
268
269       • Calvin Tran (@cyberhobbes) - Windows interface detection improvements
270
271       • Izra Faturrahman (@Frizz925) - Unit tests using the platform samples
272
273       • Jose Gonzalez (@Komish) - Docker container and Docker testing
274
275       • @fortunate-man - Awesome usage videos
276
277       • @martmists - legacy Python compatibility improvements
278
279       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
282https://github.com/python/cpython/blob/master/Lib/uuid.py
283
284https://github.com/python/cpython/blob/2.7/Lib/uuid.py
285

OTHER NOTABLE SOURCES

287_unix_fcntl_by_interface
288
289_windows_get_remote_mac_ctypes
290
291String joining
292
293       MIT. Feel free to copy, modify, and use to your heart's content.  Enjoy
294       :)
295

AUTHOR

297       Christopher Goes
298
300       2018, Christopher Goes
301
302
303
304
3050.6.0                            Oct 06, 2018                        GETMAC(1)
Impressum