zerov4 0.1.0__py3-none-any.whl

zerov4/__init__.py

@@ -0,0 +1,93 @@
+"""
+ZeroV4 — request-level protection for WSGI applications.
+
+Quick start:
+
+    from zerov4 import arx
+    from myapp import app
+
+    arx.run(app)
+
+That asks for a port, a debug flag and a protection level, then serves
+your app with every request inspected before it reaches your routes.
+
+Under gunicorn, wrap instead of run:
+
+    # wsgi.py
+    from zerov4 import arx
+    from myapp import app
+    application = arx.wrap(app)
+
+Or use the middleware directly, if you want the control:
+
+    from zerov4 import ZeroGuard, make_config
+
+    app.wsgi_app = ZeroGuard(app.wsgi_app, cfg=make_config("balanced"))
+
+Or from the shell:
+
+    $ zerov4 init
+    $ zerov4 run myapp:app
+
+Protection levels: permissive, balanced (default), paranoid.
+Balanced is tuned for a site with real visitors. Paranoid is the original
+Autonomous Agent Zero-V4 behaviour — it will produce false positives on
+public traffic, which is what it is for.
+
+Derived from Autonomous Agent Zero-V4 by Barış (BRSX-Labs).
+"""
+
+from . import arx
+from .agent import ThreatAgent
+from .auth import PanelAuth, hash_password, verify_password
+from .challenge import ChallengeManager
+from .config import LEVELS, Config, from_env, make_config
+from .feedback import FeedbackTracker
+from .firewall import ALLOW, BAN, BLOCKED, THROTTLE, Firewall, Verdict
+from .middleware import Request, ZeroGuard
+from .state import ZeroState
+from .store import Store, make_store
+from .utils import Signature, load_signatures
+
+__version__ = "0.1.0"
+__author__ = "Barış (BRSX-Labs)"
+
+__all__ = [
+    # The front door
+    "arx",
+    # Middleware
+    "ZeroGuard",
+    "serve",
+    # Config
+    "make_config",
+    "from_env",
+    "Config",
+    "LEVELS",
+    # Decisions
+    "Firewall",
+    "Verdict",
+    "ALLOW",
+    "THROTTLE",
+    "BAN",
+    "BLOCKED",
+    # Components
+    "ChallengeManager",
+    "FeedbackTracker",
+    "PanelAuth",
+    "ThreatAgent",
+    "Store",
+    "ZeroState",
+    "Request",
+    "Signature",
+    # Helpers
+    "load_signatures",
+    "make_store",
+    "hash_password",
+    "verify_password",
+    "__version__",
+]
+
+
+def serve(app, cfg=None, interactive: bool = True, **overrides):
+    """Wrap `app` and serve it. Same as arx.run()."""
+    return arx.run(app, cfg=cfg, interactive=interactive, **overrides)

zerov4/agent.py

