nrdax 0.1.0__py3-none-any.whl

nrdax/__init__.py

@@ -0,0 +1,114 @@
+"""nrdax - the open-source Python library and CLI for the NRDAX registry.
+
+NRDAX (NullRabbit Decentralised Attack indeX) is NullRabbit's canonical,
+chain-agnostic registry of techniques for attacks on decentralised infrastructure.
+This package is the standard programmatic interface to the public NRDAX dataset:
+load it, search and filter it, traverse relationships, export it (JSON / CSV /
+STIX), cite it, and inspect changes.
+
+Quick start::
+
+    from nrdax import NRDAX
+    registry = NRDAX.load()                 # bundled snapshot, offline
+    technique = registry.get("NRDAX-T0006")
+    results = registry.search("rpc exhaustion")
+    related = registry.related("NRDAX-T0006")
+
+The CLI (``nrdax``) is built entirely on this library.
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .citations import CitationData, cite
+from .errors import (
+    DataFormatError,
+    ExitCode,
+    InvalidArgumentError,
+    NotFoundError,
+    NrdaxError,
+    SchemaVersionError,
+    SourceError,
+    ValidationError,
+    ValidationIssue,
+)
+from .models import (
+    CoverageCell,
+    CoverageMatrix,
+    ExternalReference,
+    FamilyCount,
+    Instance,
+    KnownCell,
+    KnownCoverage,
+    Technique,
+)
+from .queries.search import SearchResult
+from .registry import NRDAX
+from .relationships import RelatedResult
+from .sources import RawDataset, Source, SourceMeta
+from .sources.api import ApiSource
+from .sources.bundled import BundledSource
+from .sources.feed import FeedSource
+from .sources.file import FileSource
+from .sources.memory import MemorySource
+from .sources.stix import StixSource
+from .vocab import (
+    DISCOVERY_ORIGINS,
+    FAMILIES,
+    FIDELITY_CLASSES,
+    NRDAX_API,
+    NRDAX_SCHEMA_VERSION,
+    NRDAX_SITE,
+    REFERENCE_KINDS,
+    REPRODUCTION_STATUSES,
+    STATUSES,
+)
+
+__all__ = [
+    "__version__",
+    # facade
+    "NRDAX",
+    # models
+    "Technique",
+    "Instance",
+    "ExternalReference",
+    "KnownCoverage",
+    "CoverageMatrix",
+    "CoverageCell",
+    "KnownCell",
+    "FamilyCount",
+    "SearchResult",
+    "RelatedResult",
+    "CitationData",
+    "cite",
+    # sources
+    "Source",
+    "RawDataset",
+    "SourceMeta",
+    "BundledSource",
+    "FeedSource",
+    "ApiSource",
+    "FileSource",
+    "StixSource",
+    "MemorySource",
+    # errors
+    "NrdaxError",
+    "NotFoundError",
+    "InvalidArgumentError",
+    "SourceError",
+    "DataFormatError",
+    "SchemaVersionError",
+    "ValidationError",
+    "ValidationIssue",
+    "ExitCode",
+    # vocab
+    "FAMILIES",
+    "STATUSES",
+    "FIDELITY_CLASSES",
+    "DISCOVERY_ORIGINS",
+    "REFERENCE_KINDS",
+    "REPRODUCTION_STATUSES",
+    "NRDAX_SCHEMA_VERSION",
+    "NRDAX_SITE",
+    "NRDAX_API",
+]

nrdax/_version.py

@@ -0,0 +1,10 @@
+"""Single source of truth for the package version.
+
+Kept distinct from the *dataset* version (which comes from the loaded registry's
+``index.json``) and the *schema* version (``nrdax.vocab.NRDAX_SCHEMA_VERSION``).
+See ``docs/data-model.md`` for the versioning policy.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

nrdax/cache.py

