Layer 2 网络邻居发现工具技术文档

1. 安装指南

1.1 环境要求

在开始安装之前，请确保您的系统满足以下要求：

• Python 2.7 或 3.4 及以上版本
• Scapy 库，用于网络功能，如 ARP ping

1.2 安装步骤

您可以通过以下两种方式安装项目依赖：

1.2.1 使用包管理器安装 Scapy

如果您已经安装了包管理器（如 apt、yum 或 brew），可以直接使用包管理器安装 Scapy：

$ sudo apt-get install python-scapy  # 对于 Debian/Ubuntu 系统
$ sudo yum install scapy  # 对于 CentOS/RHEL 系统
$ brew install scapy  # 对于 macOS 系统

1.2.2 使用虚拟环境安装

推荐使用虚拟环境来隔离项目依赖，避免与系统全局 Python 环境冲突。以下是使用虚拟环境的安装步骤：

$ virtualenv virtualenv  # 创建虚拟环境
$ source virtualenv/bin/activate  # 激活虚拟环境
$ pip install -r requirements.txt  # 安装项目依赖

2. 项目的使用说明

2.1 基本用法

项目提供了一个命令行工具 neighbourhood.py，用于发现本地网络中的主机。使用以下命令运行工具：

$ sudo ./neighbourhood.py [-i <interface>]

其中，-i 参数用于指定网络接口（如 eth0 或 wlan0）。如果不指定接口，工具将使用默认的网络接口。

2.2 输出结果

工具运行后，将输出本地网络中所有活动主机的 IP 地址和 MAC 地址。例如：

192.168.1.1 - 00:11:22:33:44:55
192.168.1.2 - 66:77:88:99:AA:BB

3. 项目 API 使用文档

3.1 核心功能

项目的核心功能是通过 ARP ping 发现本地网络中的主机。以下是主要功能的 API 说明：

3.1.1 discover_hosts(interface=None)

• 功能: 发现指定网络接口上的所有活动主机。
• 参数:
  • interface: 字符串类型，指定网络接口。如果为 None，则使用默认接口。
• 返回值: 返回一个字典，键为 IP 地址，值为 MAC 地址。

3.1.2 arp_ping(ip, interface=None)

• 功能: 向指定 IP 地址发送 ARP ping。
• 参数:
  • ip: 字符串类型，目标 IP 地址。
  • interface: 字符串类型，指定网络接口。如果为 None，则使用默认接口。
• 返回值: 如果目标主机响应，则返回其 MAC 地址；否则返回 None。

3.2 示例代码

以下是一个使用项目 API 的示例代码：

from neighbourhood import discover_hosts, arp_ping

# 发现所有活动主机
hosts = discover_hosts(interface='eth0')
for ip, mac in hosts.items():
    print(f"{ip} - {mac}")

# 向特定 IP 发送 ARP ping
mac_address = arp_ping('192.168.1.1', interface='eth0')
if mac_address:
    print(f"Host is alive: {mac_address}")
else:
    print("Host is not responding")

4. 项目安装方式

4.1 从源码安装

您可以通过以下步骤从源码安装项目：

1. 克隆项目仓库：

   $ git clone https://github.com/your-repo/neighbourhood.git
   $ cd neighbourhood
   

2. 创建并激活虚拟环境：

   $ virtualenv virtualenv
   $ source virtualenv/bin/activate
   

3. 安装项目依赖：

   $ pip install -r requirements.txt
   

4.2 使用 pip 安装

如果项目已经发布到 PyPI，您可以直接使用 pip 安装：

$ pip install neighbourhood

结语

本文档详细介绍了 Layer 2 网络邻居发现工具的安装、使用和 API 文档。通过本文档，您可以快速上手并使用该工具来发现本地网络中的活动主机。如果您有任何问题或建议，欢迎反馈。