inventory-monitor-scripts 1.0.0__tar.gz

inventory_monitor_scripts-1.0.0/.env.sample

@@ -0,0 +1,33 @@
+NETBOX_API_TOKEN=
+NETBOX_INSTANCE_URL=
+
+# Define as a string of versions separated by ','
+SNMP_VERSION = '3,2'
+SNMP_USER =
+SNMP_AUTH =
+SNMP_AUTH_METHOD = "SHA"
+SNMP_PRIVACY =
+SNMP_PRIVACY_METHOD = "AES"
+SNMP_SECURITY = "authPriv"
+SNMP_COMMUNITY =
+
+# SNMP connection tuning
+SNMP_TIMEOUT=1  # timeout in seconds (default: 1) - passed to easysnmp Session
+SNMP_RETRIES=1  # total attempts per SNMP version (1 = single attempt, no retry)
+
+# when multiple model names, separate by ","
+# Note: both "excludes" (corrected) and "exludes" (legacy) spellings are accepted
+entPhysicalModelName_excludes="ASR-9900-AC-PEM,ASR-9900-DC-PEM,A9K-AC-PEM,A9K-DC-PEM"
+
+# when multiple tags, separate by ","
+NETBOX_TAGS="net-cesnet3"
+NETBOX_TAGS__N=""
+
+# SSL verification for NetBox API (true/false)
+NETBOX_VERIFY_SSL=true
+
+# Logging configuration (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+LOG_LEVEL="INFO"
+
+# Number of parallel jobs for device processing (default: 50, tuned here for dev/test)
+PARALLEL_JOBS=10

inventory_monitor_scripts-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan Krupa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

inventory_monitor_scripts-1.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+include .env.sample

inventory_monitor_scripts-1.0.0/PKG-INFO

