snipeit-eosl 1.0.0__py3-none-any.whl

snipeit_eosl/cli.py

@@ -0,0 +1,91 @@
+"""snipeit-eosl — audit a Snipe-IT inventory against the EOSL.ai lifecycle database.
+
+Read-only. Exit codes: 0 nothing past EOSL, 1 something past EOSL (so it is usable in CI),
+2 an error occurred. The distinction matters: "the check failed to run" must never look like
+"the check passed".
+"""
+
+import argparse
+import csv
+import json
+import os
+import sys
+
+from . import eosl, report
+from .snipeit import SnipeIt, SnipeItError
+
+__version__ = "1.0.0"
+
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="snipeit-eosl",
+        description="Audit a Snipe-IT inventory against the EOSL.ai hardware lifecycle database.",
+        epilog="Credentials may also come from SNIPEIT_URL and SNIPEIT_TOKEN.",
+    )
+    p.add_argument("--url", default=os.environ.get("SNIPEIT_URL"),
+                   help="Snipe-IT base URL, e.g. https://snipe.example.com")
+    p.add_argument("--token", default=os.environ.get("SNIPEIT_TOKEN"),
+                   help="Snipe-IT API token (prefer the SNIPEIT_TOKEN env var)")
+    p.add_argument("--format", choices=("text", "json", "csv"), default="text")
+    p.add_argument("--all", action="store_true",
+                   help="include current and untracked models in the output")
+    p.add_argument("--output", "-o", help="write to a file instead of stdout")
+    p.add_argument("--timeout", type=int, default=30)
+    p.add_argument("--api-url", default=eosl.DEFAULT_API_URL,
+                   help="override the EOSL.ai lookup URL (for a mirror or an air-gapped copy)")
+    p.add_argument("--insecure", action="store_true",
+                   help="skip TLS verification for Snipe-IT (self-signed internal certs only)")
+    p.add_argument("--fail-on", choices=("never", "unsupported"), default="unsupported",
+                   help="exit 1 when models past end of service life are found (default) or never")
+    p.add_argument("--version", action="version", version="%(prog)s " + __version__)
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    if not args.url or not args.token:
+        print("error: --url and --token are required (or set SNIPEIT_URL / SNIPEIT_TOKEN)",
+              file=sys.stderr)
+        return 2
+
+    try:
+        client = SnipeIt(args.url, args.token, timeout=args.timeout, insecure=args.insecure)
+        models = client.models()
+        skus = eosl.fetch_lookup(api_url=args.api_url, timeout=args.timeout)
+    except (SnipeItError, eosl.EoslError) as e:
+        # Exit 2, never 0. An audit that could not run has not found "no problems".
+        print("error: %s" % e, file=sys.stderr)
+        return 2
+
+    if not models:
+        print("error: Snipe-IT returned no models — nothing to audit. This is reported as an error "
+              "rather than a clean result on purpose.", file=sys.stderr)
+        return 2
+
+    rep = report.build(models, skus)
+
+    if args.format == "json":
+        text = json.dumps(rep, indent=2, sort_keys=True)
+    elif args.format == "csv":
+        import io
+        buf = io.StringIO()
+        csv.writer(buf, lineterminator="\n").writerows(report.to_csv_rows(rep))
+        text = buf.getvalue()
+    else:
+        text = report.to_text(rep, show_all=args.all)
+
+    if args.output:
+        with open(args.output, "w", encoding="utf-8", newline="") as fh:
+            fh.write(text if text.endswith("\n") else text + "\n")
+        print("wrote %s" % args.output, file=sys.stderr)
+    else:
+        print(text)
+
+    if args.fail_on == "unsupported" and rep["summary"]["unsupported"]["models"]:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

snipeit_eosl/eosl.py

