etherlyzer 0.5.1__py3-none-any.whl

etherlyzer/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("etherlyzer")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

etherlyzer/exporter.py

@@ -0,0 +1,31 @@
+from etherlyzer.util.settings import config
+from etherlyzer.formatters import MACFormatter
+
+from etherlyzer.ieee.registry import IEEEEntry
+
+
+class RegistryMatchExporter:
+    @staticmethod
+    def export_csv_to_console(entries: list[IEEEEntry]):
+        for entry in entries:
+            try:
+                print(
+                    f"{entry.registry}{config.field_separator}"
+                    f"{MACFormatter.format_default(entry.assignment)}{config.field_separator}"
+                    f"{entry.organization_name}{config.field_separator}"
+                    f"{entry.organization_address}"
+                    f""
+                )
+            except AttributeError():
+                # Lookup not found.
+                pass
+
+    @staticmethod
+    def export_humanized_to_console(entries: list[IEEEEntry]):
+        for entry in entries:
+            mac = MACFormatter.format_default(entry.assignment)
+            try:
+                print(f"{entry.registry}: {mac} {entry.organization_name}")
+            except AttributeError():
+                # Lookup not found.
+                pass

etherlyzer/formatters.py

@@ -0,0 +1,154 @@
+from enum import StrEnum
+from typing import Literal
+
+from etherlyzer.util.settings import config
+from string import punctuation
+
+
+class MacMaskLetter(StrEnum):
+    EXCESS_INVALID = "I"
+    INVALID = "i"
+    EXCESS_HEX = "V"
+    HEX = "v"
+    EXCESS_RELAXED_TYPO = "R"
+    RELAXED_TYPO = "r"
+    EXCESS_LENIENT_TYPO = "L"
+    LENIENT_TYPO = "l"
+    PUNCTUATION = "p"
+    SEPERATOR = "-"
+
+
+class MACFormatter:
+    HEX_DIGITS = frozenset("0123456789ABCDEFabcdef")
+    VALID_SEPERATORS = frozenset(" -.:")
+    STRICT_TYPOS: dict[str, str] = {" ": "", "\t": ""}
+    RELAXED_TYPOS: dict[str, str] = {  # noqa: RUF012
+        **STRICT_TYPOS,
+        "o": "0",
+        "O": "0",
+    }
+
+    LENIENT_TYPOS: dict[str, str] = {  # noqa: RUF012
+        **RELAXED_TYPOS,
+        "i": "1",
+        "I": "1",
+        "l": "1",
+        "L": "1",
+        "s": "5",
+        "S": "5",
+        "ø": "0",
+        "Ø": "0",
+    }
+
+    @classmethod
+    def format_default(cls, mac: str) -> str:
+        mac = cls.normalize(mac)
+        mac = config.mac_separator.join(
+            mac[i: i + config.mac_block_size] for i in range(0, len(mac), config.mac_block_size)
+        )
+
+        return getattr(mac, config.mac_case.value)()
+
+    @classmethod
+    def format_with_stuffed_hex(cls, mac: str, stuffed_hex: str) -> str:
+        mac = (cls.normalize(mac) + 12 * stuffed_hex)[:12]
+        return cls.format_default(mac)
+
+    @classmethod
+    def format_custom(
+            cls,
+            mac: str,
+            block_size: int,
+            separator: Literal[".", ":", "-"],
+            case: Literal["upper", "lower"],
+            fix_typos: bool,
+    ) -> str:
+        if fix_typos:
+            mac = cls.fix_typos(mac)
+        mac = cls.normalize(mac)
+        if len(mac) > 12:
+            raise ValueError(f"Malformed MAC address is of length: {len(mac)}!")
+        mac = separator.join(mac[i: i + block_size] for i in range(0, len(mac), block_size))
+        if case == "upper":
+            return mac.upper()
+        return mac.lower()
+
+    @classmethod
+    def validate(cls, in_addr: str) -> tuple[str, str]:
+        normalized_mac = ""
+        validation_mask = ""
+        valid_letter_count = 0
+        typo_count = 0
+
+        def valid_norm_mac_check():
+            return valid_letter_count + typo_count < 12
+
+        for idx, ch in enumerate(in_addr):
+            if ch in cls.HEX_DIGITS:
+                if valid_norm_mac_check():
+                    normalized_mac += ch.lower()
+                    validation_mask += MacMaskLetter.HEX
+                else:
+                    normalized_mac += ch.lower()
+                    validation_mask += MacMaskLetter.EXCESS_HEX
+                valid_letter_count += 1
+            elif ch in cls.VALID_SEPERATORS:
+                pass
+            elif ch in punctuation:
+                pass
+            elif ch in cls.RELAXED_TYPOS:
+                if valid_norm_mac_check():
+                    normalized_mac += ch
+                    validation_mask += MacMaskLetter.RELAXED_TYPO
+                else:
+                    normalized_mac += ch
+                    validation_mask += MacMaskLetter.EXCESS_RELAXED_TYPO
+                typo_count += 1
+            elif ch in cls.LENIENT_TYPOS:
+                if valid_norm_mac_check():
+                    normalized_mac += ch
+                    validation_mask += MacMaskLetter.LENIENT_TYPO
+                else:
+                    normalized_mac += ch
+                    validation_mask += MacMaskLetter.EXCESS_LENIENT_TYPO
+                typo_count += 1
+            else:
+                if valid_norm_mac_check():
+                    normalized_mac += ch
+                    validation_mask += MacMaskLetter.INVALID
+                else:
+                    normalized_mac += ch
+                    validation_mask += MacMaskLetter.EXCESS_INVALID
+        if len(validation_mask) < 12:
+            validation_mask = validation_mask.ljust(12, "M")
+        return normalized_mac, validation_mask
+
+    @classmethod
+    def mask_is_valid(cls, mask: str) -> bool:
+        return len(mask) == 12 and all([ch == "v" for ch in mask])
+
+    @classmethod
+    def normalize(cls, mac: str) -> str:
+        mac = "".join(c for c in mac.lower() if c in cls.HEX_DIGITS)
+        return mac
+
+    @classmethod
+    def fix_typos(cls, mac: str) -> str:
+        for c in mac:
+            if c in cls.LENIENT_TYPOS:
+                mac = mac.replace(c, cls.LENIENT_TYPOS[c])
+            elif c not in cls.HEX_DIGITS:
+                mac = mac.replace(c, "#")
+        return mac
+
+
+if __name__ == "__main__":
+    print(
+        MACFormatter().format_custom(
+            mac="ab:cd:ef:fg:de:dd",
+            separator=":",
+            block_size=2,
+            case="upper",
+            fix_typos=False,
+        )
+    )

