snmpv3-utils 0.1.0__tar.gz

snmpv3_utils-0.1.0/.env.example

@@ -0,0 +1,13 @@
+# .env.example — copy to .env and fill in your values
+# SNMPv3 credentials
+SNMPV3_USERNAME=
+SNMPV3_AUTH_PROTOCOL=SHA256     # MD5 | SHA1 | SHA256 | SHA512
+SNMPV3_AUTH_KEY=
+SNMPV3_PRIV_PROTOCOL=AES128     # DES | AES128 | AES256
+SNMPV3_PRIV_KEY=
+SNMPV3_SECURITY_LEVEL=authPriv  # noAuthNoPriv | authNoPriv | authPriv
+
+# Connection defaults
+SNMPV3_PORT=161
+SNMPV3_TIMEOUT=5
+SNMPV3_RETRIES=3

snmpv3_utils-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Something is not working correctly
+labels: bug
+---
+
+**Describe the bug**
+A clear description of what is wrong.
+
+**Command run**
+```bash
+snmpv3 ...
+```
+
+**Expected behavior**
+
+**Actual behavior / error output**
+
+**Environment**
+- OS:
+- Python version:
+- snmpv3-utils version: (`snmpv3 --version`)
+- pysnmp version:

snmpv3_utils-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,11 @@
+---
+name: Feature request
+about: Suggest an improvement or new capability
+labels: enhancement
+---
+
+**What would you like to see?**
+
+**Why is this useful?**
+
+**Any implementation ideas?**

snmpv3_utils-0.1.0/.github/ISSUE_TEMPLATE/new_operation.md

@@ -0,0 +1,22 @@
+---
+name: New SNMP operation
+about: Propose adding a new SNMP command
+labels: enhancement, new-operation
+---
+
+**Operation name and description**
+
+**Which group does it belong to?**
+- [ ] query
+- [ ] trap
+- [ ] auth
+- [ ] new group (describe below)
+
+**Proposed command signature**
+```bash
+snmpv3 <group> <command> ...
+```
+
+**pysnmp API used**
+
+**Any edge cases to handle?**

snmpv3_utils-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,17 @@
+## Summary
+
+Closes #
+
+## Changes
+
+-
+
+## Checklist
+
+- [ ] Tests written before implementation (TDD)
+- [ ] `uv run pytest` passes
+- [ ] `uv run ruff check .` passes
+- [ ] `uv run ruff format --check .` passes
+- [ ] `uv run mypy src/` passes
+- [ ] `CHANGELOG.md` updated (if user-facing change)
+- [ ] `README.md` updated (if new command or changed behavior)

snmpv3_utils-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+# .github/workflows/ci.yml
+name: ci
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check .
+
+      - name: Type check (mypy)
+        run: uv run mypy src/
+
+      - name: Tests
+        run: uv run pytest --tb=short

