[Show & Tell] NetBox Endpoint Locator: Find an endpoint's access switch and port from IP or MAC

[Jaycelu]

Hi everyone,

I recently built a small NetBox plugin that I’d like to share with the community.

Project name: NetBox Endpoint Locator

Repository:
https://github.com/Jaycelu/netbox_-endpoint_locator

The goal of this plugin is simple:

If you only have an endpoint IP address or MAC address, you can quickly locate the access switch, interface, and VLAN directly from NetBox.

In day-to-day operations, this is a very common troubleshooting workflow:

• You know the endpoint IP, but not where it is physically connected
• You have the MAC address, but still need to jump across multiple systems
• You want to combine NetBox’s inventory view with live network data from LibreNMS

So I built this plugin to bring that workflow closer to NetBox.

What it does

Given an IPv4 address or a MAC address, the plugin queries LibreNMS APIs and tries to return:

• MAC address
• Related IPv4 information
• LibreNMS hostname
• Switch / device name
• Interface
• VLAN
• A matching NetBox device when possible

The main lookup flow is roughly:

IP -> ARP -> MAC -> FDB -> Port -> VLAN

If the input is a MAC address, the flow becomes:

MAC -> ARP / FDB -> Port -> VLAN

The UI also lets you expand the raw API response, which makes it easier to troubleshoot field differences across LibreNMS versions or environments.

Why I built it

In my own environment, I often need to answer a very practical question:

Where exactly is this endpoint connected?

The traditional workflow usually looks like this:

• Find the IP or MAC
• Search ARP / FDB / port data in LibreNMS or another monitoring system
• Confirm the interface
• Go back to NetBox for device context

None of those steps are hard, but they are repetitive and fragmented.

This plugin is meant to be a small but useful bridge:
making NetBox not only a source of truth for inventory, but also a quicker entry point for endpoint troubleshooting.

Current features

• Lookup by IP or MAC
• Integrated into the NetBox plugin menu
• Uses LibreNMS APIs for ARP / FDB / port data
• Attempts to map results back to a NetBox device
• Supports raw response inspection for debugging and adaptation

Target environment

Currently tested and intended mainly for:

• NetBox 4.4.x
• Environments where LibreNMS API access is available and ARP / FDB / port data is populated

Installation

Install the plugin in the same Python environment used by NetBox, then enable it in configuration.py:

PLUGINS = ["netbox_endpoint_locator"]

PLUGINS_CONFIG = {
    "netbox_endpoint_locator": {
        "librenms_url": "https://librenms.example.com",
        "librenms_token": "YOUR_TOKEN",
        "verify_ssl": False,
        "timeout": 15,
    }
}
After that, restart NetBox and the plugin should be available from the plugin menu.

Feedback welcome
This project is still evolving, and I’d love feedback from others using NetBox + LibreNMS in real environments.

If you try it, I’d be very interested in:

bug reports
field compatibility issues
feature suggestions
pull requests
real-world use cases
If the plugin looks useful to you, a Star on the repository would also be greatly appreciated.

Thanks.
大家好，我最近做了一个 NetBox 插件，想分享给同样在做网络运维、资产管理和故障排查的朋友。

项目名：**NetBox Endpoint Locator**

仓库地址：
https://github.com/Jaycelu/netbox_-endpoint_locator

这个插件的目标很直接：

**当你手上只有一个终端的 IP 或 MAC 时，能够直接在 NetBox 里快速定位它接在哪台交换机、哪个接口、属于哪个 VLAN。**

在很多实际场景里，我们做排障时经常会遇到这种情况：

- 已经知道终端 IP，但不知道它具体接在哪个接入交换机口
- 已经拿到 MAC，但还要在多个系统之间来回查
- 想把 NetBox 的资产视图和 LibreNMS 的实时网络数据结合起来

所以我做了这个插件，把这条查询链路尽量收敛到 NetBox 里完成。

## 这个插件能做什么

输入一个 `IPv4` 或 `MAC`，插件会通过 LibreNMS API 去查询并尽量给出以下信息：

- MAC 地址
- 关联 IPv4 信息
- LibreNMS 主机
- 交换机 / 设备名
- 接口名
- VLAN
- 尝试匹配 NetBox 中对应的设备

核心查询思路大致是：

`IP -> ARP -> MAC -> FDB -> Port -> VLAN`

如果直接输入 MAC，则会走：

`MAC -> ARP / FDB -> Port -> VLAN`

除了正常展示结果之外，页面也支持展开查看原始 API 返回，方便排查字段差异和适配不同 LibreNMS 环境。

## 为什么做它

我自己的使用场景里，经常需要做“终端到底接在哪”的快速定位。

传统方式一般是：

- 先查 IP / MAC
- 再去 LibreNMS 或其他监控系统找 ARP / FDB
- 再确认接口
- 最后再回到 NetBox 看设备信息

这个过程并不复杂，但很碎，而且频繁重复。

所以这个插件更像是一个小而实用的增强能力：
**让 NetBox 不只是静态资产库，也能承接一部分实时排障入口。**

## 当前特性

- 支持按 `IP` 或 `MAC` 查询
- 集成到 NetBox 插件菜单
- 基于 LibreNMS API 查询 ARP / FDB / Ports 数据
- 尝试将 LibreNMS 查询结果映射回 NetBox 设备
- 支持查看原始返回，方便调试和二次适配

## 适用环境

目前主要面向：

- NetBox `4.4.x`
- LibreNMS 已开启 API 并可正常返回相关 ARP / FDB / Port 数据的环境

## 安装方式

在 NetBox 使用的 Python 环境中安装插件后，在 `configuration.py` 中启用：

```python
PLUGINS = ["netbox_endpoint_locator"]

PLUGINS_CONFIG = {
    "netbox_endpoint_locator": {
        "librenms_url": "https://librenms.example.com",
        "librenms_token": "YOUR_TOKEN",
        "verify_ssl": False,
        "timeout": 15,
    }
}
然后重启 NetBox 即可。

欢迎反馈
这个项目还在持续完善中，后面我也会继续优化查询准确性、字段兼容性和展示体验。

如果你也在用 NetBox + LibreNMS，欢迎：

试用一下
提 Issue
提 PR
分享你们实际环境里的字段结构或使用场景
如果这个插件对你有帮助，也欢迎点个 Star 支持一下，同时欢迎关注我的公众号【数字卢语】。

感谢大家。
<img width="2802" height="1428" alt="c19596f2-823e-401e-8210-7345fb393ffb" src="https://github.com/user-attachments/assets/9cf3f960-0122-48c1-8240-b182ee2b483c" />

[Jaycelu]