etherlyzer/ieee/catalog.py

@@ -0,0 +1,130 @@
+from etherlyzer.ieee.registry import RegCategory, IEEEEntry, EtherTypeEntry, IEEERegistry
+
+
+class Catalog:
+    IEEE_REGISTRIES = {  # noqa
+        "mal": IEEERegistry(
+            enabled=True,
+            name="MA-L",
+            model=IEEEEntry,
+            full_name="MAC Address Block Large",
+            legacy_name="OUI",
+            category=RegCategory.MAC,
+            prefix_bits=24,
+            address_bits=24,
+            address_count=16_777_216,
+            legacy=False,
+            description=(
+                "Large IEEE MAC address allocation. Formerly known as the "
+                "Organizationally Unique Identifier (OUI). Used by vendors "
+                "requiring large address spaces."
+            ),
+            url="https://standards-oui.ieee.org/oui/oui.csv",
+        ),
+        "mam": IEEERegistry(
+            enabled=True,
+            name="MA-M",
+            model=IEEEEntry,
+            full_name="MAC Address Block Medium",
+            legacy_name="OUI-28",
+            category=RegCategory.MAC,
+            prefix_bits=28,
+            address_bits=20,
+            address_count=1_048_576,
+            legacy=False,
+            description=(
+                "Medium-sized IEEE MAC address allocation intended for "
+                "organizations requiring fewer addresses than MA-L."
+            ),
+            url="https://standards-oui.ieee.org/oui28/mam.csv",
+        ),
+        "mas": IEEERegistry(
+            enabled=True,
+            name="MA-S",
+            model=IEEEEntry,
+            full_name="MAC Address Block Small",
+            legacy_name="OUI-36",
+            category=RegCategory.MAC,
+            prefix_bits=36,
+            address_bits=12,
+            address_count=4_096,
+            legacy=False,
+            description=(
+                "Small IEEE MAC address allocation for embedded devices, "
+                "IoT, industrial equipment, and smaller manufacturers."
+            ),
+            url="https://standards-oui.ieee.org/oui36/oui36.csv",
+        ),
+        "cid": IEEERegistry(
+            enabled=True,
+            name="CID",
+            model=IEEEEntry,
+            full_name="Company Identifier",
+            legacy_name=None,
+            category=RegCategory.IDENTIFIER,
+            legacy=False,
+            description=(
+                "Unique company identifiers assigned by IEEE. Identifies "
+                "organizations independently of MAC address allocations."
+            ),
+            url="https://standards-oui.ieee.org/cid/cid.csv",
+        ),
+        "iab": IEEERegistry(
+            enabled=True,
+            name="IAB",
+            model=IEEEEntry,
+            full_name="Individual Address Block",
+            legacy_name=None,
+            category=RegCategory.MAC,
+            prefix_bits=36,
+            address_bits=12,
+            address_count=4_096,
+            legacy=True,
+            description=(
+                "Legacy IEEE MAC address allocation scheme superseded by "
+                "MA-S. Retained for compatibility with older hardware."
+            ),
+            url="https://standards-oui.ieee.org/iab/iab.csv",
+        ),
+        "ethertype": IEEERegistry(
+            enabled=True,
+            name="EtherType",
+            model=EtherTypeEntry,
+            full_name="EtherType Registry",
+            legacy_name=None,
+            category=RegCategory.PROTOCOL,
+            legacy=False,
+            description=(
+                "Registry mapping EtherType values to Ethernet protocols, "
+                "including IPv4, IPv6, ARP, VLAN tagging, LLDP, MPLS, "
+                "802.1X, and many vendor-specific protocols."
+            ),
+            url="https://standards-oui.ieee.org/ethertype/eth.csv",
+        ),
+    }
+
+    @classmethod
+    def db_is_initialized(cls):
+        db_init_checks: list[bool] = []
+        for registry in cls.IEEE_REGISTRIES.values():
+            db_init_checks.append(registry.filepath.exists())
+        if not all([check for check in db_init_checks]):
+            return False
+        return True
+
+    @staticmethod
+    def get_registry(registry_name: str) -> IEEERegistry | None:
+        return Catalog.IEEE_REGISTRIES.get(registry_name, None)
+
+    def get_all_registries(self, check_for_updates=True) -> list[IEEERegistry]:
+        for registry in self.IEEE_REGISTRIES.values():
+            # If not checking for updates, we still need a present dataset.
+            if (check_for_updates and registry.need_updates()) or not self.db_is_initialized():
+
+                status = registry.save()
+                if status is False:
+                    break
+        return list(self.IEEE_REGISTRIES.values())
+
+    def __getitem__(self, key):
+        return self.IEEE_REGISTRIES[key]

