ninjasignal 0.1.0__tar.gz

ninjasignal-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# envs
+.venv/
+venv/
+env/
+
+# secrets — never commit
+.env
+*.pem
+*.key
+*.token
+secrets*.json
+
+# editor / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

ninjasignal-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 — 2026-10-07
+
+Initial release.
+
+- `Client` + module-level helpers over the public Ninja Labz feeds:
+  `groups`, `group`, `recent`, `monthly`, `predictions`, `surging`, `predict`, `risk`.
+- `ninja` / `ninjasignal` CLI with table or `--json` output.
+- Zero runtime dependencies; optional pandas via `frame()`.
+- Non-JSON responses are rejected (a stale CDN entry or error page can never be
+  parsed into bad data).

ninjasignal-0.1.0/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 Scott Gardner / Ninja Labz
+
+   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.

ninjasignal-0.1.0/NOTICE

@@ -0,0 +1,29 @@
+ninjasignal
+Copyright 2026 Scott Gardner / Ninja Labz (ninja.ing)
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+Intellectual-property boundary
+------------------------------
+This open-source client library contains NO Ninja Labs predictive-intelligence
+methods, models, correlation/inference algorithms, scoring, or systems. It only
+reads already-published outputs from the public Ninja Labs data feeds.
+
+The predictive-intelligence methods and systems that produce those outputs are
+proprietary to Ninja Labs and are patent-pending and/or patented. Nothing in this
+repository — neither the Apache-2.0 code license nor the CC-BY data license —
+grants any right, express or implied, to those methods, models, or systems, by
+license, estoppel, or otherwise.
+
+Licensing summary
+-----------------
+- This client CODE: Apache License 2.0 (patent grant limited to what this code
+  itself embodies — which is none of the proprietary methods).
+- The DATA served by the feeds: Creative Commons Attribution 4.0 (CC BY 4.0).
+  Attribute "Ninja Labs — ninjalabz.io".
+- The predictive METHODS/MODELS behind the data: proprietary, patent-pending.
+  NOT licensed by this repository.
+
+"Ninja Labs", "Ninja Signal", "ninja.ing" and associated marks are trademarks of
+their owner. This License does not grant permission to use those marks except as
+required for reasonable and customary use in describing the origin of the work.

