NetAudit

Network Audit & Diagnostics Toolkit
A practical CLI for network discovery, diagnostics and infrastructure visibility.

Features • Installation • Quick Start • Network Discovery • Commands • Development

Overview

NetAudit is a command-line network auditing and diagnostics toolkit written in Python.

It is designed for network engineers, system administrators, infrastructure engineers, cybersecurity students, IT support engineers and developers working with network infrastructure.

NetAudit provides practical network visibility directly from the terminal.

It can discover hosts, identify MAC addresses and vendors, resolve hostnames, inspect ports, test connectivity, query DNS, trace routes, inspect local interfaces, communicate with supported network devices and generate reports.

The project follows a simple principle:

Report what was actually observed. Never fabricate network information.

Features

Diagnostics

ICMP ping
Packet loss
Latency
TTL information
Best-effort OS family hints
DNS lookups
Reverse DNS
Route tracing
Local interface inspection
TCP port scanning
HTTP/HTTPS checks
Network health diagnostics

Output

Human-readable terminal tables
JSON
CSV
Markdown
HTML reports

Development

Pytest test suite
Ruff linting
Mypy support
GitHub Actions
Modular scanner architecture

Network Discovery

The main network discovery command is:

netaudit scan 192.168.1.0/24

The scanner combines several mechanisms rather than depending on one protocol.

A typical result can contain:

IP              STATUS  LATENCY  HOSTNAME       MAC                  VENDOR
10.0.0.1        UP      5.2 ms   router         00:11:22:33:44:55   ExampleVendor
10.0.0.20       UP      0.8 ms   workstation    AA:BB:CC:DD:EE:FF   Apple
10.0.0.30       UP      0.7 ms   —              12:34:56:78:9A:BC   —

The values above are synthetic examples and do not represent a real network.

Not every device will expose every field.

For example, a device may:

respond to ICMP but not expose a hostname;
have a MAC address but no recognizable vendor;
expose a hostname through SMB but not reverse DNS;
block ICMP while still exposing TCP services.

NetAudit keeps these results separate instead of treating missing information as failure.

MAC Address Discovery

On macOS, NetAudit first uses the system ARP table.

For example:

arp -an

Entries such as:

? (10.0.0.1) at 00:11:22:33:44:55 on en0

are normalized to:

00:11:22:33:44:55

This is important because macOS may display some hexadecimal MAC octets using a single digit.

Scapy is available as a fallback for environments where raw ARP access is possible.

Raw packet access may require elevated privileges depending on the operating system.

Vendor Identification

NetAudit uses multiple methods to identify the manufacturer of a MAC address.

The preferred lookup uses the manuf database when available.

Example:

00:11:22:33:44:55 -> ExampleVendor
AA:BB:CC:DD:EE:FF -> ExampleVendor
12:34:56:78:9A:BC -> ExampleVendor

A built-in OUI fallback is also available for common vendors.

Vendor detection is best-effort.

A result of:

VENDOR: —

does not mean that the MAC address is invalid. It means that no matching vendor was available from the installed databases or fallback table.

Hostname Discovery

Hostname resolution uses several mechanisms.

1. SMB / NetBIOS on macOS

For devices exposing SMB, NetAudit can use:

smbutil status <IP>

For example:

Using IP address of 10.0.0.20: 10.0.0.20
Workgroup: WORKGROUP
Server: EXAMPLE-WORKSTATION

NetAudit can extract:

EXAMPLE-WORKSTATION

as the hostname.

2. Reverse DNS

The scanner attempts:

socket.gethostbyaddr(ip)

If a PTR record exists, the hostname is returned.

3. `/etc/hosts`

Local hostname mappings are checked as another fallback.

4. macOS Bonjour / mDNS

On macOS, NetAudit can use:

dns-sd

for local Bonjour-related discovery.

Bonjour resolution is intentionally best-effort because some dns-sd operations can remain active while waiting for network responses.

NetAudit applies strict timeouts and avoids blocking the entire network scan on a single Bonjour lookup.

Installation

Requirements

Python 3.11+
macOS or Linux
Windows support is best-effort

The project uses:

Typer
Rich
Scapy
Netmiko
Pydantic
Pydantic Settings
PyYAML
HTTPX
dnspython
psutil
python-dotenv

Development dependencies include:

pytest
pytest-cov
Ruff
Mypy

Quick Install

git clone https://github.com/netforge201/netaudit.git
cd netaudit
./install.sh

The installer can use pipx when available or create a local virtual environment.

Manual Installation

pip install .

For development:

pip install -e ".[dev]"

Quick Start

Scan a local network

netaudit scan 192.168.1.0/24

Scan a smaller network:

netaudit scan 192.168.1.0/28

Use more workers:

netaudit scan 192.168.1.0/24 --workers 100

Change the timeout:

netaudit scan 192.168.1.0/24 --timeout 0.5

Scan hosts and selected TCP ports:

netaudit scan 192.168.1.0/24 --ports 22,80,443,445

Export JSON:

netaudit scan 192.168.1.0/24 --json > scan.json

Export CSV:

netaudit scan 192.168.1.0/24 --csv > scan.csv

Commands

`scan`

Discover hosts in a CIDR range.

netaudit scan 192.168.1.0/24

With ports:

netaudit scan 192.168.1.0/24 --ports 22,80,443,445

JSON:

netaudit scan 192.168.1.0/24 --json

CSV:

netaudit scan 192.168.1.0/24 --csv

Common options:

Option	Description
`--timeout`	Per-host timeout
`--workers`	Concurrent worker count
`--ports`	TCP ports to check
`--json`	JSON output
`--csv`	CSV output
`--quiet`	Reduce terminal output

NetAudit limits CIDR scanning to 65,536 addresses to prevent accidental large-scale scans.

`host`

Inspect an individual host:

netaudit host 192.168.1.1

Depending on the target, information can include:

IP address
Reachability
Latency
TTL
OS family hint
Hostname
MAC address
Vendor
Open ports
Services

`ports`

Scan TCP ports:

netaudit ports 192.168.1.1

Selected ports:

netaudit ports 192.168.1.1 --ports 22,80,443

Port range:

netaudit ports 192.168.1.1 --range 1-1024

NetAudit performs connectivity checks and service identification.

It does not attempt to exploit discovered services.

`ping`

Test reachability and latency:

netaudit ping 8.8.8.8

Multiple packets:

netaudit ping 8.8.8.8 --count 10

`dns`

Forward lookup:

netaudit dns example.com

Reverse lookup:

netaudit dns 8.8.8.8 --reverse

Supported record types include:

A
AAAA
MX
NS
TXT
CNAME
PTR

`route`

Trace the route to a destination:

netaudit route 8.8.8.8

`interfaces`

Inspect local network interfaces:

netaudit interfaces

Depending on the platform, output can include:

Interface name
Interface state
MAC address
IPv4 addresses
IPv6 addresses
MTU
RX statistics
TX statistics

`doctor`

Run network diagnostics:

netaudit doctor 192.168.1.1

For a network device:

netaudit doctor 192.168.1.1 \
  --device \
  --device-type cisco_ios

Depending on the target, diagnostics can include:

ICMP
Packet loss
Latency
DNS
HTTP/HTTPS
TCP services
SSH
Interface state
Interface errors
Uptime
Default route
ARP
NTP
BGP
OSPF

Unavailable checks are reported as unavailable rather than guessed.

Network Devices

NetAudit supports read-only access to network infrastructure through Netmiko.

Platform	Device type
Cisco IOS / IOS-XE	`cisco_ios`
Cisco NX-OS	`cisco_nxos`
Cisco IOS-XR	`cisco_xr`
Juniper Junos	`juniper_junos`
Arista EOS	`arista_eos`
Generic	`generic`

Example:

netaudit device info 192.168.1.1 \
  --device-type cisco_ios

Connect:

netaudit device connect 192.168.1.1 \
  --device-type cisco_ios

Device operations are intended to be read-only.

Snapshots

Create a device snapshot:

netaudit snapshot 192.168.1.1 \
  --device-type cisco_ios

List snapshots:

netaudit snapshot --list

Compare snapshots:

netaudit diff 192.168.1.1

Snapshots can be used to identify configuration or operational state changes over time.

Reports

Generate HTML:

netaudit report scan.json --format html

Generate Markdown:

netaudit report scan.json \
  --format markdown \
  --output report.md

Supported formats:

JSON
CSV
Markdown
HTML

Configuration

Initialize configuration:

netaudit config init

