check_interfaces.py
Deterministic Network Interface Monitoring
check_interfaces.py is a deterministic network interface monitoring tool designed for
operators and monitoring systems that require reproducible, audit‑transparent interface state.
It provides canonical filtering, speed enforcement, and structured output suitable for Nagios,
Icinga, and automation pipelines.
Overview
check_interfaces.py inspects local network interfaces using a deterministic, reproducible pipeline.
It supports canonical filtering rules, interface selection, speed validation, and structured metadata
extraction.
The tool is built around three principles:
- Determinism — same host → same output
- Reproducibility — no environment‑dependent behavior
- Audit Transparency — explicit, structured interface metadata
Key Features
- Canonical interface filtering (alias, virtual, local, ignore, require)
- Speed enforcement and validation
- Deterministic metadata extraction
- JSON, verbose, and Nagios output modes
- Operator‑grade error classification
- Consistent behavior across Linux distributions
Canonical Filtering
- Alias filtering — remove alias interfaces (e.g.,
eth0:1) - Virtual filtering — remove virtual interfaces (docker, veth, etc.)
- Local filtering — remove loopback and local‑only interfaces
- Ignore list — explicit operator‑defined exclusions
- Require list — enforce presence of specific interfaces
Deterministic Behavior
- Consistent interface ordering
- Structured metadata for each interface
- Explicit speed validation
- Operator‑grade verbose mode
- Nagios‑compatible single‑line output
Architecture Overview
1. Discovery Layer
Enumerates all network interfaces and retrieves raw metadata from the operating system.
All fields are normalized for reproducibility.
2. Filtering Layer
Applies canonical filtering rules to remove irrelevant or non‑operator interfaces.
Filtering is deterministic and fully explicit.
3. Validation Layer
- Speed enforcement
- Operational state checks
- Required interface validation
4. Output Layer
Produces deterministic JSON, verbose, or Nagios output.
All fields are explicit and audit‑transparent.
Current Status
- Version: 1.0.0
- Edition: Community Edition (public)
- Platform: Linux / Python 3.x
- Dependencies: Standard library only
Roadmap
Near‑Term
- Enhanced speed validation rules
- Interface grouping and tagging
- Improved error classification
Mid‑Term
- Cross‑suite correlation with check_cert.py and check_html.py
- Extended JSON schema
- Interface performance metrics
Long‑Term
- Remote interface inspection
- Distributed interface state aggregation
Why check_interfaces.py Exists
Traditional interface checkers often produce inconsistent output, rely on distribution‑specific behavior,
or provide limited visibility into interface metadata.
check_interfaces.py solves this by applying deterministic engineering principles:
- explicit filtering
- reproducible output
- audit‑transparent reporting
- no hidden behavior or implicit assumptions
Links
- GitHub Repository
- Documentation
- Usage Examples
- Release Notes