How to Update the Nmap OUI Database

Overview

    In a previous blog post, I covered what an OUI is, how to extract them from a MAC address, how the IEEE maintains this information publicly, and that tools like Nmap and Wireshark can perform an OUI lookup.  Today, I want to cover how Nmap does this function, and how we can update this file ourselves using a script I have released to the Secure Ideas Professionally Evil GitHub repository.

Example Scan of Known OUI

    In the previous post, I had mentioned Nmap can do this, but didn’t show an example.  Let’s cover this now by having it perform a ping scan (-sn) as root so it uses ARP to detect hosts.  The ARP scan, by its nature, gets the MAC address of the remote host which Nmap will report.  We will scan a VirtualBox VM which NMAP will report an OUI for correctly.  This allows us to see how this function works when Nmap can perform the OUI lookup.

Example Scan of Unknown OUI

    The example above is nice, but other MAC address OUIs will not show up.  The screenshot below shows another scan against a VirtualBox VM, but this time the MAC address has been spoofed and Nmap isn’t able to perform the lookup on this MAC address.

    While Nmap couldn’t report the OUI for this MAC address, it is registered with the IEEE, and can be found at https://standards-oui.ieee.org/ if we search for the OUI 348518.

How Does Nmap Lookup OUIs

    So the IEEE has information about this OUI from the previous example and Nmap doesn’t.  Why is that?  Well, Nmap doesn’t perform a live lookup on this information, but rather depends on the information being stored locally.  Nmap does a good job decoupling information from the codebase and storing it in flat files instead.  Nmap stores information related to OUI and manufacturers in the file called nmap-mac-prefixes, which will be in the root of Nmap’s directory.  On most Linux systems, such as Kali Linux, that will be under /usr/share/nmap/.

    So what’s the problem with having this file stored locally?  Well, this file can get stale with time.  The Nmap developers do update this file about once a year in the repository, but even if they did there is a chance that if you installed it from a package manager, the package manager will be lagging behind what is in the current Nmap GitHub repository.  Since this is data in a flat text file, we can fix this ourselves pretty easily.  So let’s get hacking on Nmap’s OUI lookup file!

Examining Nmap’s nmap-mac-prefixes File

    Before we begin our approach of making changes, we should review the file and make sure we understand it first.  If we use the Linux command head we can explore the first few lines of this file in Kali Linux.

    The first few lines of the file are comments.  These comments show the file was last updated about a year ago.  There is also a reference to some sort of PERL script to update it, but searching the local file system and the internet doesn’t seem to produce this script for us.  The comments also mention that the data comes from the IEEE, but also includes a few unregistered OUIs as well.

    After the comments we can see a list of entries in a format of the OUI as a six character hex string, followed by the manufacturer's name.  This information matches what is shown in the IEEE OUI website, just in a format that focuses on the OUI and company name while cutting out the physical address of the company.  The data in the flat text file generated by Nmap is more streamlined to be parsed for the purposes Nmap uses.  It should be pretty easy for us to parse the IEEE’s OUI data into this format.

    Nmap also has an entire book about Nmap and there is a section of the book dedicated to this file alone.  The book is available to read for free online and the section about the nmap-mac-prefixes file can be found at https://nmap.org/book/nmap-mac-prefixes.html.  Personally, if you’ve not read the book in full, I highly recommend it.  It’s informative and reads well with some humor to keep it interesting.

Updating the nmap-mac-prefixes File with IEEE OUI Data

    So we know that the IEEE OUI data can be used as a source-of-truth for the latest data on OUIs that have been registered.  But on the other hand, Nmap also throws stuff in there that relates to real-world observations of unregistered OUIs.  These can create conflicts and we need a strategy for how we want to execute updating this file.  The strategy I came up with was to script out the following:

1. Create a backup copy of the nmap-mac-prefixes file
2. Download the IEEE’s OUI file from the internet
3. Open the nmap-mac-prefixes backup file and read it into a memory buffer
4. Parse through the IEEE’s OUI file and grab the “(base 16)” lines and extract the OUI and manufacturer names
5. Check if the OUI exists in the nmap-mac-prefixes buffer and if not append it as a new entry at the end formatted as Nmap expects it
6. Dump the updated nmap-mac-prefixes buffer to a new file called nmap-mac-prefixes_updated in our local directory
7. Copy the nmap-mac-prefixes_updated to /usr/share/nmap/nmap-mac-prefixes

    This strategy is the approach I came up with and works for me since it has the following outcomes:

• Ensures new OUIs are added from the latest IEEE records
• Keeps a backup of the original in case something goes wrong, I can always restore the original
• Allows us to keep the unregistered data from the nmap-mac-prefixes file if there is a collision with the IEEE data (which there are a few of these)

    I took the time to put this into a Python script called nmap_oui_update.py which is available on the Professionally Evil GitHub Repo under a MIT license.  Please feel free to use it when you need to update your Nmap OUI file.

Obtaining the Script

    To obtain the script, we can download it from the GitHub repository with the following commands.

git clone https://github.com/ProfessionallyEvil/nmap_oui_update.git && \
cd nmap_oui_update

    If this command executed correctly, you have downloaded the repository to your current directory and your shell should now be inside the directory with the script.

Running the Script

    Once we have the script downloaded and are in the directory with the script, we can run this by executing the following command:

sudo python3 ./nmap_oui_update.py

    The screenshot below shows what the output will look like when this script executes.  The output from this script will show you where the backup file is stored and how many OUI records were added to the nmap-mac-prefixes file.  In our example it added a total of 1,606 new OUIs.

    We can use the Linux wc command to show the line count to compare the differences of the backup versus the real, now updated, nmap-mac-prefixes file.

Re-scanning the Unknown Host After the Update

    Now that we have run our update script, we can scan that host that reported as Unknown again and should now see it show the OUI for that device correctly!

Conclusion

    I hope you’ve enjoyed this blog post and learned something new about Nmap’s OUI lookup system and hacking on the supporting file to improve Nmap.  If you’re interested in network security fundamentals, we have a Network Security channel that covers a variety of network topics.  We also offer training via our Professionally Evil Network Testing (PENT) course, and also answer general basic questions in our Knowledge Center.  Finally, if you’re looking for a penetration test, professional training for your organization, or just have general security questions, please Contact Us.