Show configuration:

netaudit config show

Default configuration:

~/.netaudit/config.yaml

Example:

defaults:
  timeout: 2
  workers: 50

scanner:
  default_ports:
    - 22
    - 80
    - 443
    - 445

reports:
  directory: ./reports

snapshots:
  directory: ./snapshots

Environment variables can also be used for configuration.

Credentials

Network-device credentials should never be committed to Git.

Credential sources can include:

CLI options
Environment variables
Interactive hidden password input

Example:

export NETAUDIT_USERNAME="admin"
export NETAUDIT_PASSWORD="your-password"

Do not commit real credentials to:

Git repositories
README files
configuration files
screenshots
issue reports
shell history

Architecture

netaudit/
├── cli.py
├── commands/
│   ├── config.py
│   ├── device.py
│   ├── diff.py
│   ├── dns.py
│   ├── doctor.py
│   ├── host.py
│   ├── interfaces.py
│   ├── ping.py
│   ├── ports.py
│   ├── report.py
│   ├── route.py
│   ├── scan.py
│   └── snapshot.py
├── config/
├── devices/
├── diagnostics/
├── network/
├── reports/
├── scanner/
│   ├── arp.py
│   ├── discovery.py
│   ├── icmp.py
│   └── tcp.py
├── snapshots/
└── utils/

Discovery Architecture

The LAN scanner roughly follows this flow:

                 ┌──────────────┐
                 │ CIDR network │
                 └──────┬───────┘
                        │
                        ▼
                ┌───────────────┐
                │ ICMP discovery│
                └───────┬───────┘
                        │
                ┌───────┴────────┐
                │                │
                ▼                ▼
           Reachable         Unreachable
                │
                ▼
        ┌───────────────┐
        │ MAC discovery │
        └───────┬───────┘
                │
        ┌───────┴───────────┐
        │                   │
        ▼                   ▼
   System ARP          Scapy fallback
        │
        ▼
   ┌──────────────┐
   │ Vendor lookup│
   └──────┬───────┘
          │
          ▼
   ┌──────────────────┐
   │ Hostname lookup  │
   └────────┬─────────┘
            │
     ┌──────┼───────────────┐
     │      │               │
     ▼      ▼               ▼
    SMB    DNS          /etc/hosts
                         + Bonjour
            │
            ▼
      ┌──────────────┐
      │ TCP scanning │
      └──────┬───────┘
             │
             ▼
        Final result

Each stage is best-effort.

Failure of one discovery method does not invalidate information obtained through another method.

macOS Support

macOS receives additional integration through native utilities:

ping
arp
smbutil
dns-sd

For example, MAC addresses can often be obtained from:

arp -an

SMB hostnames can sometimes be obtained through:

smbutil status <IP>

Bonjour services can be inspected manually with:

dns-sd -B _smb._tcp local

Some macOS network information is intentionally unavailable through standard DNS.

NetAudit therefore does not assume that every local device must have a reverse-DNS hostname.

Privileges

Some operations may require elevated privileges depending on the operating system.

In particular:

Raw ARP packet transmission
Scapy packet capture
Access to /dev/bpf* on macOS

If raw packet access is unavailable, NetAudit attempts to use safer system-level alternatives where possible.

A reachable host can still be reported as:

UP

even if Scapy cannot access:

/dev/bpf0

MAC discovery is optional metadata and must not turn a reachable host into DOWN.

Security

NetAudit follows a safe-by-default approach.

The project is intended for authorized network auditing and diagnostics.

NetAudit:

Does not exploit discovered services
Does not attempt credential attacks
Does not modify network devices
Uses read-only device commands
Does not intentionally fabricate discovery data
Reports unavailable information explicitly
Limits CIDR scanning
Uses command timeouts to avoid indefinite blocking
Treats MAC and hostname discovery as best-effort

Only scan networks and systems that you own or have explicit authorization to audit.

Support NetForge

Like NetAudit?
Support the development of NetForge and future open-source network tools.

Every contribution helps fund development, testing, maintenance and new features.

Crypto Donations

💵 USDT

TRC-20

TYtLvfgG9szPoRUcNpsz3paYzynFmLS5Go

💎 TON

TON Network

UQDpx5wZ03QD5tCFT6fkhKGJ-LRFhAfn7hYohEUSNoJcv6JS

