zerov4 0.1.0__tar.gz

zerov4-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 Barış (BRSX-Labs)
+
+   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.

zerov4-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE NOTICE README.md
+recursive-include zerov4/signatures *.py

zerov4-0.1.0/NOTICE

@@ -0,0 +1,6 @@
+ZeroV4
+Copyright 2026 Barış (BRSX-Labs)
+
+This product includes software developed by Barış (BRSX-Labs).
+
+Derived from Autonomous Agent Zero-V4.

zerov4-0.1.0/PKG-INFO

@@ -0,0 +1,327 @@
+Metadata-Version: 2.4
+Name: zerov4
+Version: 0.1.0
+Summary: Request-level protection for WSGI applications: signatures, rate limiting, honeypots, IP reputation and a bot challenge, inspected before your app sees the request.
+Author: Barış
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/brsx-labs/zerov4
+Project-URL: Issues, https://github.com/brsx-labs/zerov4/issues
+Keywords: security,waf,firewall,wsgi,flask,rate-limiting,bot-detection,honeypot,intrusion-detection
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Networking :: Firewalls
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: werkzeug>=2.0
+Provides-Extra: redis
+Requires-Dist: redis>=4.0; extra == "redis"
+Provides-Extra: geoip
+Requires-Dist: geoip2>=4.0; extra == "geoip"
+Provides-Extra: prod
+Requires-Dist: waitress>=2.0; extra == "prod"
+Provides-Extra: toml
+Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "toml"
+Provides-Extra: all
+Requires-Dist: redis>=4.0; extra == "all"
+Requires-Dist: geoip2>=4.0; extra == "all"
+Requires-Dist: waitress>=2.0; extra == "all"
+Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: flask>=2.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# ZeroV4
+
+Request-level protection for WSGI applications. Signatures, rate limiting, honeypots, IP reputation, and a bot challenge — all applied **before** your app sees the request.
+
+```python
+from zerov4 import arx
+from myapp import app
+
+arx.run(app)
+```
+
+That's it. ZeroV4 asks for a port, a debug flag and a protection level, then serves your app with every request inspected first.
+
+---
+
+## Install
+
+```bash
+pip install zerov4
+```
+
+Optional extras:
+
+```bash
+pip install zerov4[redis]   # Redis-backed storage
+pip install zerov4[geoip]   # country lookup for blocked IPs
+pip install zerov4[prod]    # waitress, for serving in production
+pip install zerov4[all]
+```
+
+Core dependency: `werkzeug`. That's the whole list. A security package that pulls in half of PyPI has a larger attack surface than the attacks it stops.
+
+---
+
+## Usage
+
+### The quick way
+
+```python
+from zerov4 import arx
+from myapp import app
+
+arx.run(app)                 # menu, then serve
+arx.run(app, port=8080)      # port answered, so not asked
+arx.run("myapp:app")         # import it by name
+arx.run(interactive=False)   # no questions at all
+```
+
+### Under gunicorn
+
+`run()` serves the app itself. If gunicorn/uwsgi is doing that, wrap instead:
+
+```python
+# wsgi.py
+from zerov4 import arx
+from myapp import app
+
+application = arx.wrap(app)
+```
+
+```bash
+gunicorn wsgi:application -w 4
+```
+
+### As middleware
+
+```python
+from flask import Flask
+from zerov4 import ZeroGuard, make_config
+
+app = Flask(__name__)
+app.wsgi_app = ZeroGuard(app.wsgi_app, cfg=make_config("balanced"))
+```
+
+It's plain WSGI, so Django, Bottle, Pyramid and anything else that speaks the protocol work the same way.
+
+### From the shell
+
+```bash
+zerov4 init              # configure interactively, write zerov4.toml
+zerov4 run myapp:app     # serve
+zerov4 status            # what the firewall knows
+zerov4 unblock 1.2.3.4
+zerov4 whitelist 10.0.0.5
+zerov4 signatures        # what's loaded
+```
+
+---
+
+## Protection levels
+
+| | `permissive` | `balanced` *(default)* | `paranoid` |
+|---|---|---|---|
+| Ban threshold | 20 hits | 10 hits | 10 hits |
+| Rate limit | 300 / 10s | 100 / 10s | 10 / 1s |
+| 404s count as attacks | no | no | **yes** |
+| Non-JSON body is an attack | no | no | **yes** |
+| Fuzzy keyword matching | no | no | **yes** |
+| Session bound to IP | no | no | **yes** |
+| Bot challenge | off | on | on |
+| Pattern analysis | off | on | on |
+| Blocking throttle | no | no | **yes** |
+
+**Balanced** is tuned for a site with real visitors and is what you want unless you have a reason.
+
+**Paranoid** is the original Autonomous Agent Zero-V4 behaviour, kept intact. It treats ordinary traffic as hostile: every 404, every HTML form post, and fuzzy keyword matches all count toward a ban. Mobile users switching from WiFi to cellular change IP, which paranoid reads as session theft. It is for a target you control, not a public site. ZeroV4 asks you to confirm before enabling it.
+
+---
+
+## What it does
+
+**Signatures.** Keyword matching plus stateful `detect()` functions that count across a time window. Keywords are word-bounded, so `select` does not match `/products/selectbox`.
+
+**Escalating throttle.** Hit 1 costs 2 seconds, hit 2 costs 4, hit 9 costs 300 (capped). Hit 10 is a permanent ban. Throttling returns `429` with `Retry-After` immediately — it does not hold a worker asleep.
+
+**IP reputation.** Banned addresses are remembered and blocked on sight next time, without earning hits again. Entries expire when they haven't been seen for a while, so an address that changed hands isn't blocked forever.
+
+**Honeypots.** `/.env`, `/wp-admin`, `/phpmyadmin` and friends. One request is an instant ban.
+
+**Bot challenge.** Throttled browsers get an arithmetic question plus pointer-movement analysis instead of a flat 429, so a real person can prove it and carry on. Touch devices are not punished for having no `mousemove`.
+
+**Pattern analysis.** Correlates across IPs: coordinated attacks, slow reconnaissance, multi-category probing, rapid escalation.
+
+**Feedback loop.** Mark a decision wrong; after enough marks for the same signature, ZeroV4 tells you which file to look at. It never edits its own rules, never unbans on its own, never weakens anything by itself. The decision is yours.
+
+**SOC panel.** Live stats, blocked list, reputation, whitelist, event log, suggestions. Password-protected, hash in `.env`.
+
+---
+
+## Configuration
+
+```python
+from zerov4 import make_config, arx
+
+cfg = make_config(
+    "balanced",
+    port=8080,
+    trusted_proxies=("10.0.0.0/8",),   # required behind nginx/Cloudflare
+    redis_url="redis://localhost:6379",
+    geoip_db="GeoLite2-Country.mmdb",
+)
+arx.run(app, cfg=cfg)
+```
+
+Or `zerov4.toml`:
+
+```toml
+[zerov4]
+level = "balanced"
+port = 5000
+storage = "auto"
+panel_enabled = true
+trusted_proxies = ["10.0.0.0/8"]
+```
+
+Or the environment: `ZEROV4_PORT=8080 ZEROV4_LEVEL=paranoid`.
+
+### Behind a proxy
+
+**Set `trusted_proxies` if anything sits in front of your app.** Forwarding headers are only honoured when the direct peer is on that list. Without it, an attacker sends `X-Real-IP: <your customer>` and gets your customer banned while staying clean. With no proxy configured, `REMOTE_ADDR` is used and headers are ignored.
+
+### Hooks
+
+ZeroV4 does not touch your machine's network, kill processes, or click anything. If you want that, wire it up:
+
+```python
+def on_coordinated(ips, reason):
+    print(f"{len(ips)} attackers: {reason}")
+    # your own response here
+
+cfg = make_config("balanced",
+                  on_coordinated_attack=on_coordinated,
+                  on_ban=lambda ip, attack, entry: notify(ip),
+                  on_threat_cleared=lambda: print("clear"))
+```
+
+---
+
+## Custom signatures
+
+A signature is a module with a `NAME` and either `KEYWORDS`, a `detect()` function, or both.
+
+```python
+# signatures/my_rule.py
+NAME     = "Admin Panel Probing"
+KEYWORDS = ["/wp-login", "/administrator"]
+
+def detect(line, parsed, now, counters):
+    ip = parsed["ip"]
+    if "admin" in line.lower():
+        counters["admin_probe"][ip].append(now)
+        counters["admin_probe"][ip] = [
+            t for t in counters["admin_probe"][ip] if now - t <= 60
+        ]
+        if len(counters["admin_probe"][ip]) >= 5:
+            return f"{len(counters['admin_probe'][ip])} admin probes in 60s"
+    return None
+```
+
+Point at your own directory:
+
+```python
+cfg = make_config("balanced", signatures_dir="./signatures")
+```
+
+A signature that raises is logged and quarantined for the run, not allowed to take the request down with it.
+
+Loading a signature directory imports and executes those `.py` files. Don't point it at a directory other people can write to.
+
+---
+
+## Panel
+
+```bash
+zerov4 init     # asks for a panel password
+```
+
+The password is never written to disk — only a PBKDF2-SHA256 hash, into `.env` at mode 0600. Add `.env` to your `.gitignore`; ZeroV4 warns you if you haven't.
+
+Panel lives at `/panel` by default. It fails closed: no password set means no logins, not an open door.
+
+---
+
+## API
+
+```python
+from zerov4 import arx
+
+arx.run(app)                    # serve
+arx.wrap(app)                   # wrap only (gunicorn)
+arx.stop()
+
+arx.status()                    # stats dict
+arx.blocked()                   # list of blocked IPs
+arx.reputation()                # learned bad IPs
+arx.attacks(20)                 # recent detections
+arx.is_blocked("1.2.3.4")
+
+arx.unblock("1.2.3.4")
+arx.ban("1.2.3.4")
+arx.whitelist("10.0.0.5")       # never blocked
+arx.whitelist()                 # list
+
+arx.events()                    # firewall decisions, with ids
+arx.wrong(event_id)             # mark a false positive
+arx.suggestions()               # signatures worth reviewing
+
+arx.set_panel_password()
+arx.reload_signatures()
+```
+
+---
+
+## Notes
+
+**Locked out?** A whitelisted address is never blocked by any rule. Add yours before tightening anything: `zerov4 whitelist YOUR.IP`. Whitelisting an already-banned IP clears the ban.
+
+**Storage.** Redis if reachable, JSON files otherwise, both automatic. `storage="redis"` fails loudly instead of silently degrading — a security system whose bans quietly stop persisting is worse than one that tells you.
+
+**Multiple workers.** Under `gunicorn -w 4`, use Redis. With JSON, each worker keeps its own view and rate limits count per worker.
+
+**Failure mode.** If ZeroV4 itself crashes mid-inspection, the request is allowed and the error is logged. A bug here should cost you protection, not uptime.
+
+**Threads.** A background agent handles pattern analysis and cleanup, and a saver persists state periodically. Both are daemon threads that stop cleanly.
+
+---
+
+## Status
+
+Beta. Test it against your own traffic before putting it in front of anything that matters — start at `permissive` or `balanced`, watch what gets blocked, then tighten. A misconfigured WAF either bans your users or waves the attacker through, and only your traffic can tell you which one you have.
+
+---
+
+## Credits
+
+Derived from Autonomous Agent Zero-V4 by Barış ([BRSX-Labs](https://github.com/brsx-labs)).
+
+MIT.