CRUDE — Canonical Representation Under Declarative Execution
The vendor-agnostic engine that turns raw device truth (wire YAMLs) into clean, canonical data through three strict gates. Four protocols (MOPS, SNMP, SSH, Offline).
Built for Hirschmann HiOS industrial switches by Belden. Consumer-agnostic — adapters (NAPALM, gNMI, etc.) consume the engine's canonical output and reshape for their own spec.
No feature-specific Python. Wire YAMLs (generated from MIB) declare device truth. Schema YAMLs (human-authored) declare intent. The engine reads contracts, never sniffs data.
- CRUDE methods: Create, Read, Upsert, Delete, Execute — drop a YAML, the method exists
- Three gates: Schema Contract, Wire Contract, Encode/Decode
- Four protocols: MOPS (default, atomic writes), SNMPv3, SSH, Offline (config XML)
- Canonical output — schemas describe the device, not the consumer
- See API_REFERENCE.md for the full method and schema inventory
Not on PyPI yet (first publish is 2.10.0). From this repo:
pip install -e .
NAPALM integration is the separate napalm-hios 2.0 shim — not on PyPI yet.
fromcrude_engineimportFeatureEngineengine=FeatureEngine()
# ... connect transport, resolve intent, executefromnapalmimportget_network_driverdriver=get_network_driver('hios')
device=driver('192.0.2.10', 'admin', 'private') # HiOS factory defaultsdevice.open()
device.get_interfaces() # canonical outputdevice.get_dns() # 184 methods availabledevice.close()device.open()
caps=device.get_capabilities()
foroperationin ['create', 'read', 'upsert', 'delete', 'execute']:
print(f"{operation}: {caps['crude'][operation]}")| Document | Contents |
|---|---|
| status.html | Program poster — where we are, next task, proofs |
| SEED.md | Why + how work is allowed to happen |
| ROADMAP.md | Versions and exit criteria (2.10 = first PyPI) |
| GitHub issues | Leftover work (prove-then-file or comment-close) |
| METHOD_REFERENCE.md | Quick reference — methods, return keys, one line each |
| API_REFERENCE.md | Full reference — return schemas, per-protocol sources, wire detail |
| SCHEMA_MODEL.md | Canonical schema contract — structural rules + shape rules |
| ARCHITECTURE.md | Three-gate model, layer rules, data flow |
| ENGINE_PRINCIPLES.md | Operating principles — where new code goes |
| SCHEMA_PRIMITIVES.md | Every YAML key — what it does, which gate handles it |
| WIRE_SPEC.md | Wire YAML generation pipeline and format |
| DIAGNOSTIC_PROCESS.md | Mandatory ladder for fixing failing methods |
# Offline proofs (no switch) — same script GitHub Actions will run
bash scripts/ci_offline.sh
# Regenerate API reference from schema + wire YAMLs
python3 local/generator/generate_docs.py
# Validate all schemas against the canonical model
python3 local/generator/validate_schemas.py
# Regenerate the program status page
python3 scripts/generate_status.pyDefault order: MOPS > SNMP > SSH. Override with protocol_preference in optional_args.
| Protocol | Transport | Auth | Atomic Write | Dependencies |
|---|---|---|---|---|
| MOPS | HTTPS 443 | HTTP Basic | Yes (single POST) | requests |
| SNMP | UDP 161 | SNMPv3 authPriv (MD5/DES) | No | pysnmp |
| SSH | TCP 22 | Password | No | netmiko |
| Offline | XML file | None | N/A (file) | None |
# Getter audit against live device
python3 tests/audit_getters.py 192.0.2.10 --protocol mops
# All protocols
python3 tests/audit_getters.py 192.0.2.10 --protocol snmp
python3 tests/audit_getters.py 192.0.2.10 --protocol sshApache License 2.0 — see LICENSE.