⚠️ Verify the network before sending
_{USDT donations must be sent through TRC-20.}
_{Using the wrong network may result in permanent loss of funds.}

Thank you for supporting independent open-source development.

Development

Clone the repository:

git clone https://github.com/netforge201/netaudit.git
cd netaudit

Install development dependencies:

pip install -e ".[dev]"

Run Ruff:

ruff check netaudit tests

Run tests:

pytest -q

Run Mypy:

mypy netaudit

Run coverage:

pytest --cov=netaudit

Testing

The project includes automated tests covering:

CLI behavior
Configuration
Device connectors
Diagnostics
DNS
Health checks
ICMP
Interfaces
Reports
Routing
Services
Snapshots
TCP scanning
Input validation

Before pushing changes:

ruff check netaudit tests
pytest -q

CI/CD

GitHub Actions is used for automated project checks.

Repository:

https://github.com/netforge201/netaudit

Roadmap

Planned improvements include:

Roadmap items are not considered implemented until they are present in the actual codebase.

Contributing

Contributions are welcome.

Before opening a pull request:

Run the test suite.
Run Ruff.
Run Mypy when applicable.
Add tests for new functionality.
Do not commit credentials.
Do not commit private network information.
Keep network-device functionality read-only.
Keep platform-specific behavior isolated where possible.
Do not introduce fake or guessed network results.

Example:

ruff check netaudit tests
pytest -q

License

NetAudit is released under the MIT License.

See:

LICENSE

for the full license text.

Support

If NetAudit is useful to you, consider starring the repository and contributing improvements.

Repository:

https://github.com/netforge201/netaudit

Issues:

https://github.com/netforge201/netaudit/issues

🇷🇺 Русская версия

Что такое NetAudit?

NetAudit — консольный инструмент для аудита, диагностики и анализа компьютерных сетей.

Он предназначен для сетевых инженеров, системных администраторов, специалистов по инфраструктуре, IT-support и студентов, изучающих сети и кибербезопасность.

NetAudit позволяет обнаруживать хосты, проверять их доступность, измерять задержку, получать MAC-адреса и информацию о производителе, определять hostname, сканировать TCP-порты, выполнять DNS-запросы, трассировать маршруты, анализировать локальные интерфейсы и работать с поддерживаемыми сетевыми устройствами.

Главный принцип проекта:

NetAudit показывает только реально полученные данные и не подменяет отсутствующую информацию догадками.

Возможности

Обнаружение сети

Сканирование CIDR-сетей.
Параллельное обнаружение хостов.
ICMP-проверка доступности.
Измерение latency.
Получение MAC-адресов.
Использование системной ARP-таблицы.
Поддержка macOS arp.
Поддержка Linux neighbor table.
Scapy как дополнительный механизм ARP.
Нормализация MAC-адресов.
Определение производителя по OUI.
Определение производителя через manuf.
Reverse DNS.
/etc/hosts.
SMB / NetBIOS на macOS.
Bonjour / mDNS на macOS.
TCP service discovery.
Дополнительное сканирование портов.

Диагностика

Ping.
Packet loss.
Latency.
TTL.
DNS.
Reverse DNS.
Traceroute.
Анализ интерфейсов.
TCP scanning.
HTTP/HTTPS checks.
Health diagnostics.

Сетевые устройства

Поддерживается read-only работа с:

Cisco IOS / IOS-XE
Cisco NX-OS
Cisco IOS-XR
Juniper Junos
Arista EOS
Generic devices

Для подключения используется SSH/Netmiko.

Установка

git clone https://github.com/netforge201/netaudit.git
cd netaudit
./install.sh

Или:

pip install .

Для разработки:

pip install -e ".[dev]"

Быстрый старт

Сканирование сети:

netaudit scan 10.0.0.0/24

Сканирование с TCP-портами:

netaudit scan 10.0.0.0/24 --ports 22,80,443,445

JSON:

netaudit scan 10.0.0.0/24 --json

Информация о хосте:

netaudit host 10.0.0.1

Проверка портов:

netaudit ports 10.0.0.1 --range 1-1024

Ping:

netaudit ping 8.8.8.8

DNS:

netaudit dns example.com

Reverse DNS:

netaudit dns 8.8.8.8 --reverse

Traceroute:

netaudit route 8.8.8.8