etherlyzer/ieee/csv_parser.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import csv
+from dataclasses import MISSING, fields
+from pathlib import Path
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+class IEEERegistryReader:
+
+    @staticmethod
+    def normalize(name: str) -> str:
+        return (
+            name.strip()
+            .lower()
+            .replace("-", "_")
+            .replace(" ", "_")
+        )
+
+    @staticmethod
+    def convert(value: str, typ: type) -> Any:
+        if value == "":
+            return None
+
+        if typ is int:
+            return int(value)
+
+        if typ is float:
+            return float(value)
+
+        if typ is bool:
+            return value.lower() in {
+                "true",
+                "1",
+                "yes",
+            }
+
+        return value
+
+    @classmethod
+    def load(cls, path: str | Path, model: type[T]) -> list[T]:
+        model_fields = {
+            cls.normalize(field.name): field
+            for field in fields(model)
+        }
+
+        objects: list[T] = []
+
+        with open(path, newline="", encoding="utf-8") as f:
+            reader = csv.DictReader(f)
+
+            for row in reader:
+                kwargs = {}
+                for header, value in row.items():
+                    field_name = cls.normalize(header)
+                    field = model_fields.get(field_name)
+
+                    if field is None:
+                        continue
+                    kwargs[field.name] = cls.convert(
+                        value,
+                        field.type,
+                    )
+
+                cls.validate(model_fields, kwargs)
+                objects.append(model(**kwargs))
+
+        return objects
+
+    @staticmethod
+    def validate(model_fields, kwargs):
+        missing = [
+            field.name
+            for field in model_fields.values()
+            if (field.name not in kwargs and field.default is MISSING and field.default_factory is MISSING)
+        ]
+
+        if missing: raise ValueError(f"Missing required fields: {', '.join(missing)}")

