etherlyzer 0.9.2__tar.gz → 0.9.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. etherlyzer-0.9.3/PKG-INFO +548 -0
  2. etherlyzer-0.9.3/README.md +517 -0
  3. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/pyproject.toml +1 -1
  4. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/terminal/commands/inspect.py +6 -0
  5. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/terminal/commands/whois.py +1 -2
  6. etherlyzer-0.9.2/PKG-INFO +0 -387
  7. etherlyzer-0.9.2/README.md +0 -356
  8. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/LICENSE +0 -0
  9. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/__init__.py +0 -0
  10. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/etherlyzer.env +0 -0
  11. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/exporter.py +0 -0
  12. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/formatters.py +0 -0
  13. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/ieee/__init__.py +0 -0
  14. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/ieee/catalog.py +0 -0
  15. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/ieee/csv_parser.py +0 -0
  16. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/ieee/ieee_registry.py +0 -0
  17. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/ieee/index.py +0 -0
  18. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/terminal/__init__.py +0 -0
  19. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/terminal/cli.py +0 -0
  20. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/terminal/commands/__init__.py +0 -0
  21. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/terminal/commands/format.py +0 -0
  22. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/terminal/commands/registries.py +0 -0
  23. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/terminal/commands/sync.py +0 -0
  24. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/terminal/commands/validate.py +0 -0
  25. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/terminal/utility.py +0 -0
  26. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/util/__init__.py +0 -0
  27. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/util/dirs.py +0 -0
  28. {etherlyzer-0.9.2 → etherlyzer-0.9.3}/src/etherlyzer/util/knobs.py +0 -0