@@ -0,0 +1,461 @@
+Metadata-Version: 2.1
+Name: inventory_monitor_scripts
+Version: 1.0.0
+Summary: Scan devices via SNMP and store its inventory to NetBox
+Home-page: https://github.com/Kani999/inventory_monitor_scripts.git
+Author: Jan Krupa
+Project-URL: Bug Tracker, https://github.com/Kani999/inventory_monitor_scripts.git/issues
+Project-URL: Source Code, https://github.com/Kani999/inventory_monitor_scripts.git
+Keywords: netbox snmp inventory network monitoring cisco juniper nokia
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Provides-Extra: test
+License-File: LICENSE
+
+# Inventory Monitor Scripts
+
+A comprehensive Python package for gathering network device inventory via SNMP and storing it in NetBox using the inventory-monitor-plugin.
+
+## Overview
+
+This package performs the following key functions:
+
+1. Loads inventory data from network devices via SNMP (v2c and v3 supported)
+2. Processes and normalizes inventory data from multiple vendor platforms
+   - Cisco (IOS, IOS-XE, IOS-XR)
+   - Juniper (JunOS)
+   - Nokia (SROS)
+3. Merges inventory items with the same serial numbers based on priority class
+4. Uploads inventory data to NetBox as Probes via the inventory-monitor-plugin
+
+## Installation
+
+### Prerequisites
+
+- Python 3.7+
+- NetBox instance with the inventory-monitor-plugin installed
+- Network access to your devices via SNMP
+- System SNMP libraries (required for easysnmp)
+
+### System Dependencies
+
+Install the net-snmp development libraries based on your OS:
+
+```bash
+# macOS (Homebrew)
+brew install net-snmp
+
+# Debian/Ubuntu
+sudo apt-get install libsnmp-dev
+
+# RHEL/CentOS
+sudo yum install net-snmp-devel
+```
+
+#### ⚠️ Known Issue: macOS ARM64 (Apple Silicon M1/M2/M3)
+
+The `easysnmp` dependency has known compilation issues on macOS with Apple Silicon processors. This is a limitation of the `easysnmp` package itself, not this project.
+
+**Recommended Workarounds:**
+
+1. **Use Docker (Recommended for Production)**
+   ```bash
+   # Use Linux-based container where easysnmp works reliably
+   docker run -it --rm -v $(pwd):/app python:3.11-slim bash
+   apt-get update && apt-get install -y libsnmp-dev gcc
+   cd /app && pip install -e .
+   ```
+
+2. **Use Linux VM or Server** - Deploy on Linux where easysnmp has better support
+
+3. **Development on macOS** - If you must develop locally on ARM64 Mac:
+   - Install OpenSSL via Homebrew: `brew install openssl@3`
+   - Try manual installation with build flags:
+     ```bash
+     export CFLAGS="-I/opt/homebrew/opt/openssl@3/include"
+     export LDFLAGS="-L/opt/homebrew/opt/openssl@3/lib"
+     pip install easysnmp
+     ```
+   - **Note**: This may still fail due to upstream bugs in easysnmp
+
+For production deployments, **we strongly recommend using Linux** (Docker, VM, or bare metal) where all dependencies install reliably.
+
+See [Troubleshooting](#troubleshooting) section for more details on easysnmp installation issues.
+
+### Python Package Installation
+
+Clone the repository and install:
+
+```bash
+git clone https://github.com/yourusername/inventory_monitor_scripts.git
+cd inventory_monitor_scripts
+pip install -e .
+```
+
+Verify installation:
+
+```bash
+python -m inventory_monitor.main --help
+```
+
+## Configuration
+
+Create a `.env` file in the repository root with required settings. Copy `.env.sample` as a starting point:
+
+```bash
+cp .env.sample .env
+# Edit .env with your credentials
+```
+
+### Multiple Environment Configurations
+
+You can maintain separate configuration files for different environments (production, staging, development) and specify which one to use with the `--env-file` flag:
+
+```bash
+# Create environment-specific files
+cp .env.sample .env.production
+cp .env.sample .env.staging
+
+# Use production config
+python -m inventory_monitor.main --env-file .env.production
+
+# Use staging config with different device filter
+python -m inventory_monitor.main --env-file .env.staging --netbox-tags staging
+```
+
+If `--env-file` is not specified, the default `.env` file is used. This allows you to keep separate SNMP credentials, NetBox instances, and other settings per environment without modifying the default configuration.
+
+### Security Best Practices
+
+**⚠️ IMPORTANT**: This tool handles sensitive credentials (SNMP community strings, SNMPv3 passwords, NetBox API tokens).
+
+**Recommended approach**:
+- ✅ **Use environment variables** (`.env` file or exported variables)
+- ✅ **Use `--env-file` for different environments** (keeps credentials in files, not CLI)
+- ❌ **Avoid CLI arguments** for secrets (visible in `ps aux`, shell history, logs)
+
+While CLI arguments like `--snmp-community` and `--netbox-api-token` are supported for convenience, they expose credentials in process listings. Use them only for testing in secure environments.
+
+### Required Settings
+
+```bash
+# NetBox API Configuration
+NETBOX_API_TOKEN="your_netbox_api_token"
+NETBOX_INSTANCE_URL="https://your-netbox-instance/"
+
+# SNMP Protocol Version (comma-separated, tried in order)
+SNMP_VERSION="3,2"  # Try SNMPv3 first, fall back to SNMPv2
+
+# SNMPv2 Configuration
+SNMP_COMMUNITY="public"  # SNMPv2 community string
+
+# SNMPv3 Configuration (only needed if using SNMPv3)
+SNMP_USER="snmp_user"
+SNMP_AUTH="auth_password"
+SNMP_AUTH_METHOD="SHA"  # MD5 or SHA
+SNMP_PRIVACY="privacy_password"
+SNMP_PRIVACY_METHOD="AES"  # DES or AES
+SNMP_SECURITY="authPriv"  # noAuthNoPriv, authNoPriv, or authPriv
+```
+
+### Optional Settings
+
+```bash
+# Device Filtering
+NETBOX_TAGS="tag1,tag2"  # Only process devices with these tags
+NETBOX_TAGS__N="tag3,tag4"  # Exclude devices with these tags
+entPhysicalModelName_excludes="ASR-9900-AC-PEM,ASR-9900-DC-PEM"  # Exclude specific models
+# Note: the legacy spelling "entPhysicalModelName_exludes" is also accepted
+
+# SNMP Connection Tuning
+SNMP_TIMEOUT=1     # SNMP timeout in seconds (default: 1)
+SNMP_RETRIES=1     # Number of retries per SNMP version (default: 1)
+
+# NetBox SSL
+NETBOX_VERIFY_SSL=true  # Set to "false" to skip SSL certificate verification
+
+# Performance Tuning
+PARALLEL_JOBS=50  # Number of parallel device processing jobs (default: 50)
+
+# Logging
+LOG_LEVEL="INFO"  # DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)
+```
+
+**Security Note**: The `.env` file contains sensitive credentials and is automatically ignored by git. The application loads config in priority order: `.env` file → environment variables (CLI and exported vars override `.env` values).
+
+## Usage
+
+### Process all devices
+
+Run the script to process all active devices with primary IPs in NetBox:
+
+```bash
+python -m inventory_monitor.main
+```
+
+The script will:
+1. Query NetBox for matching devices
+2. Establish SNMP connections to each device in parallel
+3. Retrieve inventory data
+4. Merge inventory items by serial number
+5. Create or update Probes in NetBox
+
+### Process a single device
+
+To process a specific device by name (useful for testing):
+
+```bash
+python -m inventory_monitor.main --device router-1
+```
+
+Single device processing runs sequentially without parallelization.
+
+### CLI options for SNMP and NetBox
+
+All SNMP and NetBox parameters can be overridden directly from the command line. CLI values take precedence over `.env` settings:
+
+```bash
+# Override SNMPv2 community string
+python -m inventory_monitor.main --snmp-version 2 --snmp-community my_community
+
+# Override SNMPv3 credentials
+python -m inventory_monitor.main --snmp-user admin --snmp-auth MyPass --snmp-auth-method SHA
+
+# Override SNMPv3 with full privacy
+python -m inventory_monitor.main \
+  --snmp-user admin \
+  --snmp-auth AuthPass \
+  --snmp-auth-method SHA \
+  --snmp-privacy PrivPass \
+  --snmp-privacy-method AES \
+  --snmp-security authPriv
+
+# Adjust timeout and retries
+python -m inventory_monitor.main --snmp-timeout 30 --snmp-retries 3
+
+# Combine with device selection
+python -m inventory_monitor.main --device router-1 --snmp-version 2 --snmp-community secret
+
+# Override NetBox settings
+python -m inventory_monitor.main --netbox-url https://netbox.example.com/ --netbox-api-token mytoken
+
+# Filter by tags via CLI
+python -m inventory_monitor.main --netbox-tags production,core
+
+# Exclude tags via CLI
+python -m inventory_monitor.main --netbox-tags-exclude decommissioned
+
+# Adjust parallel jobs
+python -m inventory_monitor.main --parallel-jobs 10
+```
+
+Full list of CLI options:
+
+| Option | Description |
+|--------|-------------|
+| `--env-file` | Path to environment file (default: `.env`) |
+| `-d`, `--device` | Process a specific device by name |
+| `--snmp-version` | Comma-separated SNMP versions to try (e.g. `"3,2"`) |
+| `--snmp-community` | SNMPv2 community string ⚠️ |
+| `--snmp-user` | SNMPv3 username |
+| `--snmp-auth` | SNMPv3 auth password ⚠️ |
+| `--snmp-auth-method` | SNMPv3 auth protocol (`MD5` or `SHA`) |
+| `--snmp-privacy` | SNMPv3 privacy password ⚠️ |
+| `--snmp-privacy-method` | SNMPv3 privacy protocol (`DES` or `AES`) |
+| `--snmp-security` | SNMPv3 security level (`noAuthNoPriv`, `authNoPriv`, `authPriv`) |
+| `--snmp-timeout` | SNMP timeout per request (integer) |
+| `--snmp-retries` | Number of retries per SNMP version (integer) |
+| `--netbox-api-token` | NetBox API token ⚠️ |
+| `--netbox-url` | NetBox instance URL |
+| `--netbox-tags` | Comma-separated tags to filter devices |
+| `--netbox-tags-exclude` | Comma-separated tags to exclude devices |
+| `--parallel-jobs` | Number of parallel processing jobs (integer) |
+| `--log-level` | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`) |
+| `--model-excludes` | Comma-separated model names to exclude from inventory |
+| `--debug-dump` | Dump raw SNMP data to JSON file for debugging |
+
+⚠️ Options marked with warning expose credentials in process listings. Use `--env-file` with separate environment files instead.
+
+### Override environment variables at runtime
+
+You can also still use environment variable overrides:
+
+```bash
+# Force SNMPv2 only
+SNMP_VERSION='2' python -m inventory_monitor.main
+
+# Process only devices tagged 'production'
+NETBOX_TAGS='production' python -m inventory_monitor.main
+
+# Combine multiple overrides
+LOG_LEVEL=DEBUG PARALLEL_JOBS=10 python -m inventory_monitor.main --device test-device
+```
+
+### Performance tuning
+
+For large device sets, adjust parallelism:
+
+```bash
+# Reduce load on SNMP devices (10 parallel jobs)
+PARALLEL_JOBS=10 python -m inventory_monitor.main
+
+# Maximize throughput (200 parallel jobs, requires more system resources)
+PARALLEL_JOBS=200 python -m inventory_monitor.main
+```
+
+## How to tell which SNMP version is being used
+
+The application logs which SNMP version successfully connects to each device. Run with `LOG_LEVEL=DEBUG` (or at default `INFO`) and look for these log messages:
+
+```
+# Successful SNMPv3:
+device-name (10.0.0.1): SNMPv3 connection successful
+
+# SNMPv3 failed, fell back to SNMPv2:
+device-name (10.0.0.1): Unable to use SNMPv3 - <reason>
+device-name (10.0.0.1): SNMPv2 connection successful
+
+# Both failed:
+device-name (10.0.0.1): All SNMP connection attempts failed
+```
+
+The version try order is controlled by `SNMP_VERSION` (env) or `--snmp-version` (CLI). With the default `"3,2"`, SNMPv3 is tried first. If it fails, SNMPv2 is tried. To force a specific version:
+
+```bash
+# Force SNMPv2 only (skip v3 entirely)
+python -m inventory_monitor.main --snmp-version 2
+
+# Force SNMPv3 only (no v2 fallback)
+python -m inventory_monitor.main --snmp-version 3
+
+# Try v2 first, then v3
+python -m inventory_monitor.main --snmp-version "2,3"
+```
+
+At `DEBUG` log level, you will also see retry attempts. The default `SNMP_RETRIES=1` means one attempt per version (no retries). With `--snmp-retries 3`:
+
+```
+device-name (10.0.0.1): SNMPv3 attempt 1/3 failed, retrying
+device-name (10.0.0.1): SNMPv3 attempt 2/3 failed, retrying
+device-name (10.0.0.1): SNMPv3 authentication failed - check username and password/keys
+device-name (10.0.0.1): SNMPv2 connection successful
+```
+
+## Logging
+
+Logs are created in the `logs/` directory with automatic rotation:
+
+- **`logs/all.log`** - All messages at the configured log level (default: INFO)
+- **`logs/errors.log`** - Error and critical messages with detailed traces
+
+Both logs rotate at 10 MB and are retained for 1 week.
+
+Set `LOG_LEVEL=DEBUG` for detailed troubleshooting:
+
+```bash
+LOG_LEVEL=DEBUG python -m inventory_monitor.main --device router-1
+```
+
+## Troubleshooting
+
+### Installation Issues
+
+**easysnmp on macOS ARM64**: The `easysnmp` dependency has known issues on Apple Silicon Macs. For production use, deploy on Linux (recommended) or use Docker.
+
+### SNMP Connection Issues
+
+**"All SNMP connection attempts failed"**
+- Verify device IP is reachable: `ping <device-ip>`
+- Confirm SNMP is enabled on the device
+- Check SNMP credentials in `.env`
+- Try forcing a specific version: `python -m inventory_monitor.main --device <name> --snmp-version 2`
+
+**"SNMPv3 authentication failed"**
+- Verify `SNMP_USER` matches device configuration
+- Check `SNMP_AUTH` password and `SNMP_AUTH_METHOD` (SHA vs MD5)
+- If using privacy, ensure `SNMP_PRIVACY` password and `SNMP_PRIVACY_METHOD` are correct
+- Override from CLI to test: `--snmp-user myuser --snmp-auth mypass --snmp-auth-method SHA`
+
+**"SNMPv2 timeout"**
+- Device may not support SNMPv2
+- Increase timeout: `--snmp-timeout 200`
+- Increase retries: `--snmp-retries 3`
+- Try SNMPv3: `--snmp-version 3`
+
+### No Inventory Returned
+
+- Device may not support Entity MIB (standard OIDs)
+- Cisco devices fall back to legacy OIDs automatically
+- Check device is actively reporting SNMP inventory
+
+### NetBox API Errors
+
+**"API token invalid"**
+- Regenerate token in NetBox under Settings > API Tokens
+- Verify token has write permissions to inventory-monitor plugin
+
+**"Probe creation failed"**
+- Ensure inventory-monitor-plugin is installed in NetBox
+- Check device exists in NetBox with correct name
+- Verify device has primary IPv4 address assigned
+
+**"NetBox API error ... 500"**
+- NetBox server encountered an internal error
+- Check NetBox server logs for details
+- Retry after the server recovers
+
+**"NetBox API error ... 400 ... not one of the available choices"**
+- A tag specified in `NETBOX_TAGS` or `--netbox-tags` does not exist in NetBox
+- Verify tag names match exactly (case-sensitive)
+- Create missing tags in NetBox under Organization > Tags
+
+### Debug Data
+
+Use `--debug-dump` to save raw SNMP data as a JSON file for inspection:
+
+```bash
+python -m inventory_monitor.main --device router-1 --debug-dump debug_output.json
+```
+
+Then inspect it in Python:
+
+```python
+import json
+with open('debug_output.json') as f:
+    data = json.load(f)
+    # Inspect raw SNMP results
+```
+
+## Development
+
+See `CLAUDE.md` for detailed architecture and development guidance.
+
+### Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/your-feature`)
+3. Commit your changes (`git commit -am 'Add feature'`)
+4. Push to the branch (`git push origin feature/your-feature`)
+5. Create a Pull Request
+
+## License
+
+[Insert your license information here]
+
+## Credits
+
+Developed by [Your Organization/Team Name]