@@ -0,0 +1,141 @@
+"""Local snapshot cache for offline and pinned use.
+
+``nrdax update`` writes the fetched dataset here; subsequent commands load it so
+work continues offline. Nothing is hidden: :func:`info` reports the cached version
+and fetch time so stale data is always visible, and ``nrdax cache clear`` removes
+it. Location precedence: ``$NRDAX_CACHE_DIR`` → ``$XDG_CACHE_HOME/nrdax`` →
+``~/.cache/nrdax`` (``%LOCALAPPDATA%\\nrdax`` on Windows).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from pathlib import Path
+from typing import Any
+
+from .sources import RawDataset, SourceMeta
+
+_META = "meta.json"
+_JSONL = "registry.jsonl"
+_KNOWN = "known_coverage.json"
+_FAMILIES = "families.json"
+
+
+def cache_dir() -> Path:
+    override = os.environ.get("NRDAX_CACHE_DIR")
+    if override:
+        return Path(override)
+    if os.name == "nt":  # pragma: no cover - platform dependent
+        win_base = os.environ.get("LOCALAPPDATA") or os.path.expanduser("~")
+        return Path(win_base) / "nrdax"
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".cache"
+    return base / "nrdax"
+
+
+def snapshot_dir() -> Path:
+    return cache_dir() / "snapshot"
+
+
+def has_snapshot() -> bool:
+    d = snapshot_dir()
+    return (d / _META).is_file() and (d / _JSONL).is_file()
+
+
+def write_snapshot(raw: RawDataset) -> Path:
+    """Persist ``raw`` to the cache and return the snapshot directory."""
+    d = snapshot_dir()
+    d.mkdir(parents=True, exist_ok=True)
+
+    with (d / _JSONL).open("w", encoding="utf-8") as fh:
+        for tech in raw.techniques:
+            fh.write(json.dumps(tech, separators=(",", ":"), ensure_ascii=False))
+            fh.write("\n")
+
+    (d / _KNOWN).write_text(json.dumps(raw.known_coverage, ensure_ascii=False), encoding="utf-8")
+    if raw.families is not None:
+        (d / _FAMILIES).write_text(
+            json.dumps({"families": raw.families}, ensure_ascii=False), encoding="utf-8"
+        )
+
+    src = raw.meta
+    meta = {
+        "version": raw.version,
+        "doi": raw.doi,
+        "technique_count": len(raw.techniques),
+        "fetched_at": src.fetched_at if src else None,
+        "source_kind": src.kind if src else "unknown",
+        "source_location": src.location if src else "unknown",
+    }
+    (d / _META).write_text(json.dumps(meta, indent=2, ensure_ascii=False), encoding="utf-8")
+    return d
+
+
+def read_snapshot() -> RawDataset:
+    """Load the cached snapshot into a :class:`RawDataset`."""
+    from .sources.feed import read_jsonl  # local import avoids a cycle at import time
+
+    d = snapshot_dir()
+    meta = json.loads((d / _META).read_text(encoding="utf-8"))
+    techniques = read_jsonl((d / _JSONL).read_text(encoding="utf-8"))
+    known = []
+    if (d / _KNOWN).is_file():
+        known = json.loads((d / _KNOWN).read_text(encoding="utf-8"))
+    families = None
+    if (d / _FAMILIES).is_file():
+        families = json.loads((d / _FAMILIES).read_text(encoding="utf-8")).get("families")
+
+    location = f"{meta.get('source_kind', '?')}:{meta.get('source_location', '?')}"
+    return RawDataset(
+        version=meta.get("version", "cache"),
+        doi=meta.get("doi"),
+        techniques=techniques,
+        known_coverage=known,
+        families=families,
+        meta=SourceMeta(kind="cache", location=location, fetched_at=meta.get("fetched_at")),
+    )
+
+
+def clear() -> bool:
+    """Remove the cache directory. Returns ``True`` if anything was removed."""
+    d = cache_dir()
+    if d.exists():
+        shutil.rmtree(d)
+        return True
+    return False
+
+
+def _dir_size(path: Path) -> int:
+    return sum(f.stat().st_size for f in path.rglob("*") if f.is_file())
+
+
+def info() -> dict[str, Any]:
+    """A summary of cache state for ``nrdax cache info`` / ``nrdax info``."""
+    d = snapshot_dir()
+    present = has_snapshot()
+    out: dict[str, Any] = {
+        "cache_dir": str(cache_dir()),
+        "snapshot_present": present,
+    }
+    if present:
+        meta = json.loads((d / _META).read_text(encoding="utf-8"))
+        out.update(
+            {
+                "version": meta.get("version"),
+                "doi": meta.get("doi"),
+                "technique_count": meta.get("technique_count"),
+                "fetched_at": meta.get("fetched_at"),
+                "source": f"{meta.get('source_kind')}:{meta.get('source_location')}",
+                "size_bytes": _dir_size(d),
+            }
+        )
+    return out
+
+
+class CacheSource:
+    """Load the cached snapshot as a source (used as the default when present)."""
+
+    def load(self) -> RawDataset:
+        return read_snapshot()

nrdax/changes.py

@@ -0,0 +1,137 @@
+"""Change inspection.
+
+NRDAX does not (yet) publish historical versioned releases addressable by version
+number, so cross-version comparison is implemented as a **real diff between two
+datasets the caller supplies** (two snapshots, cache vs current, bundled vs live) —
+never simulated. ``since`` derives "added since a date" from ``first_seen``, which
+*is* available on every record. See ``docs/guides/compare-changes.md`` for the
+source limitation and how to pin snapshots for reproducible diffs.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from .models import Technique
+
+if TYPE_CHECKING:
+    from .registry import NRDAX
+
+Predicate = Callable[[Technique], bool]
+
+_ADVISORY_KINDS = frozenset({"cve", "ghsa", "vendor-advisory", "nr-advisory"})
+
+
+@dataclass(frozen=True)
+class Change:
+    kind: str  # e.g. "technique_added", "status_changed", "advisory_added"
+    technique_id: str
+    detail: str
+    old: str | None = None
+    new: str | None = None
+
+
+@dataclass
+class ChangeSet:
+    from_version: str
+    to_version: str
+    changes: list[Change] = field(default_factory=list)
+
+    def counts_by_kind(self) -> dict[str, int]:
+        out: dict[str, int] = {}
+        for c in self.changes:
+            out[c.kind] = out.get(c.kind, 0) + 1
+        return dict(sorted(out.items()))
+
+    def __len__(self) -> int:
+        return len(self.changes)
+
+
+def _refs(t: Technique) -> set[tuple[str, str]]:
+    return {(ref.kind, ref.id) for _, ref in t.iter_references()}
+
+
+def _instances(t: Technique) -> dict[tuple[str, str], str]:
+    # (chain, primitive_id) -> fidelity
+    return {(i.chain, i.primitive_id): i.fidelity for i in t.instances}
+
+
+def _diff_pair(old: Technique, new: Technique, out: list[Change]) -> None:
+    tid = new.id
+    if old.display != new.display:
+        out.append(Change("name_changed", tid, "display name changed", old.display, new.display))
+    if old.family != new.family:
+        out.append(Change("family_changed", tid, "family changed", old.family, new.family))
+    if old.status != new.status:
+        out.append(Change("status_changed", tid, "status changed", old.status, new.status))
+    if old.first_seen != new.first_seen:
+        out.append(
+            Change("first_seen_changed", tid, "first_seen changed", old.first_seen, new.first_seen)
+        )
+    if old.reproduction_status != new.reproduction_status:
+        out.append(
+            Change(
+                "reproduction_status_changed",
+                tid,
+                "reproduction status changed",
+                old.reproduction_status,
+                new.reproduction_status,
+            )
+        )
+
+    old_inst, new_inst = _instances(old), _instances(new)
+    for key in sorted(new_inst.keys() - old_inst.keys()):
+        out.append(
+            Change("instance_added", tid, f"instance added on {key[0]} ({key[1]})", new=key[1])
+        )
+    for key in sorted(old_inst.keys() - new_inst.keys()):
+        out.append(
+            Change("instance_removed", tid, f"instance removed on {key[0]} ({key[1]})", old=key[1])
+        )
+
+    old_chains, new_chains = set(old.chains), set(new.chains)
+    for chain in sorted(new_chains - old_chains):
+        out.append(Change("chain_added", tid, f"chain added: {chain}", new=chain))
+
+    old_refs, new_refs = _refs(old), _refs(new)
+    for kind, rid in sorted(new_refs - old_refs):
+        if kind in _ADVISORY_KINDS:
+            out.append(Change("advisory_added", tid, f"advisory linked: {rid} ({kind})", new=rid))
+        elif kind == "nr-brief":
+            out.append(Change("brief_added", tid, f"research brief linked: {rid}", new=rid))
+        else:
+            out.append(Change("reference_added", tid, f"reference added: {rid} ({kind})", new=rid))
+    for kind, rid in sorted(old_refs - new_refs):
+        out.append(Change("reference_removed", tid, f"reference removed: {rid} ({kind})", old=rid))
+
+
+def diff(old: NRDAX, new: NRDAX, *, predicate: Predicate | None = None) -> ChangeSet:
+    """Compute the changes from ``old`` to ``new`` (optionally filtered to
+    techniques matching ``predicate``)."""
+    keep = predicate or (lambda _t: True)
+    old_ids = {t.id for t in old if keep(t)}
+    new_ids = {t.id for t in new if keep(t)}
+    changes: list[Change] = []
+
+    for tid in sorted(new_ids - old_ids):
+        t = new.get(tid)
+        changes.append(Change("technique_added", tid, f"technique added: {t.display}"))
+    for tid in sorted(old_ids - new_ids):
+        t = old.get(tid)
+        changes.append(Change("technique_removed", tid, f"technique removed: {t.display}"))
+    for tid in sorted(old_ids & new_ids):
+        _diff_pair(old.get(tid), new.get(tid), changes)
+
+    changes.sort(key=lambda c: (c.technique_id, c.kind, c.detail))
+    return ChangeSet(from_version=old.version, to_version=new.version, changes=changes)
+
+
+def since(registry: NRDAX, date: str, *, predicate: Predicate | None = None) -> list[Technique]:
+    """Techniques first seen on or after ``date`` (``YYYY-MM-DD``), sorted by
+    ``first_seen`` then id."""
+    keep = predicate or (lambda _t: True)
+    hits = [t for t in registry if keep(t) and t.first_seen and t.first_seen >= date]
+    hits.sort(key=lambda t: (t.first_seen, t.id))
+    return hits