@@ -0,0 +1,143 @@
+"""
+agent.py — background threat monitor.
+
+What this used to be, and what it is now:
+
+  * The Zero-V4 model is gone, as agreed. run_inference() fed a fixed
+    prompt ("system status network analysis") into a byte-level model,
+    averaged the generated token ids, scaled that to 0-100, then added
+    random.choice([+40, +50, ..., -80]) to it. The output never depended
+    on the traffic, so the "risk score" it produced was noise with a
+    threshold on it. What actually made decisions was
+    count_active_attackers() — that logic is kept, and it is now the
+    whole agent.
+
+  * WiFi control is gone. disable_internet()/enable_internet() clicked
+    fixed screen coordinates via pyautogui, or shelled out to nmcli.
+    A library does not take the host off the network. The coordinated-
+    attack event now fires Config.on_coordinated_attack; wire whatever
+    you want to it, including your old disable_internet().
+
+  * The attacker set no longer comes from re-reading and truncating
+    attack_log.txt. It reads live state, which is where the middleware
+    records detections. The old file round-trip lost every event written
+    between the read and the open(..., 'w') that cleared it.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Optional
+
+from .utils import log
+
+
+class ThreatAgent(threading.Thread):
+    """Watches for coordinated activity and drives pattern analysis.
+
+    Single IP misbehaving      -> firewall throttles/bans it inline;
+                                  the agent stays out of it.
+    coordinated_threshold+ IPs -> on_coordinated_attack hook fires once,
+                                  on_threat_cleared when it subsides.
+
+    Interval adapts: quiet systems poll slowly, active ones poll fast.
+    """
+
+    NORMAL_INTERVAL = 30.0
+    TRACKING_INTERVAL = 8.0
+    CRITICAL_INTERVAL = 4.0
+
+    def __init__(self, cfg, firewall, state, interval: Optional[float] = None):
+        super().__init__(daemon=True, name="zeroguard-agent")
+        self.cfg = cfg
+        self.firewall = firewall
+        self.state = state
+        self._forced_interval = interval
+        self._stop_event = threading.Event()
+        self._last_pattern_run = 0.0
+
+    # ─── Threat assessment ───────────────────────────────────────────
+    def active_attackers(self, now: Optional[float] = None) -> set:
+        """Distinct IPs that triggered a detection within the pattern
+        window. Read from live state, not from a log file."""
+        return set(self.state.attack_history(now).keys())
+
+    def assess(self, now: Optional[float] = None) -> dict:
+        """Current threat picture. No model, no randomness — just counts."""
+        now = now or time.time()
+        history = self.state.attack_history(now)
+        attackers = set(history.keys())
+        total_hits = sum(len(v) for v in history.values())
+
+        if not attackers:
+            level, status = 0, "clear"
+        elif len(attackers) >= self.cfg.coordinated_threshold:
+            level, status = 3, "coordinated attack"
+        elif total_hits >= 10 or len(attackers) >= 3:
+            level, status = 2, "elevated"
+        else:
+            level, status = 1, "isolated activity"
+
+        return {
+            "level": level,
+            "status": status,
+            "attackers": sorted(attackers),
+            "attacker_count": len(attackers),
+            "total_hits": total_hits,
+            "coordinated": len(attackers) >= self.cfg.coordinated_threshold,
+        }
+
+    def _interval_for(self, level: int) -> float:
+        if self._forced_interval:
+            return self._forced_interval
+        if level >= 3:
+            return self.CRITICAL_INTERVAL
+        if level == 2:
+            return self.TRACKING_INTERVAL
+        return self.NORMAL_INTERVAL
+
+    # ─── Loop ────────────────────────────────────────────────────────
+    def tick(self, now: Optional[float] = None) -> dict:
+        """One assessment cycle. Exposed separately so it can be called
+        directly from a test or a one-shot CLI command."""
+        now = now or time.time()
+        report = self.assess(now)
+
+        # Pattern analysis owns the coordinated/cleared hooks and the
+        # slow-recon / multi-category / rapid-escalation bans.
+        if self.cfg.pattern_enabled:
+            try:
+                self.firewall.analyse_patterns(now)
+            except Exception as e:
+                log.warning("Pattern analysis failed: %s", e)
+
+        if report["attacker_count"] and report["attacker_count"] < self.cfg.coordinated_threshold:
+            log.debug("%d IP(s) active — handled inline by the firewall.",
+                      report["attacker_count"])
+
+        # Housekeeping the middleware shouldn't do per request.
+        try:
+            self.state.maybe_prune()
+            self.firewall.purge_expired()
+        except Exception as e:
+            log.warning("Housekeeping failed: %s", e)
+
+        return report
+
+    def run(self) -> None:
+        log.info("Threat agent started (coordinated threshold: %d IPs / %ds)",
+                 self.cfg.coordinated_threshold, self.cfg.pattern_window)
+        interval = self.NORMAL_INTERVAL
+        while not self._stop_event.wait(interval):
+            try:
+                report = self.tick()
+                interval = self._interval_for(report["level"])
+            except Exception as e:
+                # The agent must never die: it is what clears expired
+                # bans and prunes memory.
+                log.warning("Agent cycle failed: %s", e)
+                interval = self.NORMAL_INTERVAL
+
+    def stop(self) -> None:
+        self._stop_event.set()

zerov4/arx.py

@@ -0,0 +1,341 @@
+"""
+arx.py — the front door.
+
+    from zerov4 import arx
+
+    arx.run(app)              # menu, then serve
+    arx.run("myapp:app")      # same, but import it for me
+    arx.run()                 # read zerov4.toml, find the app, serve
+    arx.wrap(app)             # just wrap it; gunicorn does the serving
+    arx.status()              # what does the firewall know
+    arx.unblock("1.2.3.4")
+
+`arx` is a module, so `from zerov4 import arx` gives you the namespace and
+every call below hangs off it. State (the running guard) is held here so
+that arx.status() after arx.wrap() talks about the same instance rather
+than building a second one that shares nothing.
+
+Everything here is a thin layer. ZeroGuard, Firewall, make_config and the
+rest stay importable and are what you reach for when you want control:
+
+    from zerov4 import ZeroGuard, make_config
+    app.wsgi_app = ZeroGuard(app.wsgi_app, cfg=make_config("paranoid"))
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any, Optional, Union
+
+from .config import Config, make_config
+
+# The guard built by the most recent wrap()/run() call, so the helpers
+# below operate on the live instance instead of a detached copy.
+_guard = None
+_cfg: Optional[Config] = None
+
+
+# ─── Internals ───────────────────────────────────────────────────────
+def _resolve_app(app: Union[Any, str, None]):
+    """Accept a WSGI callable, a 'module:attr' string, or nothing."""
+    if app is None:
+        from .cli import load_config_file
+        target = load_config_file().get("app")
+        if not target:
+            raise SystemExit(
+                "  No app given and no `app` key in zerov4.toml.\n"
+                "  Try:  arx.run(app)   or   arx.run('myapp:app')\n"
+                "  Or add to zerov4.toml:  app = \"myapp:app\"")
+        app = target
+
+    if isinstance(app, str):
+        from .cli import load_app
+        return load_app(app)
+
+    if not callable(app):
+        raise TypeError(
+            f"Expected a WSGI application or a 'module:attr' string, "
+            f"got {type(app).__name__}. If you have a Flask app, pass the "
+            f"app itself: arx.run(app)")
+    return app
+
+
+def _build_config(cfg: Optional[Config], overrides: dict,
+                  interactive: bool) -> Config:
+    if cfg is not None:
+        return cfg
+
+    from .cli import interactive_setup, load_config_file
+
+    values = load_config_file()
+    values.pop("app", None)          # not a Config field
+    values.update(overrides)
+
+    if interactive and sys.stdin.isatty():
+        return interactive_setup(values, write_file=False)
+
+    level = values.pop("level", "balanced")
+    return make_config(level, **values)
+
+
+def _need_guard():
+    if _guard is None:
+        raise RuntimeError(
+            "No guard is running. Call arx.run(app) or arx.wrap(app) first.\n"
+            "For read-only inspection without a running app, use the CLI:\n"
+            "    zerov4 status")
+    return _guard
+
+
+def _offline_firewall():
+    """Build a firewall against the on-disk state, for when nothing is
+    running — `zerov4 status` from a second terminal, for instance."""
+    from .firewall import Firewall
+    from .state import ZeroState
+    from .store import make_store
+    from .utils import setup_logging
+    from .cli import load_config_file
+
+    values = load_config_file()
+    values.pop("app", None)
+    level = values.pop("level", "balanced")
+    values.setdefault("verbose", False)
+    cfg = make_config(level, **values)
+    setup_logging(cfg)
+    store = make_store(cfg)
+    state = ZeroState(cfg)
+    state.load()
+    return Firewall(cfg, store, state), cfg
+
+
+def _firewall():
+    return _guard.firewall if _guard is not None else _offline_firewall()[0]
+
+
+# ─── Main entry points ───────────────────────────────────────────────
+def wrap(app: Union[Any, str, None] = None, cfg: Optional[Config] = None,
+         level: str = "balanced", **overrides):
+    """Wrap a WSGI app and return it. Does not serve.
+
+    This is what you want under gunicorn/uwsgi, which do their own serving:
+
+        # wsgi.py
+        from zerov4 import arx
+        from myapp import app
+        application = arx.wrap(app)
+
+        $ gunicorn wsgi:application -w 4
+
+    Non-interactive by design — a worker booting under gunicorn must not
+    stop to ask you for a port.
+    """
+    global _guard, _cfg
+    from .middleware import ZeroGuard
+
+    resolved = _resolve_app(app)
+    if cfg is None:
+        overrides.setdefault("level", level)
+        cfg = _build_config(None, overrides, interactive=False)
+
+    _cfg = cfg
+    _guard = ZeroGuard(resolved, cfg=cfg)
+    return _guard
+
+
+def run(app: Union[Any, str, None] = None, cfg: Optional[Config] = None,
+        interactive: bool = True, **overrides):
+    """Wrap `app` and serve it.
+
+        arx.run(app)                  # asks port/debug/level, then serves
+        arx.run(app, port=8080)       # port answered, so not asked
+        arx.run("myapp:app")
+        arx.run(interactive=False)    # no questions at all
+
+    Blocks until Ctrl+C.
+    """
+    global _guard, _cfg
+    from .cli import serve
+
+    resolved = _resolve_app(app)
+    cfg = _build_config(cfg, overrides, interactive)
+    _cfg = cfg
+
+    from .middleware import ZeroGuard
+    _guard = ZeroGuard(resolved, cfg=cfg)
+
+    print()
+    print("  This server is secured by Arx and Zero.")
+    print(f"  ZeroV4 listening on http://{cfg.host}:{cfg.port}")
+    if cfg.panel_enabled:
+        print(f"  Panel: http://127.0.0.1:{cfg.port}{cfg.panel_path}")
+    print("  Ctrl+C to stop.")
+    print()
+
+    from .cli import _run_server
+    try:
+        _run_server(_guard, cfg)
+    except KeyboardInterrupt:
+        print("\n  Stopping...")
+    finally:
+        _guard.shutdown()
+        _guard = None
+        print("  Stopped.")
+
+
+def stop() -> None:
+    """Shut down the running guard: stop its threads, flush state."""
+    global _guard
+    if _guard is not None:
+        _guard.shutdown()
+        _guard = None
+
+
+def init(**overrides) -> Config:
+    """Run the setup menu and write zerov4.toml. Same as `zerov4 init`."""
+    global _cfg
+    from .cli import interactive_setup
+    _cfg = interactive_setup(overrides)
+    return _cfg
+
+
+# ─── Inspection ──────────────────────────────────────────────────────
+def status() -> dict:
+    """What the firewall currently knows. Works with or without a running
+    guard — without one it reads the stored state."""
+    firewall = _firewall()
+    stats = firewall.stats()
+    if _guard is not None:
+        stats.update(_guard.state.snapshot())
+        stats["signatures"] = len(_guard.signatures)
+    return stats
+
+
+def blocked() -> list:
+    """Every blocked IP, newest first."""
+    return _firewall().list_blocked()
+
+
+def reputation() -> list:
+    """The learned bad-IP list, worst first."""
+    return _firewall().list_reputation()
+
+
+def attacks(n: int = 20) -> list:
+    """Recent detections. Needs a running guard — this lives in memory."""
+    return _need_guard().state.recent_attacks(n)
+
+
+def is_blocked(ip: str) -> bool:
+    return _firewall().is_blocked(ip) is not None
+
+
+# ─── Actions ─────────────────────────────────────────────────────────
+def unblock(ip: str) -> bool:
+    """Lift a block: block entry, reputation, and hit count all cleared.
+    Miss any one and the IP is re-banned on its next request."""
+    return _firewall().unblock(ip)
+
+
+def ban(ip: str, reason: str = "manual ban") -> bool:
+    """Ban an IP outright."""
+    from .firewall import BAN
+    return _firewall().ban_permanent(ip, reason).action == BAN
+
+
+def whitelist(ip: Optional[str] = None, remove: bool = False):
+    """No argument lists the whitelist; an IP adds or removes one.
+
+    A whitelisted IP is never blocked by anything, which is also your way
+    out if a rule turns on you.
+    """
+    firewall = _firewall()
+    if ip is None:
+        return firewall.get_whitelist()
+    return firewall.remove_whitelist(ip) if remove else firewall.add_whitelist(ip)
+
+
+def reload_signatures() -> int:
+    """Re-read the signature directory. Returns how many are loaded."""
+    return _need_guard().reload_signatures()
+
+
+def signatures() -> list:
+    """The loaded signatures."""
+    if _guard is not None:
+        return _guard.signatures
+    from .utils import load_signatures
+    _, cfg = _offline_firewall()
+    return load_signatures(cfg.signatures_dir)
+
+
+# ─── Feedback ────────────────────────────────────────────────────────
+def events(limit: int = 30) -> list:
+    """Recent firewall decisions, each with an id you can mark wrong."""
+    from .feedback import FeedbackTracker
+    firewall = _firewall()
+    cfg = _cfg or _offline_firewall()[1]
+    return FeedbackTracker(cfg, firewall).recent_events(limit=limit)
+
+
+def wrong(event_id: str, unblock: bool = False) -> dict:
+    """Mark a firewall decision as a false positive.
+
+    Nothing is changed automatically. After enough marks for the same
+    signature, ZeroV4 tells you which file to look at — you decide.
+    Pass unblock=True to also release that IP.
+    """
+    from .feedback import FeedbackTracker
+    firewall = _firewall()
+    cfg = _cfg or _offline_firewall()[1]
+    return FeedbackTracker(cfg, firewall).mark_wrong(event_id, unblock=unblock)
+
+
+def suggestions() -> list:
+    """Signatures that have been wrong often enough to be worth a look."""
+    from .feedback import FeedbackTracker
+    cfg = _cfg or _offline_firewall()[1]
+    return FeedbackTracker(cfg, _firewall()).suggestions()
+
+
+# ─── Panel password ──────────────────────────────────────────────────
+def set_panel_password(password: Optional[str] = None) -> Optional[str]:
+    """Set the panel password.
+
+    No argument prompts for one (and offers to generate). Only the PBKDF2
+    hash is written to .env; the password itself never touches disk.
+    Returns the generated password if one was generated, else None.
+    """
+    from .auth import prompt_panel_password, write_env_value, ENV_KEY
+    from .auth import hash_password, password_strength
+
+    if password is None:
+        _, generated = prompt_panel_password()
+        return generated
+
+    ok, message = password_strength(password)
+    if not ok:
+        raise ValueError(message)
+    write_env_value(ENV_KEY, hash_password(password))
+    return None
+
+
+# ─── Config ──────────────────────────────────────────────────────────
+def config() -> Optional[Config]:
+    """The Config in use, if a guard is running."""
+    return _cfg
+
+
+def guard():
+    """The live ZeroGuard instance. For when the facade isn't enough."""
+    return _guard
+
+
+__all__ = [
+    "run", "wrap", "stop", "init",
+    "status", "blocked", "reputation", "attacks", "is_blocked",
+    "unblock", "ban", "whitelist",
+    "signatures", "reload_signatures",
+    "events", "wrong", "suggestions",
+    "set_panel_password", "config", "guard",
+]