Интерфейсы:

netaudit interfaces

Диагностика:

netaudit doctor 10.0.0.1

Информация о Cisco:

netaudit device info 10.0.0.1 --device-type cisco_ios

MAC и Vendor

На macOS NetAudit в первую очередь использует системную ARP-таблицу:

arp -an

MAC-адреса macOS могут отображаться с однозначными hex-октетами. NetAudit нормализует их до стандартного шестнадцатеричного формата.

Например, синтетический пример:

10.0.0.1 -> 00:11:22:33:44:55

Vendor определяется через базу manuf и встроенный OUI fallback.

Если производитель неизвестен, NetAudit показывает:

VENDOR: —

Это означает только то, что соответствие не было найдено.

Hostname

NetAudit использует несколько источников:

Reverse DNS.
/etc/hosts.
SMB / NetBIOS.
Bonjour / mDNS на macOS.

Hostname не всегда доступен. Это нормально для локальных сетей: устройство может отвечать на ICMP и иметь MAC-адрес, но не иметь PTR-записи или доступного имени.

macOS

Для macOS используются системные инструменты:

arp
smbutil
dns-sd

Некоторые Bonjour-запросы могут ждать ответ от сети. Поэтому NetAudit использует таймауты и не должен блокировать весь скан из-за одного устройства.

Конфигурация

Основной конфигурационный файл:

~/.netaudit/config.yaml

Пример:

defaults:
  timeout: 2
  workers: 50

scanner:
  default_ports:
    - 22
    - 80
    - 443
    - 445

reports:
  directory: ./reports

snapshots:
  directory: ./snapshots

Также можно использовать переменные окружения с префиксом:

NETAUDIT_*

Безопасность

NetAudit предназначен для авторизованного аудита.

Инструмент:

не пытается эксплуатировать найденные сервисы;
не изменяет конфигурацию сетевых устройств;
использует read-only команды;
не должен сохранять credentials в отчётах;
ограничивает размер CIDR-сканирования;
сообщает об отсутствующих зависимостях и привилегиях;
не выдумывает MAC, hostname или vendor.

Используйте NetAudit только в сетях и системах, на аудит которых у вас есть разрешение.

Разработка

ruff check netaudit tests
pytest -q

Type checking:

mypy netaudit

Coverage:

pytest --cov=netaudit

Поддержать NetForge

Если NetAudit оказался полезен, можно поддержать разработку проекта криптодонатом.

USDT — TRC-20

TYtLvfgG9szPoRUcNpsz3paYzynFmLS5Go

TON

UQDpx5wZ03QD5tCFT6fkhKGJ-LRFhAfn7hYohEUSNoJcv6JS

Перед отправкой обязательно проверьте сеть. Для USDT используется именно TRC-20.

Спасибо за поддержку независимой open-source разработки.

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
examples		examples
netaudit		netaudit
reports		reports
snapshots		snapshots
tests		tests
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
config.example.yaml		config.example.yaml
install.sh		install.sh
netaudit.sh		netaudit.sh
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

NetAudit

Overview

Features

Network discovery

Diagnostics

Network devices

Output

Development

Network Discovery

MAC Address Discovery

Vendor Identification

Hostname Discovery

1. SMB / NetBIOS on macOS

2. Reverse DNS

3. /etc/hosts

4. macOS Bonjour / mDNS

Installation

Requirements

Quick Install

Manual Installation

Quick Start

Scan a local network

Commands

scan

host

ports

ping

dns

route

interfaces

doctor

Network Devices

Snapshots

Reports

Configuration

Credentials

Architecture

Discovery Architecture

macOS Support

Privileges

Security

Support NetForge

Crypto Donations

💵 USDT

💎 TON

Development

Testing

CI/CD

Roadmap

Contributing

License

Support

🇷🇺 Русская версия

Что такое NetAudit?

Возможности

Обнаружение сети

Диагностика

Сетевые устройства

Установка

Быстрый старт

MAC и Vendor

Hostname

macOS

Конфигурация

Безопасность

Разработка

Поддержать NetForge

USDT — TRC-20

TON

About

Topics

Resources

Stars

Watchers

Forks

Releases

3. `/etc/hosts`

`scan`

`host`

`ports`

`ping`

`dns`

`route`

`interfaces`

`doctor`