nrdax/citations.py

@@ -0,0 +1,179 @@
+"""Citation generation for NRDAX techniques.
+
+Uses the canonical URL and the metadata that actually exists: the technique's
+``display`` title, ``first_seen`` date, the dataset ``version``, and the DOI *only
+when one is minted*. It never fabricates bibliographic metadata — the current
+dataset has no DOI, so citations omit it rather than inventing one.
+
+Styles: ``text`` (plain), ``markdown``, ``bibtex`` (``@online``), and ``json``
+(CSL-JSON, importable by reference managers). House style: hyphens, never em dashes.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from .errors import InvalidArgumentError
+from .models import Technique
+
+if TYPE_CHECKING:
+    from .registry import NRDAX
+
+AUTHOR = "NullRabbit Labs"
+PUBLISHER = "NullRabbit"
+CONTAINER = "NRDAX - NullRabbit Decentralised Attack indeX"
+CITATION_STYLES = ("text", "markdown", "bibtex", "json")
+
+
+@dataclass(frozen=True)
+class CitationData:
+    """The resolved, source-backed fields a citation is built from."""
+
+    id: str
+    title: str
+    url: str
+    author: str
+    publisher: str
+    container: str
+    version: str
+    first_seen: str
+    accessed: str
+    doi: str | None = None
+
+    @property
+    def year(self) -> str:
+        return self.first_seen[:4] if self.first_seen else ""
+
+
+def _accessed(accessed: str | _dt.date | None) -> str:
+    if accessed is None:
+        return _dt.date.today().isoformat()
+    if isinstance(accessed, _dt.date):
+        return accessed.isoformat()
+    return accessed
+
+
+def build(
+    technique: Technique,
+    *,
+    version: str,
+    doi: str | None = None,
+    accessed: str | _dt.date | None = None,
+) -> CitationData:
+    return CitationData(
+        id=technique.id,
+        title=technique.display,
+        url=technique.url,
+        author=AUTHOR,
+        publisher=PUBLISHER,
+        container=CONTAINER,
+        version=version,
+        first_seen=technique.first_seen,
+        accessed=_accessed(accessed),
+        doi=doi,
+    )
+
+
+def _text(c: CitationData) -> str:
+    doi = f" https://doi.org/{c.doi}" if c.doi else ""
+    year = f" ({c.year})" if c.year else ""
+    return (
+        f"{c.author}.{year} {c.title} ({c.id}). {c.container}, version {c.version}. "
+        f"Retrieved {c.accessed}, from {c.url}.{doi}"
+    )
+
+
+def _markdown(c: CitationData) -> str:
+    doi = f" [doi:{c.doi}](https://doi.org/{c.doi})" if c.doi else ""
+    year = f" ({c.year})" if c.year else ""
+    return (
+        f"{c.author}.{year} *{c.title}* ({c.id}). {c.container}, version {c.version}. "
+        f"Retrieved {c.accessed}, from [{c.url}]({c.url}).{doi}"
+    )
+
+
+def _bibtex(c: CitationData) -> str:
+    lines = [
+        f"@online{{{c.id},",
+        f"  author       = {{{c.author}}},",
+        f"  title        = {{{{{c.title}}}}},",
+    ]
+    if c.year:
+        lines.append(f"  year         = {{{c.year}}},")
+    lines += [
+        f"  organization = {{{c.publisher}}},",
+        f"  howpublished = {{{c.container}}},",
+        f"  version      = {{{c.version}}},",
+        f"  number       = {{{c.id}}},",
+        f"  url          = {{{c.url}}},",
+        f"  urldate      = {{{c.accessed}}},",
+    ]
+    if c.doi:
+        lines.append(f"  doi          = {{{c.doi}}},")
+    lines.append(f"  note         = {{NRDAX technique {c.id}}}")
+    lines.append("}")
+    return "\n".join(lines)
+
+
+def _csl_json(c: CitationData) -> str:
+    parts = c.first_seen.split("-")
+    issued: dict[str, Any] = {}
+    if len(parts) == 3 and all(p.isdigit() for p in parts):
+        issued = {"date-parts": [[int(parts[0]), int(parts[1]), int(parts[2])]]}
+    acc = c.accessed.split("-")
+    accessed_obj: dict[str, Any] = {}
+    if len(acc) == 3 and all(p.isdigit() for p in acc):
+        accessed_obj = {"date-parts": [[int(acc[0]), int(acc[1]), int(acc[2])]]}
+
+    doc: dict[str, Any] = {
+        "id": c.id,
+        "type": "dataset",
+        "title": c.title,
+        "author": [{"literal": c.author}],
+        "publisher": c.publisher,
+        "container-title": c.container,
+        "version": c.version,
+        "number": c.id,
+        "URL": c.url,
+        "note": f"NRDAX technique {c.id}",
+    }
+    if issued:
+        doc["issued"] = issued
+    if accessed_obj:
+        doc["accessed"] = accessed_obj
+    if c.doi:
+        doc["DOI"] = c.doi
+    return json.dumps(doc, indent=2, ensure_ascii=False)
+
+
+_RENDERERS = {
+    "text": _text,
+    "markdown": _markdown,
+    "bibtex": _bibtex,
+    "json": _csl_json,
+}
+
+
+def render(citation: CitationData, style: str = "text") -> str:
+    try:
+        return _RENDERERS[style](citation)
+    except KeyError:
+        raise InvalidArgumentError(
+            f"unknown citation style {style!r} (choose from {', '.join(CITATION_STYLES)})"
+        ) from None
+
+
+def cite(
+    registry: NRDAX,
+    technique_id: str,
+    *,
+    style: str = "text",
+    accessed: str | _dt.date | None = None,
+) -> str:
+    """Build and render a citation for a technique in ``registry``."""
+    technique = registry.get(technique_id)
+    data = build(technique, version=registry.version, doi=registry.doi, accessed=accessed)
+    return render(data, style)