@@ -0,0 +1,83 @@
+"""HTTP client for the EOSL.ai lifecycle dataset. Stdlib only — no third-party dependencies.
+
+ONE FETCH, NOT N. https://eosl.ai/data/lookup.json carries every tracked part number in a single
+document (~93 KB gzipped), so auditing an inventory of any size is one round trip.
+"""
+
+import gzip
+import io
+import json
+import urllib.error
+import urllib.request
+
+from . import matching
+
+DEFAULT_API_URL = "https://eosl.ai/data/lookup.json"
+USER_AGENT = "snipeit-eosl (+https://eosl.ai/)"
+
+
+class EoslError(Exception):
+    """Raised for any failure to obtain or parse the lifecycle data."""
+
+
+def fetch_lookup(api_url=DEFAULT_API_URL, timeout=30):
+    """Fetch and parse the lifecycle lookup document. Returns the list of sku records."""
+    req = urllib.request.Request(
+        api_url,
+        headers={
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+            "Accept-Encoding": "gzip",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read()
+    except urllib.error.HTTPError as e:
+        raise EoslError("HTTP %s fetching %s" % (e.code, api_url)) from e
+    except urllib.error.URLError as e:
+        raise EoslError("could not reach %s: %s" % (api_url, e.reason)) from e
+    except Exception as e:  # noqa: BLE001 - surface the cause, never proceed on partial data
+        raise EoslError("failed fetching %s: %s" % (api_url, e)) from e
+
+    # SNIFF THE BYTES, DO NOT TRUST Content-Encoding. Some clients decompress transparently but leave
+    # the header on, so branching on the header gunzips already-plain JSON. The magic number
+    # describes what the bytes ARE, which is the only thing that matters. (This exact bug shipped in
+    # ansible-eosl and was caught only in CI.)
+    if raw[:2] == b"\x1f\x8b":
+        raw = gzip.GzipFile(fileobj=io.BytesIO(raw)).read()
+
+    try:
+        data = json.loads(raw.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError) as e:
+        raise EoslError("response from %s was not valid JSON: %s" % (api_url, e)) from e
+
+    skus = data.get("skus") if isinstance(data, dict) else None
+    if not isinstance(skus, list) or not skus:
+        # A 200 with an empty or truncated body is the exact failure that silently deleted 124
+        # families from this database in July 2026. Treat it as an error, NEVER as "no results" —
+        # otherwise every model in the inventory reports as untracked and the run looks clean.
+        raise EoslError(
+            "response from %s carried no part numbers — refusing to report an empty payload "
+            "as 'nothing tracked'" % api_url
+        )
+    return skus
+
+
+def resolve_many(parts, vendor_of=None, api_url=DEFAULT_API_URL, timeout=30, skus=None):
+    """Resolve an iterable of part numbers to normalised records.
+
+    `vendor_of` is an optional callable part -> vendor name, used only to gate vendor-specific SKU
+    aliases. Returns {part_as_supplied: record_or_None}.
+    """
+    if skus is None:
+        skus = fetch_lookup(api_url=api_url, timeout=timeout)
+    exact, loose_index = matching.build_index(skus)
+    out = {}
+    for p in parts:
+        if p is None or str(p).strip() == "":
+            continue
+        key = str(p)
+        vendor = vendor_of(key) if vendor_of else None
+        out[key] = matching.normalise(matching.match(key, vendor, exact, loose_index))
+    return out

snipeit_eosl/matching.py

@@ -0,0 +1,140 @@
+"""Pure part-number matching and record shaping — no Snipe-IT or network imports.
+
+THIS IS A DELIBERATE PORT of netbox-eosl/netbox_eosl/matching.py and
+ansible-eosl/plugins/module_utils/eosl_match.py. Three integrations resolving the same part number
+differently would be one fact with three definitions — the failure mode that produced the 844-vs-845
+homepage bug. If you change matching here, change it in both of the others.
+
+That instruction has been given twice before and is only as good as the person reading it, so it is
+now ENFORCED: `pipeline/matcher-parity-check.py` runs one battery of inputs through all three copies
+and fails CI if any of them disagrees. Do not delete that check to make a change land.
+
+Matching is deterministic and conservative: exact, then a punctuation/case-insensitive "loose" match,
+then a *vendor-gated* SKU-abbreviation expansion. Never fuzzy, never substring — 'WS-C3850' must not
+resolve to 'WS-C3850-24T-L', and an unknown part returns None rather than a near neighbour. A wrong
+end-of-life date on the wrong device would defeat the point of a source-backed tool.
+"""
+
+import datetime
+import re
+
+# Official Fortinet SKU-abbreviation -> product-line prefixes. EOSL.ai stores the long form
+# ("FortiGate-60E"); inventories commonly carry the short SKU form ("FG-60E").
+FORTINET_PREFIX = {
+    "FG": "FORTIGATE",
+    "FS": "FORTISWITCH",
+    "FAP": "FORTIAP",
+    "FAZ": "FORTIANALYZER",
+    "FMG": "FORTIMANAGER",
+    "FWB": "FORTIWEB",
+    "FAD": "FORTIADC",
+    "FML": "FORTIMAIL",
+    "FPX": "FORTIPROXY",
+    "FEX": "FORTIEXTENDER",
+    "FAC": "FORTIAUTHENTICATOR",
+    "FDD": "FORTIDDOS",
+    "FSA": "FORTISANDBOX",
+}
+
+BASE_URL = "https://eosl.ai"
+
+
+def loose(s):
+    """Uppercase, strip every non-alphanumeric char. 'FortiGate-60E' -> 'FORTIGATE60E'."""
+    return re.sub(r"[^A-Z0-9]", "", (s or "").upper())
+
+
+def build_index(skus):
+    """Return (exact, loose_index): UPPER(pid)->rec and loose(pid)->rec. First writer wins."""
+    exact, loose_index = {}, {}
+    for rec in skus:
+        pid = (rec.get("p") or "").strip().upper()
+        if not pid:
+            continue
+        exact.setdefault(pid, rec)
+        loose_index.setdefault(loose(pid), rec)
+    return exact, loose_index
+
+
+def _is_fortinet(vendor):
+    return bool(vendor) and "FORTINET" in vendor.upper()
+
+
+def candidate_loose_keys(part, vendor=None):
+    """Loose keys to try, most-specific first. Vendor-gated aliases only; deterministic, never fuzzy."""
+    keys, seen = [], set()
+
+    def add(raw):
+        k = loose(raw)
+        if k and k not in seen:
+            seen.add(k)
+            keys.append(k)
+
+    add(part)
+    if _is_fortinet(vendor):
+        lp = loose(part)
+        for ab, full in FORTINET_PREFIX.items():
+            if lp.startswith(ab) and len(lp) > len(ab) and not lp.startswith(full):
+                add(full + lp[len(ab):])
+    return keys
+
+
+def match(part, vendor, exact, loose_index):
+    """Resolve a part number to a record, or None. Exact -> loose -> vendor-gated alias."""
+    if not part:
+        return None
+    u = part.strip().upper()
+    if u in exact:
+        return exact[u]
+    for k in candidate_loose_keys(part, vendor):
+        rec = loose_index.get(k)
+        if rec:
+            return rec
+    return None
+
+
+def normalise(rec):
+    """Expand a compact lookup record into documented, stable field names.
+
+    The wire format is abbreviated to keep the single-fetch payload small; users should never have to
+    know that 'xb' means the support-runway band.
+    """
+    if rec is None:
+        return None
+    slug = rec.get("s")
+    out = {
+        "part_number": rec.get("p"),
+        "family": rec.get("f"),
+        "vendor": rec.get("v"),
+        "slug": slug,
+        "end_of_sale": rec.get("eos") or None,
+        "end_of_service_life": rec.get("eol") or None,
+        "active": bool(rec.get("a")),
+        "support_runway_score": rec.get("xs"),
+        "support_runway_band": rec.get("xb"),
+        "source_url": rec.get("src") or None,
+        "cisa_bod_26_02_scope": bool(rec.get("bd")),
+        "url": "%s/system/%s/" % (BASE_URL, slug) if slug else None,
+    }
+    out["status"] = status_of(out)
+    return out
+
+
+def status_of(item, today=None):
+    """'active' | 'unsupported' | 'supported' | 'unknown' — from the dates alone, never guessed.
+
+    'active' means the manufacturer has announced no end of life. 'unknown' means this database holds
+    no end-of-service-life date for the part, which is NOT the same as "still supported" and must
+    never be rendered as though it were.
+    """
+    if item is None:
+        return "unknown"
+    if item.get("active"):
+        return "active"
+    eol = item.get("end_of_service_life")
+    if not eol:
+        return "unknown"
+    today = today or datetime.date.today()
+    # Dates are 'YYYY-MM' precision in the lookup payload; compare on that precision only rather
+    # than inventing a day-of-month.
+    return "unsupported" if eol <= today.strftime("%Y-%m") else "supported"

snipeit_eosl/report.py

@@ -0,0 +1,160 @@
+"""Turn Snipe-IT models + EOSL.ai records into an audit report. Pure — no network, no I/O."""
+
+import datetime
+
+from . import matching
+
+# Order matters: this is the order rows are presented and the order a human should act in.
+BUCKETS = ["unsupported", "supported", "active", "unknown"]
+
+BUCKET_LABEL = {
+    "unsupported": "Past end of service life",
+    "supported": "Tracked, still supported",
+    # ASCII ONLY in anything printed: this is a CLI, and a Windows cp1252 console renders an
+    # em-dash as a replacement character. Guarded by test_text_output_is_ascii.
+    "active": "Current - no EOL announced",
+    "unknown": "Not tracked by EOSL.ai",
+}
+
+
+def plural(n, word):
+    """'1 unit' / '2 units'. Trivial, but wrong grammar in a report reads as a careless tool."""
+    return word if n == 1 else word + "s"
+
+
+def _candidates(model):
+    """Part-number candidates for a Snipe-IT model, most authoritative first.
+
+    `model_number` is the field Snipe-IT intends for this. `name` is tried second because a great
+    many real Snipe-IT installs leave model_number blank and put "WS-C3850-24T-L" in the name — but
+    it is a fallback, and which one matched is reported so the result stays auditable.
+    """
+    out = []
+    for field in ("model_number", "name"):
+        v = (model.get(field) or "").strip()
+        if v:
+            out.append((field, v))
+    return out
+
+
+def build(models, skus, today=None):
+    """Return {'rows': [...], 'summary': {...}}.
+
+    One row per Snipe-IT model. `matched_on` records which field resolved, and `status` is computed
+    by the shared matcher — never recomputed here.
+    """
+    today = today or datetime.date.today()
+    exact, loose_index = matching.build_index(skus)
+    rows = []
+
+    for m in models:
+        rec, matched_on, tried = None, None, []
+        for field, value in _candidates(m):
+            tried.append(value)
+            hit = matching.match(value, m.get("manufacturer"), exact, loose_index)
+            if hit is not None:
+                rec, matched_on = matching.normalise(hit), field
+                break
+
+        status = matching.status_of(rec, today=today) if rec else "unknown"
+        rows.append(
+            {
+                "snipeit_model_id": m.get("id"),
+                "snipeit_model": m.get("name"),
+                "manufacturer": m.get("manufacturer"),
+                "category": m.get("category"),
+                "assets": m.get("assets_count") or 0,
+                "matched_on": matched_on,
+                "queried": tried,
+                "status": status,
+                "part_number": rec["part_number"] if rec else None,
+                "end_of_sale": rec["end_of_sale"] if rec else None,
+                "end_of_service_life": rec["end_of_service_life"] if rec else None,
+                "support_runway_band": rec["support_runway_band"] if rec else None,
+                "source_url": rec["source_url"] if rec else None,
+                "url": rec["url"] if rec else None,
+            }
+        )
+
+    # Sort: worst first, then by unit count — the biggest exposure at the top of the page.
+    rows.sort(key=lambda r: (BUCKETS.index(r["status"]), -(r["assets"] or 0), r["snipeit_model"] or ""))
+
+    summary = {b: {"models": 0, "assets": 0} for b in BUCKETS}
+    for r in rows:
+        s = summary[r["status"]]
+        s["models"] += 1
+        s["assets"] += r["assets"] or 0
+    summary["total_models"] = len(rows)
+    summary["total_assets"] = sum(r["assets"] or 0 for r in rows)
+    return {"rows": rows, "summary": summary}
+
+
+def to_text(report, show_all=False):
+    """Human-readable report. Returns a string."""
+    rows, summary = report["rows"], report["summary"]
+    out = []
+    out.append("EOSL.ai audit of Snipe-IT inventory")
+    out.append("=" * 62)
+    for b in BUCKETS:
+        s = summary[b]
+        if s["models"]:
+            out.append("  %-30s %4d %-6s %5d %s" % (BUCKET_LABEL[b], s["models"], plural(s["models"], "model"), s["assets"], plural(s["assets"], "unit")))
+    out.append("  %-30s %4d %-6s %5d %s" % ("TOTAL", summary["total_models"], plural(summary["total_models"], "model"), summary["total_assets"], plural(summary["total_assets"], "unit")))
+    out.append("")
+
+    shown = rows if show_all else [r for r in rows if r["status"] in ("unsupported", "supported")]
+    if not shown:
+        out.append("Nothing tracked matched this inventory.")
+        # Never let "we matched nothing" read as "you are fine".
+        if summary["unknown"]["models"]:
+            out.append(
+                "NOTE: %d models are not tracked by EOSL.ai. That is not the same as supported - "
+                "it means this database holds no date for them." % summary["unknown"]["models"]
+            )
+        return "\n".join(out)
+
+    for b in BUCKETS:
+        sub = [r for r in shown if r["status"] == b]
+        if not sub:
+            continue
+        out.append("%s (%d)" % (BUCKET_LABEL[b].upper(), len(sub)))
+        out.append("-" * 62)
+        for r in sub:
+            out.append(
+                "  %-28s %4d unit%s  EOS %-8s EOSL %-8s"
+                % (
+                    (r["snipeit_model"] or "")[:28],
+                    r["assets"],
+                    " " if r["assets"] == 1 else "s",
+                    r["end_of_sale"] or "-",
+                    r["end_of_service_life"] or "-",
+                )
+            )
+            if r["source_url"]:
+                out.append("      source: %s" % r["source_url"])
+        out.append("")
+
+    if not show_all and summary["unknown"]["models"]:
+        out.append(
+            "%d model(s) are not tracked by EOSL.ai - not the same as supported. Use --all to list them."
+            % summary["unknown"]["models"]
+        )
+    return "\n".join(out)
+
+
+def to_csv_rows(report):
+    """Return [header, *rows] as lists of strings, for csv.writer."""
+    header = [
+        "snipeit_model", "manufacturer", "category", "assets", "status",
+        "part_number", "matched_on", "end_of_sale", "end_of_service_life",
+        "support_runway_band", "source_url", "eosl_ai_url",
+    ]
+    out = [header]
+    for r in report["rows"]:
+        out.append([
+            r["snipeit_model"] or "", r["manufacturer"] or "", r["category"] or "",
+            str(r["assets"]), r["status"], r["part_number"] or "", r["matched_on"] or "",
+            r["end_of_sale"] or "", r["end_of_service_life"] or "",
+            r["support_runway_band"] or "", r["source_url"] or "", r["url"] or "",
+        ])
+    return out

snipeit_eosl/snipeit.py

@@ -0,0 +1,130 @@
+"""Read-only Snipe-IT API client. Stdlib only.
+
+WHY MODELS AND NOT ASSETS. Snipe-IT stores the part number on the *model* (`model_number`), and every
+asset points at one. A 4,000-device estate is typically 40-200 models, so walking `/api/v1/models`
+answers "what do I own that is end-of-life" in a handful of requests instead of paging thousands of
+assets to read the same field over and over. `assets_count` on each model gives the unit counts for
+free. If you need per-asset detail, `--assets` widens the walk deliberately.
+
+THIS CLIENT NEVER WRITES. Snipe-IT is a system of record and a tool that silently edits one is a tool
+nobody should run against production. Write-back to a custom field was considered and deliberately
+left out — see README, "What this does not do".
+"""
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+
+USER_AGENT = "snipeit-eosl (+https://eosl.ai/)"
+PAGE = 100
+# A real Snipe-IT can hold a lot of models; this is a runaway-loop backstop, not a coverage limit.
+MAX_PAGES = 500
+
+
+class SnipeItError(Exception):
+    """Raised for any failure to obtain or parse data from Snipe-IT."""
+
+
+class SnipeIt:
+    def __init__(self, base_url, token, timeout=30, insecure=False):
+        if not base_url:
+            raise SnipeItError("a Snipe-IT base URL is required")
+        if not token:
+            raise SnipeItError("a Snipe-IT API token is required")
+        self.base = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self.insecure = insecure
+
+    def _get(self, path, params=None):
+        url = "%s/api/v1/%s" % (self.base, path.lstrip("/"))
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+        req = urllib.request.Request(
+            url,
+            headers={
+                "Authorization": "Bearer %s" % self.token,
+                "Accept": "application/json",
+                "User-Agent": USER_AGENT,
+            },
+        )
+        ctx = None
+        if self.insecure:
+            import ssl
+
+            ctx = ssl._create_unverified_context()
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout, context=ctx) as resp:
+                raw = resp.read()
+        except urllib.error.HTTPError as e:
+            hint = ""
+            if e.code in (401, 403):
+                hint = " — check the API token and that it has read access"
+            raise SnipeItError("HTTP %s from %s%s" % (e.code, url, hint)) from e
+        except urllib.error.URLError as e:
+            raise SnipeItError("could not reach %s: %s" % (url, e.reason)) from e
+
+        try:
+            data = json.loads(raw.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError) as e:
+            raise SnipeItError("response from %s was not valid JSON: %s" % (url, e)) from e
+
+        # Snipe-IT answers some auth and validation failures with HTTP 200 and a body of
+        # {"status":"error","messages":...}. Treating that as an empty result set is how a broken
+        # token turns into a clean-looking "no models found" report.
+        if isinstance(data, dict) and data.get("status") == "error":
+            raise SnipeItError("Snipe-IT returned an error for %s: %s" % (url, data.get("messages")))
+        return data
+
+    def _paged(self, path, params=None):
+        """Walk a paginated Snipe-IT collection, yielding rows."""
+        offset, seen, total = 0, 0, None
+        for _ in range(MAX_PAGES):
+            p = dict(params or {})
+            p.update({"limit": PAGE, "offset": offset})
+            data = self._get(path, p)
+            rows = data.get("rows")
+            if rows is None:
+                raise SnipeItError("unexpected response shape from %s: no 'rows'" % path)
+            if total is None:
+                total = data.get("total")
+            for r in rows:
+                yield r
+            seen += len(rows)
+            if not rows or (total is not None and seen >= total):
+                break
+            # ADVANCE BY WHAT WAS RETURNED, NOT BY PAGE. Snipe-IT clamps `limit` server-side to its
+            # `max_results` setting (config/app.php, default 500 but admin-configurable via
+            # MAX_RESULTS). On an instance capped below PAGE, `offset += PAGE` would step straight
+            # over the rows the server withheld. Found by reading AssetModelsController rather than
+            # by testing, because the mock in the test suite answered with whatever it was told to.
+            offset += len(rows)
+        else:
+            raise SnipeItError("pagination did not terminate after %d pages of %s" % (MAX_PAGES, path))
+
+        # A truncated walk that reports success is the IBM failure in a different costume: every
+        # model we never saw would silently read as "not in your inventory".
+        if total is not None and seen < total:
+            raise SnipeItError(
+                "only retrieved %d of %d rows from %s — refusing to report a partial inventory"
+                % (seen, total, path)
+            )
+
+    def models(self):
+        """Return [{id, name, model_number, manufacturer, category, assets_count}]."""
+        out = []
+        for r in self._paged("models"):
+            man = r.get("manufacturer") or {}
+            cat = r.get("category") or {}
+            out.append(
+                {
+                    "id": r.get("id"),
+                    "name": (r.get("name") or "").strip(),
+                    "model_number": (r.get("model_number") or "").strip(),
+                    "manufacturer": (man.get("name") or "").strip() if isinstance(man, dict) else "",
+                    "category": (cat.get("name") or "").strip() if isinstance(cat, dict) else "",
+                    "assets_count": r.get("assets_count") or 0,
+                }
+            )
+        return out

snipeit_eosl-1.0.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: snipeit-eosl
+Version: 1.0.0
+Summary: Audit a Snipe-IT inventory against the EOSL.ai hardware end-of-service-life database.
+Author-email: "EOSL.ai" <hello@eosl.ai>
+License: Apache-2.0
+Project-URL: Homepage, https://eosl.ai
+Project-URL: Source, https://github.com/EOSL-AI/snipeit-eosl
+Project-URL: Issues, https://github.com/EOSL-AI/snipeit-eosl/issues
+Project-URL: Dataset, https://eosl.ai/dataset/
+Keywords: snipe-it,snipeit,itam,asset-management,eol,eosl,end-of-life,lifecycle
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# snipeit-eosl
+
+Audit a [Snipe-IT](https://snipeitapp.com/) inventory against the
+[EOSL.ai](https://eosl.ai) hardware end-of-service-life database.
+
+Snipe-IT knows what hardware you own. It does not know when the manufacturer stops supporting it.
+This tells you, and links the manufacturer's own bulletin for every date so you can check it.
+
+**Read-only. Zero dependencies. One HTTP request to EOSL.ai regardless of inventory size.**
+
+```
+$ snipeit-eosl --url https://snipe.example.com
+
+EOSL.ai audit of Snipe-IT inventory
+==============================================================
+  Past end of service life          3 models    129 units
+  Tracked, still supported          2 models     18 units
+  Not tracked by EOSL.ai            3 models     13 units
+  TOTAL                             8 models    160 units
+
+PAST END OF SERVICE LIFE (3)
+--------------------------------------------------------------
+  Catalyst 3850 24-port          40 units  EOS 2020-10 EOSL 2025-10
+      source: https://www.cisco.com/c/en/us/products/collateral/...
+  MR33-HW                        85 units  EOS 2021-05 EOSL 2026-07
+      source: https://documentation.meraki.com/...
+```
+
+## Install
+
+```bash
+pip install snipeit-eosl
+```
+
+## Use
+
+Generate an API token in Snipe-IT under **Account → API Keys**. A read-only user is enough.
+
+```bash
+export SNIPEIT_URL=https://snipe.example.com
+export SNIPEIT_TOKEN=eyJ0eXAi...
+
+snipeit-eosl                       # human-readable summary
+snipeit-eosl --all                 # include current and untracked models
+snipeit-eosl --format csv -o eol-audit.csv
+snipeit-eosl --format json | jq '.rows[] | select(.status=="unsupported")'
+```
+
+**Exit codes:** `0` nothing past end of service life · `1` something is · `2` the audit could not run.
+That third one matters: a failed audit must never be mistakable for a clean one. Use it in CI:
+
+```yaml
+- run: snipeit-eosl        # fails the job when EOL hardware appears in the inventory
+```
+
+## How matching works
+
+Deterministic and conservative, in this order:
+
+1. **Exact** match on the part number.
+2. **Loose** match ignoring case and punctuation — `ws c3850 24t l` finds `WS-C3850-24T-L`.
+3. **Vendor-gated alias** — `FG-60E` finds `FortiGate-60E`, but *only* when the Snipe-IT manufacturer
+   is Fortinet, so one vendor's SKU can never land on another vendor's record.
+
+**It never fuzzy- or substring-matches.** `WS-C3850` does not resolve to `WS-C3850-24T-L`. An unknown
+part returns nothing rather than a plausible neighbour, because a confident wrong end-of-life date is
+worse than no date.
+
+It reads `model_number` first and falls back to the model `name`, since many real installs leave
+`model_number` blank. Which field matched is reported in `matched_on`, so a result is always
+traceable.
+
+### Snipe-IT already has an "EOL" field. It does not mean this.
+
+Snipe-IT models carry their own `eol` value, and its API returns it as a string like `"36 months"`.
+That is a **depreciation-style estimate of useful life measured from purchase** — a number somebody
+at your organisation typed in. It is not a manufacturer date and it has no source behind it.
+
+This tool reports the **manufacturer's published end-of-service-life date**, with a link to the
+bulletin it came from. The two answer different questions, and the built-in field is the one people
+mistake for this. `snipeit-eosl` reads it never and writes it never.
+
+### "Not tracked" is not "supported"
+
+Models EOSL.ai has no record for are reported as **unknown**, never folded in with the healthy ones.
+It means this database holds no date for that part — not that the part is fine. The tooling says so
+in every output format on purpose.
+
+## What this does not do
+
+- **It never writes to Snipe-IT.** Snipe-IT is a system of record, and a tool that quietly edits one
+  is a tool nobody should point at production. Write-back into a custom field was considered and
+  deliberately left out.
+- **It does not warrant the dates.** Every record links the manufacturer's bulletin. That bulletin
+  governs; this is a convenience layer over it.
+- **It does not invent dates.** If a manufacturer has published nothing, nothing is shown.
+
+## Related integrations
+
+Same data, same matching logic, different place to stand:
+
+- **[netbox-eosl](https://github.com/EOSL-AI/netbox-eosl)** — NetBox plugin
+- **[ansible-eosl](https://github.com/EOSL-AI/ansible-eosl)** — `eosl.lifecycle` Ansible collection
+- **[EOSL.ai API](https://eosl.ai/api/)** — public JSON API, MCP server, and CC BY dataset
+
+## Licence
+
+Apache-2.0. The underlying dataset is **CC BY 4.0** — free for commercial use with attribution.

snipeit_eosl-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+snipeit_eosl/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+snipeit_eosl/cli.py,sha256=1Ve3oQMS4AC959jMfD63BOIkG83lkuSZ-LG6CO1Rg4Q,3607
+snipeit_eosl/eosl.py,sha256=99EkNwbUl7_joP_2bne1CfnRnVzsNpaB0LPr_NpzYMA,3401
+snipeit_eosl/matching.py,sha256=-k2qU0Rm4j0Ryjga-y_PcimzsAwNu3XrasS905ZSoWI,5003
+snipeit_eosl/report.py,sha256=RV_GDuz_2eHK87_WohZruwSb_28PnkvuQcyTerqXjiM,6494
+snipeit_eosl/snipeit.py,sha256=3Z8lCPdNTxeThL1gS_FR4vbYOjnWDIVqFc1awXKE6vY,5802
+snipeit_eosl-1.0.0.dist-info/licenses/LICENSE,sha256=8MIt5rjpYpxzEFylDddz-WQ2oRwJsICB38D4rJZMTME,11337
+snipeit_eosl-1.0.0.dist-info/METADATA,sha256=PMgiETlu7GUCf4MjJzXYn6a0RriEbutebW7RoVpmRxM,5685
+snipeit_eosl-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+snipeit_eosl-1.0.0.dist-info/entry_points.txt,sha256=YONtX2Nt1tcSod70rN2eyKYAXmri79tEHdoaRf6hG6c,55
+snipeit_eosl-1.0.0.dist-info/top_level.txt,sha256=BAG-bYhnB-ca_QSjJSA9C64GZTWh_e1PT9ye44Kstdk,13
+snipeit_eosl-1.0.0.dist-info/RECORD,,

snipeit_eosl-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

snipeit_eosl-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+snipeit-eosl = snipeit_eosl.cli:main

snipeit_eosl-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions for
+      use, reproduction, or distribution of Your modifications, or for any
+      such Derivative Works as a whole, provided Your use, reproduction,
+      and distribution of the Work otherwise complies with the conditions
+      stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 EOSL.ai
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

snipeit_eosl-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+snipeit_eosl