snmpv3_utils-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,59 @@
+# .github/workflows/release.yml
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # needed to create GitHub Release
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run full CI suite
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+          uv run mypy src/
+          uv run pytest --tb=short
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: uv publish
+
+      - name: Extract changelog entry for this tag
+        id: changelog
+        run: |
+          # Extract the section matching the tag version from CHANGELOG.md
+          TAG="${GITHUB_REF_NAME}"
+          VERSION="${TAG#v}"
+          BODY=$(awk "/^## \[${VERSION}\]/{found=1; next} found && /^## /{exit} found{print}" CHANGELOG.md)
+          echo "body<<EOF" >> "$GITHUB_OUTPUT"
+          echo "$BODY" >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: ${{ steps.changelog.outputs.body }}
+          files: dist/*

snmpv3_utils-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+*.egg
+.env
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+.DS_Store

snmpv3_utils-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

snmpv3_utils-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-20
+
+### Added
+- Initial release with full SNMPv3 query, trap, and credential testing support
+- `snmpv3 query` — GET, GETNEXT, WALK, BULK, SET
+- `snmpv3 trap` — send (trap + inform), listen (stub, asyncio pending)
+- `snmpv3 auth` — single credential check, bulk CSV check
+- `snmpv3 profile` — add, delete, list, show profiles
+- Full SNMPv3 security matrix: noAuthNoPriv, authNoPriv, authPriv
+- Auth protocols: MD5, SHA1, SHA256, SHA512
+- Priv protocols: DES, AES128, AES256
+- Credential resolution: defaults → .env → profile → CLI flags
+- Rich and JSON output via `--format` flag

snmpv3_utils-0.1.0/CLAUDE.md

@@ -0,0 +1,49 @@
+# CLAUDE.md
+
+Project instructions for AI assistants working on snmpv3-utils.
+
+## Setup
+
+```bash
+uv sync --all-extras
+```
+
+## Key Commands
+
+| Task | Command |
+|------|---------|
+| Run tests | `uv run pytest` |
+| Lint | `uv run ruff check .` |
+| Format | `uv run ruff format .` |
+| Type check | `uv run mypy src/` |
+| Run CLI | `uv run snmpv3 --help` |
+
+## Architecture Rules
+
+- **`cli/`** — thin Typer wrappers only. No SNMP logic, no direct pysnmp imports.
+- **`core/`** — all SNMP operations. Returns `dict` or `list[dict]`. No CLI, no rich.
+- **`security.py`** — the only file that imports pysnmp auth/priv constants.
+- **`output.py`** — the only file that imports rich. Takes dicts, formats for display.
+
+## Adding a New Operation
+
+1. Write the failing test in `tests/test_<module>.py`
+2. Implement in `core/<module>.py`
+3. Add the CLI command in `cli/<module>.py`
+4. Add a CLI test using typer's `CliRunner`
+5. Open an issue, work in a branch, open a PR
+
+## PR & Issue Workflow
+
+- All work starts with a GitHub Issue
+- Branch from `main`, name: `feat/<issue-number>-<short-description>`
+- PRs require CI to pass (ruff, mypy, pytest)
+- Conventional commits required: `feat:`, `fix:`, `docs:`, `chore:`, `test:`
+
+## pysnmp v7 Notes
+
+- Import from `pysnmp.hlapi.v3arch.asyncio` (NOT `pysnmp.hlapi` — that's v6)
+- Auth constants: `usmHMACMD5AuthProtocol`, `usmHMACSHAAuthProtocol`, `usmHMAC192SHA256AuthProtocol`, `usmHMAC384SHA512AuthProtocol`
+- Priv constants: `usmDESPrivProtocol`, `usmAesCfb128Protocol`, `usmAesCfb256Protocol`
+- All SNMP operations are async in v7 — core/ wraps them with `asyncio.run()`
+- Trap listener requires asyncio (v7 removed asyncore dispatcher) — see `core/trap.py`

snmpv3_utils-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to snmpv3-utils
+
+Thank you for contributing! This guide covers everything you need to get started.
+
+## Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) (`pip install uv` or `brew install uv`)
+- [GitHub CLI](https://cli.github.com/) (`gh`) for issue/PR management
+
+## Dev Setup
+
+```bash
+git clone https://github.com/<your-username>/snmpv3-utils
+cd snmpv3-utils
+uv sync --all-extras
+```
+
+Verify everything works:
+```bash
+uv run pytest
+uv run snmpv3 --help
+```
+
+## Workflow
+
+1. **Find or create a GitHub Issue** for the work you want to do
+2. **Branch:** `git checkout -b feat/<issue-number>-short-description`
+3. **Write tests first** — we use TDD; tests live in `tests/`
+4. **Implement** — keep `cli/` thin and business logic in `core/`
+5. **Run checks locally** before pushing:
+   ```bash
+   uv run ruff check . && uv run ruff format . && uv run mypy src/ && uv run pytest
+   ```
+6. **Commit** using conventional commits: `feat:`, `fix:`, `docs:`, `chore:`, `test:`
+7. **Open a PR** and reference the issue with `Closes #<number>`
+
+## Adding a New SNMP Operation
+
+1. Add the core function in `src/snmpv3_utils/core/<module>.py` — return `dict`/`list[dict]`
+2. Add the CLI command in `src/snmpv3_utils/cli/<module>.py` — thin wrapper only
+3. Write tests for both in `tests/`
+4. Update `README.md` with usage example
+
+## Code Style
+
+- Formatter + linter: `ruff` (configured in `pyproject.toml`)
+- Type checker: `mypy --strict`
+- No classes unless clearly warranted — prefer functions
+- Docstrings on all public functions (one-liner is fine if self-evident)

snmpv3_utils-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: snmpv3-utils
+Version: 0.1.0
+Summary: SNMPv3 CLI testing utility — GET, WALK, SET, traps, credential testing
+License: MIT
+Keywords: cli,network,snmp,snmpv3,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: System :: Networking :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pysnmp>=7.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13
+Requires-Dist: tomli-w>=1.2
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# snmpv3-utils
+
+A Python CLI for SNMPv3 testing. Most existing tools only support v1/v2 — this one does v3 properly.
+
+## Install
+
+```bash
+pipx install snmpv3-utils
+```
+
+## Quick Start
+
+```bash
+# GET a single OID
+snmpv3 query get 192.168.1.1 1.3.6.1.2.1.1.1.0 \
+  --username admin \
+  --auth-protocol SHA256 --auth-key myauthpass \
+  --priv-protocol AES128 --priv-key myprivpass \
+  --security-level authPriv
+
+# WALK the system MIB
+snmpv3 query walk 192.168.1.1 1.3.6.1.2.1.1 --profile myrouter
+
+# Send a trap
+snmpv3 trap send 192.168.1.1 --profile myrouter
+
+# Test credentials
+snmpv3 auth check 192.168.1.1 --profile myrouter
+
+# Bulk test from a CSV
+snmpv3 auth bulk 192.168.1.1 --file creds.csv
+
+# JSON output (for piping into jq)
+snmpv3 query walk 192.168.1.1 1.3.6.1.2.1.1 --format json | jq '.[] | .value'
+```
+
+## Configuration
+
+Copy `.env.example` to `.env` and fill in your defaults:
+
+```bash
+cp .env.example .env
+```
+
+Or use named profiles:
+
+```bash
+snmpv3 profile add myrouter \
+  --username admin \
+  --auth-protocol SHA256 --auth-key myauthpass \
+  --priv-protocol AES128 --priv-key myprivpass \
+  --security-level authPriv
+```
+
+## Commands
+
+| Group | Command | Description |
+|-------|---------|-------------|
+| `query` | `get` | Fetch a single OID |
+| `query` | `getnext` | Single GETNEXT step |
+| `query` | `walk` | Full subtree traversal |
+| `query` | `bulk` | GETBULK retrieval |
+| `query` | `set` | Set an OID value |
+| `trap` | `send` | Send a trap or inform |
+| `trap` | `listen` | Listen for incoming traps |
+| `auth` | `check` | Test a credential set |
+| `auth` | `bulk` | Test many credentials from CSV |
+| `profile` | `add/delete/list/show` | Manage credential profiles |
+
+## Supported Security
+
+| Level | Auth | Privacy |
+|-------|------|---------|
+| noAuthNoPriv | — | — |
+| authNoPriv | MD5, SHA1, SHA256, SHA512 | — |
+| authPriv | MD5, SHA1, SHA256, SHA512 | DES, AES128, AES256 |
+
+## License
+
+MIT

snmpv3_utils-0.1.0/README.md

@@ -0,0 +1,80 @@
+# snmpv3-utils
+
+A Python CLI for SNMPv3 testing. Most existing tools only support v1/v2 — this one does v3 properly.
+
+## Install
+
+```bash
+pipx install snmpv3-utils
+```
+
+## Quick Start
+
+```bash
+# GET a single OID
+snmpv3 query get 192.168.1.1 1.3.6.1.2.1.1.1.0 \
+  --username admin \
+  --auth-protocol SHA256 --auth-key myauthpass \
+  --priv-protocol AES128 --priv-key myprivpass \
+  --security-level authPriv
+
+# WALK the system MIB
+snmpv3 query walk 192.168.1.1 1.3.6.1.2.1.1 --profile myrouter
+
+# Send a trap
+snmpv3 trap send 192.168.1.1 --profile myrouter
+
+# Test credentials
+snmpv3 auth check 192.168.1.1 --profile myrouter
+
+# Bulk test from a CSV
+snmpv3 auth bulk 192.168.1.1 --file creds.csv
+
+# JSON output (for piping into jq)
+snmpv3 query walk 192.168.1.1 1.3.6.1.2.1.1 --format json | jq '.[] | .value'
+```
+
+## Configuration
+
+Copy `.env.example` to `.env` and fill in your defaults:
+
+```bash
+cp .env.example .env
+```
+
+Or use named profiles:
+
+```bash
+snmpv3 profile add myrouter \
+  --username admin \
+  --auth-protocol SHA256 --auth-key myauthpass \
+  --priv-protocol AES128 --priv-key myprivpass \
+  --security-level authPriv
+```
+
+## Commands
+
+| Group | Command | Description |
+|-------|---------|-------------|
+| `query` | `get` | Fetch a single OID |
+| `query` | `getnext` | Single GETNEXT step |
+| `query` | `walk` | Full subtree traversal |
+| `query` | `bulk` | GETBULK retrieval |
+| `query` | `set` | Set an OID value |
+| `trap` | `send` | Send a trap or inform |
+| `trap` | `listen` | Listen for incoming traps |
+| `auth` | `check` | Test a credential set |
+| `auth` | `bulk` | Test many credentials from CSV |
+| `profile` | `add/delete/list/show` | Manage credential profiles |
+
+## Supported Security
+
+| Level | Auth | Privacy |
+|-------|------|---------|
+| noAuthNoPriv | — | — |
+| authNoPriv | MD5, SHA1, SHA256, SHA512 | — |
+| authPriv | MD5, SHA1, SHA256, SHA512 | DES, AES128, AES256 |
+
+## License
+
+MIT