ninjasignal-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: ninjasignal
+Version: 0.1.0
+Summary: Python client for Ninja Labz predictive threat intelligence — live ransomware groups, victims, and what the lab predicts next.
+Project-URL: Homepage, https://ninjalabz.io
+Project-URL: Predictive Intel Report, https://ninjalabz.io/intel-report/
+Project-URL: Data Feeds, https://ninjalabz.io/feeds/
+Project-URL: Source, https://github.com/scottgardner777/ninjasignal
+Author-email: Scott Gardner <the_v01d@ninja.ing>
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: cti,ninja-labz,ninjasignal,osint,predictive-intelligence,ransomware,security,threat-intelligence
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.3; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# ninjasignal
+
+**The Python client for [Ninja Labz](https://ninjalabz.io) predictive threat intelligence.**
+
+Ninja Labz tracks the ransomware ecosystem on live data and publishes *what it predicts next* — surging groups, new entrants, sectors in the crosshairs, and calibrated forward calls. `ninjasignal` puts that in three lines of Python.
+
+```bash
+pip install ninjasignal
+```
+
+```python
+import ninjasignal as ns
+
+ns.surging()          # groups accelerating right now
+ns.predict("qilin")   # what the lab predicts for a group
+ns.groups()           # active groups + victim counts, top sector/country, origin
+ns.recent(limit=20)   # latest claimed victims (date, group, sector, country)
+```
+
+Zero runtime dependencies. Talks only to the public feeds over HTTPS. Pandas is an optional convenience, never required.
+
+---
+
+## Why
+
+Ransomware intel is everywhere; *predictive* ransomware intel, published openly, is not. Ninja Labz runs an AI-native lab that scans dated victim activity, scores the ecosystem, and calls what's next — then publishes it. This library is how you consume it from a notebook, a pipeline, or a terminal.
+
+## CLI
+
+Installs `ninja` (and `ninjasignal`):
+
+```bash
+ninja surging                       # groups accelerating now
+ninja predict qilin                 # the lab's calls for a group
+ninja groups                        # active groups
+ninja recent --limit 20 --sector Healthcare
+ninja report                        # latest monthly stats
+ninja risk --sector Healthcare      # exposure concentration (descriptive)
+```
+
+Add `--json` to any command for raw output, `--base URL` to point at a mirror.
+
+## API
+
+| Call | Returns |
+|------|---------|
+| `ns.groups()` | active ransomware groups: `name, victims, top_sector, top_country, origin, sanctioned` |
+| `ns.group(slug)` | one group's full dossier data (sectors, countries, recent, aliases) |
+| `ns.recent(limit=, group=, sector=, country=)` | recent claimed victims, newest first |
+| `ns.monthly()` | per-month totals + top groups (the trend series) |
+| `ns.predictions(kind=)` | the lab's predictions: `type, subject, statement, confidence, basis` |
+| `ns.surging()` | predictions of type `rising_group` |
+| `ns.predict(group)` | predictions matching a group |
+| `ns.risk(sector=, country=)` | a transparent exposure-concentration score (see note) |
+
+Use a `Client` directly to set caching / host:
+
+```python
+from ninjasignal import Client
+nl = Client(cache_ttl=600)
+nl.frame(nl.groups())   # a pandas DataFrame if pandas is installed, else a list
+```
+
+> **Note on `risk()`** — this is a simple, transparent *descriptive* measure (a sector's share of recent claims, scaled 0–100). It is **not** a probabilistic forecast and **not** the lab's model. For the model's forward calls, use `predictions()`.
+
+## Data & provenance
+
+All data comes from the public feeds under `https://ninjalabz.io/feeds/`, documented at **<https://ninjalabz.io/feeds/>**. The monthly **Predictive Intel Report** lives at **<https://ninjalabz.io/intel-report/>**.
+
+- **Data license:** Creative Commons Attribution 4.0 (CC BY 4.0). Attribute *"Ninja Labz — ninjalabz.io"*.
+- **This client's code:** Apache License 2.0.
+
+## Intellectual property
+
+This client library **embodies none of Ninja Labz's predictive methods** — it only reads already-published outputs. The models, correlation/inference algorithms, and systems that produce those outputs are **proprietary to Ninja Labz and patent-pending**. Neither the Apache-2.0 code license nor the CC-BY data license grants any right to those methods. See [`NOTICE`](NOTICE).
+
+## Contributing & security
+
+Issues and PRs welcome for the client itself. Please report security concerns privately via GitHub Security Advisories — see [`SECURITY.md`](SECURITY.md).
+
+---
+
+*Built by [Ninja Labz](https://ninjalabz.io) — the name in predictive threat intelligence.*

ninjasignal-0.1.0/README.md

@@ -0,0 +1,83 @@
+# ninjasignal
+
+**The Python client for [Ninja Labz](https://ninjalabz.io) predictive threat intelligence.**
+
+Ninja Labz tracks the ransomware ecosystem on live data and publishes *what it predicts next* — surging groups, new entrants, sectors in the crosshairs, and calibrated forward calls. `ninjasignal` puts that in three lines of Python.
+
+```bash
+pip install ninjasignal
+```
+
+```python
+import ninjasignal as ns
+
+ns.surging()          # groups accelerating right now
+ns.predict("qilin")   # what the lab predicts for a group
+ns.groups()           # active groups + victim counts, top sector/country, origin
+ns.recent(limit=20)   # latest claimed victims (date, group, sector, country)
+```
+
+Zero runtime dependencies. Talks only to the public feeds over HTTPS. Pandas is an optional convenience, never required.
+
+---
+
+## Why
+
+Ransomware intel is everywhere; *predictive* ransomware intel, published openly, is not. Ninja Labz runs an AI-native lab that scans dated victim activity, scores the ecosystem, and calls what's next — then publishes it. This library is how you consume it from a notebook, a pipeline, or a terminal.
+
+## CLI
+
+Installs `ninja` (and `ninjasignal`):
+
+```bash
+ninja surging                       # groups accelerating now
+ninja predict qilin                 # the lab's calls for a group
+ninja groups                        # active groups
+ninja recent --limit 20 --sector Healthcare
+ninja report                        # latest monthly stats
+ninja risk --sector Healthcare      # exposure concentration (descriptive)
+```
+
+Add `--json` to any command for raw output, `--base URL` to point at a mirror.
+
+## API
+
+| Call | Returns |
+|------|---------|
+| `ns.groups()` | active ransomware groups: `name, victims, top_sector, top_country, origin, sanctioned` |
+| `ns.group(slug)` | one group's full dossier data (sectors, countries, recent, aliases) |
+| `ns.recent(limit=, group=, sector=, country=)` | recent claimed victims, newest first |
+| `ns.monthly()` | per-month totals + top groups (the trend series) |
+| `ns.predictions(kind=)` | the lab's predictions: `type, subject, statement, confidence, basis` |
+| `ns.surging()` | predictions of type `rising_group` |
+| `ns.predict(group)` | predictions matching a group |
+| `ns.risk(sector=, country=)` | a transparent exposure-concentration score (see note) |
+
+Use a `Client` directly to set caching / host:
+
+```python
+from ninjasignal import Client
+nl = Client(cache_ttl=600)
+nl.frame(nl.groups())   # a pandas DataFrame if pandas is installed, else a list
+```
+
+> **Note on `risk()`** — this is a simple, transparent *descriptive* measure (a sector's share of recent claims, scaled 0–100). It is **not** a probabilistic forecast and **not** the lab's model. For the model's forward calls, use `predictions()`.
+
+## Data & provenance
+
+All data comes from the public feeds under `https://ninjalabz.io/feeds/`, documented at **<https://ninjalabz.io/feeds/>**. The monthly **Predictive Intel Report** lives at **<https://ninjalabz.io/intel-report/>**.
+
+- **Data license:** Creative Commons Attribution 4.0 (CC BY 4.0). Attribute *"Ninja Labz — ninjalabz.io"*.
+- **This client's code:** Apache License 2.0.
+
+## Intellectual property
+
+This client library **embodies none of Ninja Labz's predictive methods** — it only reads already-published outputs. The models, correlation/inference algorithms, and systems that produce those outputs are **proprietary to Ninja Labz and patent-pending**. Neither the Apache-2.0 code license nor the CC-BY data license grants any right to those methods. See [`NOTICE`](NOTICE).
+
+## Contributing & security
+
+Issues and PRs welcome for the client itself. Please report security concerns privately via GitHub Security Advisories — see [`SECURITY.md`](SECURITY.md).
+
+---
+
+*Built by [Ninja Labz](https://ninjalabz.io) — the name in predictive threat intelligence.*

ninjasignal-0.1.0/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Scope
+
+`ninjasignal` is a read-only client for public, open data feeds. It uses no
+credentials, writes nothing, and contacts only its configured host (default
+`https://ninjalabz.io`) over HTTPS. It ships with no runtime dependencies.
+
+## Reporting a vulnerability
+
+Please report security issues **privately** via GitHub Security Advisories
+("Report a vulnerability" on the repository's **Security** tab) rather than a
+public issue. We aim to acknowledge within a few days.
+
+Helpful to include: the version, a minimal reproduction, and the impact you see.
+
+## Out of scope
+
+- The Ninja Labz backend, feeds infrastructure, or data content (report those
+  through the Ninja Labz site, not this repo).
+- The proprietary predictive methods behind the feeds — not part of this package.

ninjasignal-0.1.0/examples/quickstart.py

@@ -0,0 +1,27 @@
+"""Quickstart — live against the public Ninja Labz feeds.
+
+    python examples/quickstart.py
+"""
+import ninjasignal as ns
+
+
+def main():
+    print("== Surging now ==")
+    for p in ns.surging()[:5]:
+        print(f"  {p['subject']:<16} conf {p['confidence']:<4} {p['statement'][:80]}")
+
+    print("\n== Most-tracked groups ==")
+    for g in sorted(ns.groups(), key=lambda g: g.get("victims", 0), reverse=True)[:5]:
+        flag = " [SANCTIONED]" if g.get("sanctioned") else ""
+        print(f"  {g['name']:<16} {g.get('victims', 0):>5} victims  top: {g.get('top_sector')}{flag}")
+
+    print("\n== Latest recent victims ==")
+    for v in ns.recent(limit=5):
+        print(f"  {v['date']}  {v['group']:<14} {v.get('sector', '?'):<16} {v.get('country', '?')}")
+
+    print("\n== Healthcare exposure (descriptive) ==")
+    print(" ", ns.risk(sector="Healthcare"))
+
+
+if __name__ == "__main__":
+    main()

ninjasignal-0.1.0/ninjasignal/__init__.py

@@ -0,0 +1,72 @@
+"""ninjasignal — the Python client for Ninja Labz predictive threat intelligence.
+
+Ninja Labz tracks the ransomware ecosystem on live data and publishes what it
+predicts next. This library is a thin, dependency-free reader over the public
+feeds — it talks only to https://ninjalabz.io and reads open CC-BY data.
+
+    import ninjasignal as ns
+    ns.surging()            # groups accelerating right now
+    ns.predict("qilin")     # what the lab predicts for a group
+    ns.groups()             # active groups + victim counts
+    ns.recent(limit=20)     # latest claimed victims
+
+IP boundary: this client embodies NONE of Ninja Labz's predictive methods. It
+only consumes already-published outputs. The models and systems behind those
+outputs are proprietary and patent-pending, and nothing here licenses them.
+"""
+from __future__ import annotations
+
+from .client import Client, NinjaSignalError, DEFAULT_BASE
+
+__all__ = ["Client", "NinjaSignalError", "DEFAULT_BASE", "__version__",
+           "groups", "group", "recent", "monthly", "predictions", "surging",
+           "predict", "risk", "latest_month"]
+
+__version__ = "0.1.0"
+
+_default: Client | None = None
+
+
+def _client() -> Client:
+    global _default
+    if _default is None:
+        _default = Client()
+    return _default
+
+
+# Module-level convenience wrappers over a shared default Client.
+def groups():
+    return _client().groups()
+
+
+def group(slug: str):
+    return _client().group(slug)
+
+
+def recent(limit: int | None = None, group: str | None = None,
+           sector: str | None = None, country: str | None = None):
+    return _client().recent(limit=limit, group=group, sector=sector, country=country)
+
+
+def monthly():
+    return _client().monthly()
+
+
+def predictions(kind: str | None = None):
+    return _client().predictions(kind=kind)
+
+
+def surging():
+    return _client().surging()
+
+
+def predict(group: str):
+    return _client().predict(group)
+
+
+def risk(sector: str | None = None, country: str | None = None):
+    return _client().risk(sector=sector, country=country)
+
+
+def latest_month():
+    return _client().latest_month()

ninjasignal-0.1.0/ninjasignal/cli.py

@@ -0,0 +1,88 @@
+"""Command-line interface: `ninja` / `ninjasignal`.
+
+    ninja surging
+    ninja predict qilin
+    ninja groups
+    ninja recent --limit 20 --sector Healthcare
+    ninja report
+    ninja risk --sector Healthcare
+
+Every command takes --json for raw output and --base to point at a mirror.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .client import Client, NinjaSignalError
+
+
+def _table(rows: list[dict], cols: list[str]) -> str:
+    if not rows:
+        return "(no results)"
+    cols = [c for c in cols if any(c in r for r in rows)]
+    widths = {c: max(len(c), *(len(str(r.get(c, ""))) for r in rows)) for c in cols}
+    line = "  ".join(c.upper().ljust(widths[c]) for c in cols)
+    out = [line, "  ".join("-" * widths[c] for c in cols)]
+    for r in rows:
+        out.append("  ".join(str(r.get(c, "")).ljust(widths[c]) for c in cols))
+    return "\n".join(out)
+
+
+def _emit(data, as_json: bool, cols: list[str] | None = None):
+    if as_json:
+        print(json.dumps(data, indent=2, ensure_ascii=False))
+    elif isinstance(data, list) and cols:
+        print(_table(data, cols))
+    else:
+        print(json.dumps(data, indent=2, ensure_ascii=False))
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        prog="ninja", description="Ninja Labz predictive threat-intel client.")
+    p.add_argument("--version", action="version", version=f"ninjasignal {__version__}")
+    p.add_argument("--base", help="feed host (default https://ninjalabz.io)")
+    p.add_argument("--json", action="store_true", help="raw JSON output")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("groups", help="active ransomware groups")
+    sub.add_parser("surging", help="groups accelerating right now")
+    sub.add_parser("report", help="latest monthly stats")
+    sp = sub.add_parser("predict", help="predictions for a group")
+    sp.add_argument("group")
+    sr = sub.add_parser("recent", help="recent claimed victims")
+    sr.add_argument("--limit", type=int, default=25)
+    sr.add_argument("--group"); sr.add_argument("--sector"); sr.add_argument("--country")
+    sk = sub.add_parser("risk", help="exposure concentration (descriptive, not a forecast)")
+    sk.add_argument("--sector"); sk.add_argument("--country")
+
+    a = p.parse_args(argv)
+    nl = Client(base=a.base) if a.base else Client()
+    try:
+        if a.cmd == "groups":
+            _emit(nl.groups(), a.json, ["name", "victims", "top_sector", "top_country", "origin", "sanctioned"])
+        elif a.cmd == "surging":
+            _emit(nl.surging(), a.json, ["subject", "confidence", "statement"])
+        elif a.cmd == "report":
+            _emit(nl.latest_month(), a.json)
+        elif a.cmd == "predict":
+            preds = nl.predict(a.group)
+            _emit(preds or [{"note": f"no current prediction for {a.group!r}"}], a.json,
+                  ["type", "subject", "confidence", "statement"])
+        elif a.cmd == "recent":
+            _emit(nl.recent(limit=a.limit, group=a.group, sector=a.sector, country=a.country),
+                  a.json, ["date", "group", "victim", "sector", "country"])
+        elif a.cmd == "risk":
+            _emit(nl.risk(sector=a.sector, country=a.country), a.json,
+                  None if (a.sector or a.country) else None)
+    except NinjaSignalError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ninjasignal-0.1.0/ninjasignal/client.py

@@ -0,0 +1,162 @@
+"""The Ninja Signal client — a thin, dependency-free reader over the public
+Ninja Labz predictive threat-intelligence feeds.
+
+Everything here talks to ONE public host (https://ninjalabz.io) over HTTPS and
+reads only the open, CC-BY data feeds under /feeds/ransomware/. There are no
+credentials, no private endpoints, and nothing internal — point it somewhere else
+with `Client(base=...)` if you mirror the feeds yourself.
+"""
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+
+__all__ = ["Client", "NinjaSignalError"]
+
+DEFAULT_BASE = "https://ninjalabz.io"
+_FEED = "/feeds/ransomware"
+
+
+class NinjaSignalError(RuntimeError):
+    """Raised when a feed can't be fetched or isn't valid JSON."""
+
+
+class Client:
+    """Reader for the Ninja Labz predictive-intel feeds.
+
+    >>> from ninjasignal import Client
+    >>> nl = Client()
+    >>> [g["name"] for g in nl.groups()][:3]
+    """
+
+    def __init__(self, base: str = DEFAULT_BASE, timeout: float = 15.0,
+                 cache_ttl: float = 300.0, user_agent: str | None = None):
+        self.base = base.rstrip("/")
+        self.timeout = timeout
+        self.cache_ttl = cache_ttl
+        self.user_agent = user_agent or "ninjasignal-python"
+        self._cache: dict[str, tuple[float, dict]] = {}
+
+    # ── transport ────────────────────────────────────────────────────────────
+    def _get(self, path: str) -> dict:
+        now = time.time()
+        hit = self._cache.get(path)
+        if hit and (now - hit[0]) < self.cache_ttl:
+            return hit[1]
+        url = self.base + path
+        req = urllib.request.Request(url, headers={"User-Agent": self.user_agent,
+                                                    "Accept": "application/json"})
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                raw = r.read().decode("utf-8", "replace")
+        except urllib.error.HTTPError as e:
+            raise NinjaSignalError(f"{url} returned HTTP {e.code}") from e
+        except urllib.error.URLError as e:
+            raise NinjaSignalError(f"could not reach {url}: {e.reason}") from e
+        stripped = raw.lstrip()
+        if not stripped or stripped[0] not in "{[":
+            # a feed is always JSON; anything else (an error page, a stale CDN
+            # entry) is rejected rather than parsed into nonsense.
+            raise NinjaSignalError(f"{url} did not return JSON (got {stripped[:40]!r}…)")
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise NinjaSignalError(f"{url} returned invalid JSON: {e}") from e
+        self._cache[path] = (now, data)
+        return data
+
+    def _feed(self, name: str) -> dict:
+        return self._get(f"{_FEED}/{name}.js")
+
+    # ── data feeds ───────────────────────────────────────────────────────────
+    def groups(self) -> list[dict]:
+        """Active ransomware groups: victim counts, top sector/country, origin."""
+        return self._feed("groups").get("groups", [])
+
+    def group(self, slug: str) -> dict:
+        """Full dossier data for one group (victims, sectors, countries, recent)."""
+        slug = slug.strip().lower().replace(" ", "")
+        return self._feed(f"group-{slug}")
+
+    def recent(self, limit: int | None = None, group: str | None = None,
+               sector: str | None = None, country: str | None = None) -> list[dict]:
+        """Recent claimed victims (date, group, victim, sector, country), newest first,
+        optionally filtered."""
+        vics = self._feed("victims-recent").get("victims", [])
+
+        def keep(v: dict) -> bool:
+            if group and (v.get("group") or "").lower() != group.lower():
+                return False
+            if sector and (v.get("sector") or "").lower() != sector.lower():
+                return False
+            if country and (v.get("country") or "").lower() != country.lower():
+                return False
+            return True
+
+        out = [v for v in vics if keep(v)]
+        return out[:limit] if limit else out
+
+    def monthly(self) -> list[dict]:
+        """Per-month totals + top groups (the time series behind the trends)."""
+        return self._feed("stats-monthly").get("months", [])
+
+    # ── predictions (the differentiator) ─────────────────────────────────────
+    def predictions(self, kind: str | None = None) -> list[dict]:
+        """The lab's live predictions: {type, subject, statement, confidence, basis}.
+        `kind` filters by type (rising_group | likely_target | momentum | watch)."""
+        preds = self._feed("predictions").get("predictions", [])
+        return [p for p in preds if (not kind or p.get("type") == kind)]
+
+    def surging(self) -> list[dict]:
+        """Groups the lab flags as accelerating right now (type=rising_group)."""
+        return self.predictions(kind="rising_group")
+
+    def predict(self, group: str) -> list[dict]:
+        """Predictions whose subject matches a group (case-insensitive)."""
+        g = group.strip().lower()
+        return [p for p in self.predictions() if g in (p.get("subject") or "").lower()]
+
+    # ── a small derived signal: exposure/risk ────────────────────────────────
+    def risk(self, sector: str | None = None, country: str | None = None) -> dict:
+        """A simple, transparent exposure score from the recent-victim mix.
+
+        Score = this sector's (or country's) share of recent claims, scaled to the
+        busiest sector/country = 100. It's a descriptive concentration measure, not a
+        probabilistic forecast — see `predictions()` for the model's forward calls.
+        """
+        vics = self.recent()
+        if not vics:
+            return {"score": 0, "basis": "no recent data"}
+        field = "sector" if sector else "country" if country else "sector"
+        target = (sector or country or "").lower()
+        counts: dict[str, int] = {}
+        for v in vics:
+            key = (v.get(field) or "unknown")
+            counts[key] = counts.get(key, 0) + 1
+        ranked = sorted(counts.items(), key=lambda kv: kv[1], reverse=True)
+        top = ranked[0][1] if ranked else 1
+        if not target:
+            return {"field": field, "ranking": [{field: k, "recent_claims": n,
+                     "score": round(100 * n / top)} for k, n in ranked[:15]],
+                    "window_claims": len(vics)}
+        n = next((c for k, c in counts.items() if k.lower() == target), 0)
+        rank = next((i + 1 for i, (k, _) in enumerate(ranked) if k.lower() == target), None)
+        return {field: sector or country, "recent_claims": n,
+                "score": round(100 * n / top), "rank": rank,
+                "of": len(ranked), "window_claims": len(vics)}
+
+    # ── convenience ──────────────────────────────────────────────────────────
+    def latest_month(self) -> dict:
+        months = self.monthly()
+        return months[0] if months else {}
+
+    def frame(self, rows: list[dict]):
+        """Return rows as a pandas DataFrame if pandas is installed, else the list.
+        Keeps pandas an optional convenience, never a hard dependency."""
+        try:
+            import pandas as pd  # noqa: PLC0415
+        except ImportError:
+            return rows
+        return pd.DataFrame(rows)

ninjasignal-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ninjasignal"
+version = "0.1.0"
+description = "Python client for Ninja Labz predictive threat intelligence — live ransomware groups, victims, and what the lab predicts next."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Scott Gardner", email = "the_v01d@ninja.ing" }]
+keywords = ["threat-intelligence", "ransomware", "predictive-intelligence", "cti",
+            "security", "osint", "ninja-labz", "ninjasignal"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Information Technology",
+  "Topic :: Security",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+dependencies = []   # stdlib only — no runtime dependencies
+
+[project.optional-dependencies]
+pandas = ["pandas>=1.3"]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://ninjalabz.io"
+"Predictive Intel Report" = "https://ninjalabz.io/intel-report/"
+"Data Feeds" = "https://ninjalabz.io/feeds/"
+Source = "https://github.com/scottgardner777/ninjasignal"
+
+[project.scripts]
+ninja = "ninjasignal.cli:main"
+ninjasignal = "ninjasignal.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ninjasignal"]

ninjasignal-0.1.0/tests/test_client.py

@@ -0,0 +1,82 @@
+"""Offline tests: feed access is monkeypatched so the suite never hits the network."""
+import pytest
+
+from ninjasignal import Client, NinjaSignalError
+
+FEEDS = {
+    "/feeds/ransomware/groups.js": {"groups": [
+        {"slug": "lockbit", "name": "LockBit", "victims": 3315, "top_sector": "Manufacturing",
+         "top_country": "US", "origin": "Russia", "sanctioned": True, "apt": False},
+        {"slug": "qilin", "name": "Qilin", "victims": 700, "top_sector": "Healthcare",
+         "top_country": "US", "origin": "Russia", "sanctioned": False, "apt": False}]},
+    "/feeds/ransomware/victims-recent.js": {"victims": [
+        {"date": "2026-10-07", "group": "Qilin", "victim": "Acme Health", "sector": "Healthcare", "country": "US"},
+        {"date": "2026-10-06", "group": "LockBit", "victim": "Widgets Inc", "sector": "Manufacturing", "country": "DE"},
+        {"date": "2026-10-06", "group": "Qilin", "victim": "Clinic Co", "sector": "Healthcare", "country": "GB"}]},
+    "/feeds/ransomware/stats-monthly.js": {"months": [
+        {"month": "2026-10", "total": 173, "top_groups": [{"name": "Qilin", "victims": 19}]}]},
+    "/feeds/ransomware/predictions.js": {"month": "2026-10", "predictions": [
+        {"type": "rising_group", "subject": "Qilin", "statement": "expanding in healthcare",
+         "confidence": 0.9, "basis": "surge 3x"},
+        {"type": "watch", "subject": "LockBit", "statement": "sanctioned, steady", "confidence": 0.7, "basis": ""}]},
+    "/feeds/ransomware/group-qilin.js": {"slug": "qilin", "name": "Qilin", "victims": 700,
+                                         "sectors": [["Healthcare", 120]], "recent": []},
+}
+
+
+@pytest.fixture
+def nl(monkeypatch):
+    c = Client(cache_ttl=0)
+    monkeypatch.setattr(c, "_get", lambda path: FEEDS[path])
+    return c
+
+
+def test_groups(nl):
+    g = nl.groups()
+    assert len(g) == 2 and g[0]["name"] == "LockBit"
+
+
+def test_recent_filters(nl):
+    assert len(nl.recent(sector="Healthcare")) == 2
+    assert len(nl.recent(group="LockBit")) == 1
+    assert len(nl.recent(limit=1)) == 1
+
+
+def test_predictions_and_surging(nl):
+    assert len(nl.predictions()) == 2
+    s = nl.surging()
+    assert len(s) == 1 and s[0]["subject"] == "Qilin"
+
+
+def test_predict(nl):
+    assert nl.predict("qilin")[0]["type"] == "rising_group"
+    assert nl.predict("nonexistent") == []
+
+
+def test_risk(nl):
+    r = nl.risk(sector="Healthcare")
+    assert r["recent_claims"] == 2 and r["score"] == 100 and r["rank"] == 1
+
+
+def test_group(nl):
+    assert nl.group("Qilin")["name"] == "Qilin"
+
+
+def test_non_json_rejected():
+    """A stale CDN entry / error page must never be parsed as data."""
+    c = Client()
+
+    class FakeResp:
+        def read(self): return b"<!doctype html><html>nope</html>"
+        def __enter__(self): return self
+        def __exit__(self, *a): return False
+
+    import urllib.request
+    import pytest as _p
+    orig = urllib.request.urlopen
+    urllib.request.urlopen = lambda *a, **k: FakeResp()
+    try:
+        with _p.raises(NinjaSignalError):
+            c._get("/feeds/ransomware/groups.js")
+    finally:
+        urllib.request.urlopen = orig