@@ -0,0 +1,548 @@
1
+ Metadata-Version: 2.4
2
+ Name: etherlyzer
3
+ Version: 0.9.3
4
+ Summary: Fast offline lookup and classification of Ethernet-related identifiers.
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Keywords: ethernet,mac-address,oui,ieee,ethertype,networking,cybersecurity,asset-discovery,network-automation
8
+ Author: Tobias Andersen
9
+ Requires-Python: >=3.14
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Information Technology
13
+ Classifier: Intended Audience :: System Administrators
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Topic :: System :: Networking
19
+ Classifier: Topic :: Security
20
+ Classifier: Typing :: Typed
21
+ Requires-Dist: pandas (>=3.0.6,<4.0.0)
22
+ Requires-Dist: platformdirs (>=4.12.2,<5.0.0)
23
+ Requires-Dist: python-dotenv (>=1.2.4,<2.0.0)
24
+ Requires-Dist: requests (>=2.34.2,<3.0.0)
25
+ Requires-Dist: tqdm (>=4.70.1,<5.0.0)
26
+ Project-URL: Homepage, https://github.com/blue-hexagon/EtherLyzer
27
+ Project-URL: Issues, https://github.com/blue-hexagon/EtherLyzer/issues
28
+ Project-URL: Repository, https://github.com/blue-hexagon/EtherLyzer
29
+ Description-Content-Type: text/markdown
30
+
31
+ # EtherLyzer
32
+
33
+ EtherLyzer is a Python library and command-line toolkit for identifying, classifying, validating, formatting, and inspecting Ethernet-related identifiers.
34
+
35
+ It provides fast local lookups against IEEE registry data, including:
36
+
37
+ - IEEE MAC address registries:
38
+ - MA-L / OUI-24
39
+ - MA-M / OUI-28
40
+ - MA-S / OUI-36
41
+ - IAB
42
+ - Company Identifiers (CID)
43
+ - EtherType protocol identifiers
44
+ - Vendor and organization information
45
+ - Address ranges and allocation sizes
46
+ - Vendor allocation correlation across IEEE registries
47
+
48
+ EtherLyzer supports both single-value and bulk workflows through its CLI and exposes the underlying functionality as a Python library.
49
+
50
+ It is designed primarily for network engineers, cybersecurity professionals, automation, asset discovery, NAC workflows, NOC/SOC tooling, and inventory systems.
51
+
52
+ ## Features
53
+
54
+ EtherLyzer maintains a local copy of the supported IEEE registries, allowing lookups to be performed locally without sending MAC addresses or other identifiers to third-party lookup services.
55
+
56
+ Typical use cases include:
57
+
58
+ - Identify the organization associated with a MAC address.
59
+ - Distinguish between MA-L, MA-M, MA-S, and legacy IAB allocations.
60
+ - Inspect IEEE assignments, prefixes, address ranges, and allocation sizes.
61
+ - Correlate all known IEEE MAC allocations belonging to an organization.
62
+ - Look up EtherTypes such as IPv4, IPv6, ARP, LLDP, VLAN tagging, MPLS, and 802.1X.
63
+ - Validate and normalize MAC addresses.
64
+ - Diagnose malformed MAC address input.
65
+ - Correct supported typo-like character substitutions.
66
+ - Convert MAC addresses between common formatting conventions.
67
+ - Bulk-process MAC addresses interactively or from files.
68
+ - Maintain a synchronized local IEEE registry database.
69
+ - Build high-performance lookup indexes for repeated queries.
70
+ - Integrate Ethernet identifier processing into Python applications and automation.
71
+
72
+ # Installation
73
+
74
+ EtherLyzer requires Python 3.14 or newer.
75
+
76
+ ## Install from PyPI
77
+
78
+ ```bash
79
+ pip install etherlyzer
80
+ ```
81
+
82
+ Upgrade an existing installation with:
83
+
84
+ ```bash
85
+ python -m pip install --upgrade etherlyzer
86
+ ```
87
+
88
+ Verify the installation:
89
+
90
+ ```text
91
+ etherlyzer --version
92
+ ```
93
+
94
+ or:
95
+
96
+ ```text
97
+ etherlyzer -v
98
+ ```
99
+
100
+ ## Developer Installation
101
+
102
+ ```bash
103
+ git clone https://github.com/blue-hexagon/EtherLyzer
104
+ cd EtherLyzer
105
+ poetry install
106
+ poetry env activate
107
+ ```
108
+
109
+ # Command-Line Interface
110
+
111
+ ```text
112
+ usage: etherlyzer [-h] [-v] COMMAND ...
113
+
114
+ EtherLyzer - Ethernet identifier lookup, validation, formatting, and IEEE registry analysis toolkit.
115
+
116
+ options:
117
+ -h, --help show this help message and exit
118
+ -v, --version Show the installed EtherLyzer version and exit.
119
+
120
+ Commands:
121
+ COMMAND
122
+ whois Identify IEEE vendors and organizations for MAC addresses.
123
+ validate Validate and normalize MAC addresses with optional diagnostics and filtering.
124
+ format Correct and normalize MAC address formatting.
125
+ inspect Inspect an IEEE assignment and display registry, organization, range, and allocation details.
126
+ registries Show local IEEE registry metadata and synchronization status.
127
+ sync Synchronize the local IEEE registry database with upstream sources.
128
+ ```
129
+
130
+ Examples:
131
+
132
+ ```text
133
+ etherlyzer whois 00:11:22:33:44:55
134
+ etherlyzer inspect 00:11:22:33:44:55
135
+ etherlyzer validate 00-11-22-33-44-55
136
+ etherlyzer format 001122334455
137
+ etherlyzer registries
138
+ etherlyzer sync
139
+ ```
140
+
141
+ Use:
142
+
143
+ ```text
144
+ etherlyzer <command> --help
145
+ ```
146
+
147
+ for command-specific options and examples.
148
+
149
+ # Vendor Identification
150
+
151
+ The `whois` command performs IEEE vendor and organization identification for MAC addresses.
152
+
153
+ A single MAC address can be queried directly:
154
+
155
+ ```text
156
+ etherlyzer whois 00:11:22:33:44:55
157
+ ```
158
+
159
+ MAC addresses can also be loaded from a file:
160
+
161
+ ```text
162
+ etherlyzer whois -f .\macs.txt
163
+ ```
164
+
165
+ or entered interactively:
166
+
167
+ ```text
168
+ etherlyzer whois -i
169
+ ```
170
+
171
+ Help:
172
+
173
+ ```text
174
+ usage: etherlyzer whois [-h] (-f FILE | -i | [mac])
175
+
176
+ Identify IEEE vendors and organizations for one or more MAC addresses.
177
+
178
+ positional arguments:
179
+ mac MAC address to identify
180
+
181
+ options:
182
+ -h, --help show this help message and exit
183
+ -f, --file FILE Read MAC addresses from a file
184
+ -i, --interactive Read multiple MAC addresses interactively
185
+ ```
186
+
187
+ # Inspect IEEE Assignments
188
+
189
+ The `inspect` command performs a deeper inspection of an IEEE assignment.
190
+
191
+ It displays information such as:
192
+
193
+ - Organization name and address
194
+ - IEEE registry type
195
+ - Assignment prefix
196
+ - Address range
197
+ - Prefix length
198
+ - Address capacity
199
+ - Legacy status
200
+ - Related allocations belonging to the same organization
201
+
202
+ Example:
203
+
204
+ ```text
205
+ etherlyzer inspect 00:00:0c:12:34:56
206
+ ```
207
+
208
+ Example output:
209
+
210
+ ```text
211
+ Organization
212
+ Name : Cisco Systems
213
+ Full Name : Cisco Systems, Inc
214
+ Address
215
+ 170 WEST TASMAN DRIVE SAN JOSE CA US 95134-1706
216
+
217
+ Registry
218
+ IEEE Type : MA-L [MAC Address Block Large]
219
+ Assignment : 00-00-0c
220
+ Range : 00-00-0c-00-00-00 - 00-00-0c-ff-ff-ff
221
+ Legacy : False
222
+ Prefix Bits : 24 bits
223
+ Address Bits : 24 bits
224
+ Addresses : 16,777,216
225
+ ```
226
+
227
+ EtherLyzer also correlates the organization against its other known MAC registry allocations.
228
+
229
+ The registry category defaults to `mac`:
230
+
231
+ ```text
232
+ etherlyzer inspect 00:11:22:33:44:55
233
+ ```
234
+
235
+ It can also be selected explicitly:
236
+
237
+ ```text
238
+ etherlyzer inspect -t mac 00:11:22:33:44:55
239
+ etherlyzer inspect -t protocol 0800
240
+ etherlyzer inspect -t identifier <identifier>
241
+ ```
242
+
243
+ Help:
244
+
245
+ ```text
246
+ usage: etherlyzer inspect [-h] [-t {mac|protocol|identifier}] value
247
+
248
+ Inspect a single IEEE assignment and display detailed registry metadata,
249
+ organization information, address range, and related vendor allocations.
250
+
251
+ positional arguments:
252
+ value IEEE assignment or identifier to inspect.
253
+
254
+ options:
255
+ -h, --help show this help message and exit
256
+ -t, --type {mac|protocol|identifier}
257
+ IEEE registry category to search (default: mac).
258
+ ```
259
+
260
+ # Validate and Normalize MAC Addresses
261
+
262
+ The `validate` command analyzes MAC address input without attempting typo correction.
263
+
264
+ Valid input is normalized, while malformed input can be reported together with a validation mask describing the detected problems.
265
+
266
+ ```text
267
+ etherlyzer validate 00:11:22:33:44:55
268
+ ```
269
+
270
+ For multiple values:
271
+
272
+ ```text
273
+ etherlyzer validate -b
274
+ ```
275
+
276
+ Additional output controls are available:
277
+
278
+ ```text
279
+ etherlyzer validate -b --strict
280
+ etherlyzer validate -b --linenumbers --show-info
281
+ etherlyzer validate -b --show-originals
282
+ ```
283
+
284
+ Help:
285
+
286
+ ```text
287
+ usage: etherlyzer validate [-h] [-b] [-l] [-s] [-o] [-i] [mac]
288
+
289
+ Validate and normalize MAC addresses without typo correction.
290
+ Malformed input is reported rather than corrected; use `format`
291
+ for corrective formatting.
292
+
293
+ positional arguments:
294
+ mac MAC address to validate and normalize.
295
+
296
+ options:
297
+ -h, --help show this help message and exit
298
+ -b, --bulk Read multiple MAC addresses interactively.
299
+ -l, --linenumbers Prefix output lines with their corresponding input line number.
300
+ -s, --strict Suppress invalid entries and output only successfully normalized MAC addresses.
301
+ -o, --show-originals Show the original input alongside each normalized MAC address.
302
+ -i, --show-info Prefix each result with OK or ERR to indicate validation status.
303
+ ```
304
+
305
+ ## Validation Masks
306
+
307
+ Validation diagnostics use compact mask characters:
308
+
309
+ ```text
310
+ v = valid hexadecimal digit
311
+ M = missing digit
312
+ V = excess valid hexadecimal digit
313
+ I = invalid character
314
+ r/R = relaxed typo candidate
315
+ l/L = lenient typo candidate
316
+ ```
317
+
318
+ Example:
319
+
320
+ ```text
321
+ ERR 001a2b3c4d5 => vvvvvvvvvvvM
322
+ ERR 001a2b3c4d5e6 => vvvvvvvvvvvvV
323
+ ERR 001a2b3c4d5O => vvvvvvvvvvvr
324
+ ERR 001a2b3c4d5I => vvvvvvvvvvvl
325
+ ```
326
+
327
+ The distinction between validation and formatting is intentional:
328
+
329
+ - `validate` interprets the input strictly and reports problems.
330
+ - `format --fix-typos` may correct supported typo-like substitutions.
331
+
332
+ # Format MAC Addresses
333
+
334
+ The `format` command converts MAC addresses into a chosen representation.
335
+
336
+ Formatting can control:
337
+
338
+ - Separator
339
+ - Block size
340
+ - Letter casing
341
+ - Supported typo correction
342
+
343
+ Basic usage:
344
+
345
+ ```text
346
+ etherlyzer format 001122334455
347
+ ```
348
+
349
+ Convert separators:
350
+
351
+ ```text
352
+ etherlyzer format 00-11-22-33-44-55 -p :
353
+ ```
354
+
355
+ Cisco-style blocks:
356
+
357
+ ```text
358
+ etherlyzer format 001122334455 -p . -s 4
359
+ ```
360
+
361
+ Uppercase output:
362
+
363
+ ```text
364
+ etherlyzer format 00:11:22:33:44:55 -c upper
365
+ ```
366
+
367
+ Correct supported typo-like input:
368
+
369
+ ```text
370
+ etherlyzer format O0:1i:22:33:44:s5 --fix-typos
371
+ ```
372
+
373
+ Bulk formatting:
374
+
375
+ ```text
376
+ etherlyzer format -b -p . -s 4 --fix-typos
377
+ ```
378
+
379
+ Example:
380
+
381
+ ```text
382
+ etherlyzer format l..iIdOØ1!23-4oo.. --fix-typos --casing upper --block-size 4 --separator .
383
+
384
+ 111D.0012.3400
385
+ ```
386
+
387
+ Help:
388
+
389
+ ```text
390
+ usage: etherlyzer format [-h] [-b] [-p SEPARATOR] [-s BLOCK_SIZE]
391
+ [-c {lower,upper}] [-f] [mac]
392
+
393
+ Format MAC addresses using a selected separator, block size, and casing.
394
+ Optional typo correction can repair supported character substitutions.
395
+ This command formats input without performing MAC address validation.
396
+
397
+ positional arguments:
398
+ mac MAC address to format.
399
+
400
+ options:
401
+ -h, --help show this help message and exit
402
+ -b, --bulk Read multiple MAC addresses interactively.
403
+ -p, --separator SEPARATOR
404
+ Output separator: ':', '-', '.', or empty (default: ':').
405
+ -s, --block-size BLOCK_SIZE
406
+ Number of hexadecimal characters per block (default: 2).
407
+ -c, --casing {lower,upper}
408
+ Output hexadecimal casing (default: lower).
409
+ -f, --fix-typos Correct supported typo-like character substitutions before formatting.
410
+ ```
411
+
412
+ # IEEE Registry Database
413
+
414
+ EtherLyzer maintains local copies of supported IEEE datasets.
415
+
416
+ The current registry configuration and synchronization state can be inspected with:
417
+
418
+ ```text
419
+ etherlyzer registries
420
+ ```
421
+
422
+ The output includes information such as:
423
+
424
+ - Registry name
425
+ - Legacy name
426
+ - Category
427
+ - Description
428
+ - Local dataset path
429
+ - IEEE source URL
430
+ - Prefix size
431
+ - Last retrieval time
432
+ - Update interval
433
+
434
+ Supported registry types include:
435
+
436
+ | Registry | Category | Purpose |
437
+ |-----------|------------|-----------------------------------------|
438
+ | MA-L | MAC | Large MAC address allocations / OUI-24 |
439
+ | MA-M | MAC | Medium MAC address allocations / OUI-28 |
440
+ | MA-S | MAC | Small MAC address allocations / OUI-36 |
441
+ | IAB | MAC | Legacy Individual Address Blocks |
442
+ | CID | Identifier | IEEE Company Identifiers |
443
+ | EtherType | Protocol | Ethernet protocol identifiers |
444
+
445
+ # Synchronization
446
+
447
+ The local IEEE registry database can be synchronized manually:
448
+
449
+ ```text
450
+ etherlyzer sync
451
+ ```
452
+
453
+ Example:
454
+
455
+ ```text
456
+ Synchronizing IEEE registries...
457
+
458
+ Synchronization completed in 2.41 seconds.
459
+ ```
460
+
461
+ EtherLyzer also supports automatic synchronization based on the configured maximum age of the local registry data.
462
+
463
+ # Configuration
464
+
465
+ EtherLyzer ships with a default `etherlyzer.env` configuration template.
466
+
467
+ On first use, the configuration is copied to EtherLyzer's platform-specific application-data directory. The user copy can then be modified without editing files inside the installed Python package.
468
+
469
+ Example configuration:
470
+
471
+ ```dotenv
472
+ # Maximum age of the local IEEE database before synchronization, in hours
473
+ DB_UPDATE_INTERVAL_HOURS=24
474
+
475
+ # Field delimiter used for CSV and stdout output
476
+ FIELD_SEPARATOR="\t"
477
+
478
+ # MAC address formatting
479
+ # Supported separators: :, -, ., or an empty value
480
+ MAC_SEPARATOR=-
481
+
482
+ # Number of hexadecimal characters per block
483
+ MAC_BLOCK_SIZE=2
484
+
485
+ # Supported values: upper, lower
486
+ MAC_CASE=lower
487
+
488
+ # Print database synchronization messages
489
+ SHOW_SYNC_MESSAGES=true
490
+ ```
491
+
492
+ Environment variables can also override values loaded from `etherlyzer.env`.
493
+
494
+ # Python Library
495
+
496
+ EtherLyzer can also be used directly from Python.
497
+
498
+ The library exposes components for:
499
+
500
+ - IEEE registry management
501
+ - Lookup indexes
502
+ - Vendor correlation
503
+ - MAC validation
504
+ - MAC normalization
505
+ - MAC formatting
506
+ - Registry synchronization
507
+
508
+ The command-line interface is built on the same underlying library functionality.
509
+
510
+ # Offline Operation
511
+
512
+ Once the IEEE registry datasets have been synchronized locally, lookups can be performed without querying an external MAC-address lookup service.
513
+
514
+ This is useful when:
515
+
516
+ - processing internal asset inventories,
517
+ - working with sensitive network information,
518
+ - performing large numbers of lookups,
519
+ - operating in restricted environments,
520
+ - or integrating lookups into automated workflows.
521
+
522
+ Internet access is only required when the local IEEE registry data needs to be synchronized.
523
+
524
+ # Development
525
+
526
+ EtherLyzer is developed using:
527
+
528
+ - Python 3.14+
529
+ - Poetry
530
+ - pytest
531
+ - mypy
532
+ - Ruff
533
+
534
+ Clone and install the development environment:
535
+
536
+ ```bash
537
+ git clone https://github.com/blue-hexagon/EtherLyzer
538
+ cd EtherLyzer
539
+ poetry install
540
+ poetry env activate
541
+ ```
542
+
543
+ # License
544
+
545
+ EtherLyzer is released under the MIT License.
546
+
547
+ You are free to use, modify, distribute, and sell the software subject to the terms of the included `LICENSE` file.
548
+