NetBox macadress

A NetBox plugin that adds the IEEE vendor to every MAC address in NetBox, using the macadress.com API. It works with no API key (vendor name only). A free key adds the block type, country and registered address.

Features

• Vendor panel on MAC address, device interface and VM interface pages
• Vendor column for the MAC address table (enable it under Configure Table), included in exports
• Background sync that looks up new MAC addresses and refreshes vendors after 30 days. A lookup is also queued as soon as a MAC address with an unknown vendor is saved, and from the Look up now button.
• One lookup per block: addresses are cached per IEEE block (OUI, MA-M or MA-S), so a few hundred lookups usually cover thousands of devices. Blocks that IEEE splits between several vendors are cached at the right width, so devices are never labeled with a neighbor's vendor.
• No lookup for locally administered (often randomized) or multicast addresses
• MAC Vendors list with filtering, global search, REST API and GraphQL

Compatibility

See COMPATIBILITY.md. Requires Python 3.12+.

Dependencies

• macadress, the official macadress.com Python client (installed automatically)
• A running NetBox background worker (manage.py rqworker), which runs the lookups
• Outbound HTTPS to api.macadress.com. NetBox's HTTP_PROXIES / PROXY_ROUTERS settings are honored.

Installation

source /opt/netbox/venv/bin/activate
pip install netbox-macadress

Add it to local_requirements.txt so NetBox upgrades keep it, then enable it in configuration.py:

PLUGINS = ["netbox_macadress"]

Apply the migration and restart NetBox and its worker:

cd /opt/netbox/netbox
python manage.py migrate
sudo systemctl restart netbox netbox-rq

For netbox-docker, add netbox-macadress to plugin_requirements.txt and see Using NetBox Plugins.

Configuration

Every setting is optional:

PLUGINS_CONFIG = {
    "netbox_macadress": {
        "api_key": "",              # or set MACADRESS_API_KEY in the environment
        "sync_interval": 60,        # minutes between scheduled syncs
        "max_lookups_per_run": 500, # the rest wait for the next run
        "refresh_days": 30,         # age at which a cached vendor is looked up again
        "lookup_on_save": True,     # queue a lookup when a MAC with an unknown vendor is saved
        "timeout": 10,
        "base_url": "https://api.macadress.com",
    },
}

When a key is added later, entries fetched without one are refreshed on the next sync.

REST API and GraphQL

• GET /api/plugins/macadress/vendors/, filterable by mac_address, prefix, organization, status, country, source and q. Delete an entry to force it to be looked up again.
• GraphQL: mac_vendor(id: ...) and mac_vendor_list

Support

• Issues: https://github.com/sapisos/netbox-macadress/issues
• Maintainer: Samy Massoud, macadress.com

License

Apache-2.0, see LICENSE.