etherlyzer/ieee/index.py

@@ -0,0 +1,199 @@
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from time import sleep
+from typing import TypeVar
+
+from etherlyzer.ieee.registry import RegCategory, IEEEEntry, EtherTypeEntry, IEEERegistry
+
+HEX_DIGITS = frozenset("0123456789ABCDEF")
+
+T = TypeVar("T")
+
+
+@dataclass(slots=True)
+class MACIndex:
+    prefixes_36: dict[str, IEEEEntry] = field(default_factory=dict)
+    prefixes_28: dict[str, IEEEEntry] = field(default_factory=dict)
+    prefixes_24: dict[str, IEEEEntry] = field(default_factory=dict)
+
+    def insert(self, registry: IEEERegistry, entries: Iterable[IEEEEntry]) -> None:
+        match registry.prefix_bits:
+            case 36:
+                target = self.prefixes_36
+            case 28:
+                target = self.prefixes_28
+            case 24:
+                target = self.prefixes_24
+            case _:
+                raise ValueError(f"Unsupported prefix length: {registry.prefix_bits}")
+
+        target.update({entry.assignment.upper(): entry for entry in entries})
+
+    def lookup(self, mac: str) -> IEEEEntry | None:
+        mac = "".join(c for c in mac.upper() if c in HEX_DIGITS)
+
+        # Order is important - longest prefix match
+        return (
+                self.prefixes_36.get(mac[:9])
+                or self.prefixes_28.get(mac[:7])
+                or self.prefixes_24.get(mac[:6])
+        )
+
+    def walk(self):
+        yield from self.prefixes_36
+        yield from self.prefixes_28
+        yield from self.prefixes_24
+
+
+@dataclass(slots=True)
+class VendorIndex:
+    vendors: dict[str, list[IEEEEntry]] = field(default_factory=dict)
+
+    @staticmethod
+    def normalize_vendor_name(name: str) -> str:
+        name = name.casefold()
+        name = re.sub(r"[.,/\\()\-_'\"&]+", " ", name)
+        name = re.sub(r"\s+", " ", name)
+        return name.strip()
+
+    def insert(self, entry: IEEEEntry) -> None:
+        key = self.normalize_vendor_name(entry.organization_name)
+        self.vendors.setdefault(key, []).append(entry)
+
+    def lookup(self, vendor: str) -> list[IEEEEntry] | None:
+        ieee_mac_entries = self.vendors.get(self.normalize_vendor_name(vendor))
+        ieee_mac_entries.sort(
+            key=lambda entry: int(
+                "".join(c for c in entry.assignment if c in "0123456789ABCDEFabcdef"),
+                16,
+            )
+        )
+        return ieee_mac_entries
+
+
+@dataclass(slots=True)
+class ProtocolIndex:
+    ethertype: dict[str, EtherTypeEntry] = field(default_factory=dict)
+
+    def insert(
+            self,
+            registry: IEEERegistry,
+            entries: Iterable[EtherTypeEntry],
+    ) -> None:
+        self.ethertype.update({entry.assignment.upper(): entry for entry in entries})
+
+    def lookup(self, ethertype: str) -> EtherTypeEntry | None:
+        ethertype = "".join(c for c in ethertype.upper() if c in HEX_DIGITS)
+        return self.ethertype.get(ethertype)
+
+
+@dataclass(slots=True)
+class IdentifierIndex:
+    cid: dict[str, IEEEEntry] = field(default_factory=dict)
+    opid: dict[str, IEEEEntry] = field(default_factory=dict)
+    manid: dict[str, IEEEEntry] = field(default_factory=dict)
+
+    def insert(self, registry: IEEERegistry, entries: Iterable[IEEEEntry]) -> None:
+        match registry.name:
+            case "CID":
+                target = self.cid
+            case "OPID":
+                target = self.opid
+            case "MANID":
+                target = self.manid
+            case _:
+                raise ValueError(f"Unsupported identifier registry: {registry.name}")
+
+        target.update({entry.assignment.upper(): entry for entry in entries})
+
+    def lookup(self, identifier: str) -> IEEEEntry | None:
+        identifier = identifier.upper()
+
+        return self.cid.get(identifier) or self.opid.get(identifier) or self.manid.get(identifier)
+
+
+@dataclass(slots=True)
+class IEEEIndex:
+    mac_index: MACIndex = field(default_factory=MACIndex)
+    protocol_index: ProtocolIndex = field(default_factory=ProtocolIndex)
+    identifier_index: IdentifierIndex = field(default_factory=IdentifierIndex)
+    vendor_index: VendorIndex = field(default_factory=VendorIndex)
+
+    @classmethod
+    def from_registries(
+            cls,
+            registries: Iterable[IEEERegistry],
+    ) -> IEEEIndex:
+
+        index = cls()
+
+        for registry in registries:
+            entries = registry.load()
+
+            match registry.category:
+                case RegCategory.MAC:
+                    index.mac_index.insert(registry, entries)
+
+                case RegCategory.PROTOCOL:
+                    index.protocol_index.insert(registry, entries)
+
+                case RegCategory.IDENTIFIER:
+                    index.identifier_index.insert(registry, entries)
+
+                case _:
+                    raise ValueError(f"Unsupported registry category: {registry.category}")
+        mac_walker = index.mac_index.walk()
+        v_index = VendorIndex()
+
+        while True:
+            try:
+                entry = index.get_from_mac_index(next(mac_walker))
+                if entry is not None:
+                    v_index.insert(entry)
+            except StopIteration:
+                break
+        index.vendor_index = v_index
+        return index
+
+    def get_from_mac_index(self, mac: str) -> IEEEEntry | None:
+        return self.mac_index.lookup(mac)
+
+    def get_from_ethertype_index(self, ethertype: str) -> EtherTypeEntry | None:
+        return self.protocol_index.lookup(ethertype)
+
+    def get_identifier(self, identifier: str) -> IEEEEntry | None:
+        return self.identifier_index.lookup(identifier)
+
+    @staticmethod
+    def get_bulk(
+            ieee_index: MACIndex | IdentifierIndex | ProtocolIndex,
+            path_or_text: Path | list[str],
+    ) -> list[IEEEEntry]:
+        # Pass a list[str] from interactive or pass a Path
+        if isinstance(path_or_text, Path):
+            with open(path_or_text) as f:
+                text_data = f.readlines()
+        else:
+            text_data = path_or_text
+        ieee_entries: set[IEEEEntry] = set()
+        for line in text_data:
+            ieee_entry = ieee_index.lookup(line)
+            if ieee_entry:
+                ieee_entries.add(ieee_entry)
+
+        ieee_entries: list[IEEEEntry] = list(ieee_entries)
+        # Sort by name, and then by registry-name reversed
+        ieee_entries = sorted(ieee_entries, key=lambda e: e.organization_name)
+        ieee_entries = sorted(ieee_entries, key=lambda e: e.registry, reverse=True)
+
+        return ieee_entries
+
+    @staticmethod
+    def get_single(indextype: VendorIndex | MACIndex | IdentifierIndex | ProtocolIndex, mac: str):
+        ieee_entry = indextype.lookup(mac)
+        if ieee_entry:
+            return ieee_entry
+        else:
+            return None