scudo-waf 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. scudo_waf-1.0.0/LICENSE +21 -0
  2. scudo_waf-1.0.0/MANIFEST.in +4 -0
  3. scudo_waf-1.0.0/PKG-INFO +135 -0
  4. scudo_waf-1.0.0/README.md +79 -0
  5. scudo_waf-1.0.0/pyproject.toml +103 -0
  6. scudo_waf-1.0.0/scudo_waf/__init__.py +37 -0
  7. scudo_waf-1.0.0/scudo_waf/adapters.py +388 -0
  8. scudo_waf-1.0.0/scudo_waf/cli.py +128 -0
  9. scudo_waf-1.0.0/scudo_waf/config.py +97 -0
  10. scudo_waf-1.0.0/scudo_waf/engine.py +367 -0
  11. scudo_waf-1.0.0/scudo_waf/middleware.py +491 -0
  12. scudo_waf-1.0.0/scudo_waf/models/cervello_waf.pkl +0 -0
  13. scudo_waf-1.0.0/scudo_waf/models/model_metadata.json +92 -0
  14. scudo_waf-1.0.0/scudo_waf/models/traduttore_waf.pkl +0 -0
  15. scudo_waf-1.0.0/scudo_waf/normalizer.py +214 -0
  16. scudo_waf-1.0.0/scudo_waf/patterns.py +190 -0
  17. scudo_waf-1.0.0/scudo_waf/pii.py +192 -0
  18. scudo_waf-1.0.0/scudo_waf/proxy.py +174 -0
  19. scudo_waf-1.0.0/scudo_waf/py.typed +0 -0
  20. scudo_waf-1.0.0/scudo_waf/telemetry.py +97 -0
  21. scudo_waf-1.0.0/scudo_waf.egg-info/PKG-INFO +135 -0
  22. scudo_waf-1.0.0/scudo_waf.egg-info/SOURCES.txt +33 -0
  23. scudo_waf-1.0.0/scudo_waf.egg-info/dependency_links.txt +1 -0
  24. scudo_waf-1.0.0/scudo_waf.egg-info/entry_points.txt +2 -0
  25. scudo_waf-1.0.0/scudo_waf.egg-info/requires.txt +27 -0
  26. scudo_waf-1.0.0/scudo_waf.egg-info/top_level.txt +1 -0
  27. scudo_waf-1.0.0/setup.cfg +4 -0
  28. scudo_waf-1.0.0/tests/test_adapters.py +69 -0
  29. scudo_waf-1.0.0/tests/test_engine.py +86 -0
  30. scudo_waf-1.0.0/tests/test_false_positives.py +94 -0
  31. scudo_waf-1.0.0/tests/test_middleware.py +178 -0
  32. scudo_waf-1.0.0/tests/test_normalizer.py +46 -0
  33. scudo_waf-1.0.0/tests/test_patterns.py +52 -0
  34. scudo_waf-1.0.0/tests/test_pii_and_evasion.py +176 -0
  35. scudo_waf-1.0.0/tests/test_proxy_and_cli.py +102 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mirko Rainone (KShield)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,4 @@
1
+ include LICENSE
2
+ include README.md
3
+ include scudo_waf/py.typed
4
+ recursive-include scudo_waf/models *.pkl *.json
@@ -0,0 +1,135 @@
1
+ Metadata-Version: 2.4
2
+ Name: scudo-waf
3
+ Version: 1.0.0
4
+ Summary: AI-Powered Hybrid Web Application Firewall (Regex + Cache + ML) for Python APIs and LLM applications
5
+ Author-email: Mirko Rainone <mirkorainone@users.noreply.github.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/MirkoRainone/scudo-waf
8
+ Project-URL: Documentation, https://github.com/MirkoRainone/scudo-waf#readme
9
+ Project-URL: Repository, https://github.com/MirkoRainone/scudo-waf
10
+ Project-URL: Issues, https://github.com/MirkoRainone/scudo-waf/issues
11
+ Keywords: waf,security,fastapi,flask,django,ai,llm,prompt-injection,cybersecurity,xss,sql-injection,firewall
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Topic :: Security
15
+ Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
16
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.9
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Programming Language :: Python :: 3.14
24
+ Classifier: Typing :: Typed
25
+ Classifier: Framework :: FastAPI
26
+ Classifier: Framework :: Flask
27
+ Classifier: Framework :: Django
28
+ Classifier: Operating System :: OS Independent
29
+ Requires-Python: >=3.9
30
+ Description-Content-Type: text/markdown
31
+ License-File: LICENSE
32
+ Requires-Dist: starlette>=0.27.0
33
+ Requires-Dist: cachetools>=5.0.0
34
+ Requires-Dist: scikit-learn>=1.3.0
35
+ Requires-Dist: joblib>=1.3.0
36
+ Provides-Extra: telemetry
37
+ Requires-Dist: httpx>=0.24.0; extra == "telemetry"
38
+ Provides-Extra: proxy
39
+ Requires-Dist: httpx>=0.24.0; extra == "proxy"
40
+ Requires-Dist: uvicorn>=0.24.0; extra == "proxy"
41
+ Provides-Extra: all
42
+ Requires-Dist: httpx>=0.24.0; extra == "all"
43
+ Requires-Dist: uvicorn>=0.24.0; extra == "all"
44
+ Provides-Extra: dev
45
+ Requires-Dist: pytest>=7.0; extra == "dev"
46
+ Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
47
+ Requires-Dist: pytest-cov>=4.0; extra == "dev"
48
+ Requires-Dist: httpx>=0.24.0; extra == "dev"
49
+ Requires-Dist: uvicorn>=0.24.0; extra == "dev"
50
+ Requires-Dist: fastapi>=0.100.0; extra == "dev"
51
+ Requires-Dist: ruff>=0.4.0; extra == "dev"
52
+ Requires-Dist: mypy>=1.8; extra == "dev"
53
+ Requires-Dist: build>=1.0; extra == "dev"
54
+ Requires-Dist: twine>=5.0; extra == "dev"
55
+ Dynamic: license-file
56
+
57
+ # ๐Ÿ›ก๏ธ Scudo WAF โ€” AI-Powered Hybrid Web Application & LLM Firewall
58
+
59
+ [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-3776ab.svg)](https://www.python.org/)
60
+ [![Version 1.0.0](https://img.shields.io/badge/version-1.0.0-10b981.svg)](https://pypi.org/project/scudo-waf/)
61
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
62
+ [![Typing: PEP 561](https://img.shields.io/badge/typing-PEP%20561-blueviolet.svg)](https://peps.python.org/pep-0561/)
63
+
64
+ **Scudo WAF** (`scudo-waf`) is an **in-memory Hybrid Web Application Firewall**, **LLM Prompt Injection & PII/Secret Guard**, and **Universal Reverse-Proxy Sidecar**. Run sub-millisecond protection inside your Python process (**FastAPI**, **Starlette**, **Flask**, **Django**) or place the `scudo-waf proxy` sidecar in front of any Node.js, Go, PHP, or Java service.
65
+
66
+ ---
67
+
68
+ ## โœจ Key Features (v1.0.0)
69
+
70
+ - **Multi-Layer Hybrid Engine**:
71
+ - **L0 Blocklist & Rate Limiter**: Explicit per-IP blocklists/allowlists (`403`) and sliding-window per-IP rate limiting (`429 Too Many Requests`).
72
+ - **L1 Structural De-obfuscation & Regex Shield**: Iterative URL/HTML/NFKC normalization, MySQL conditional comment unwrapping (`/*!50000...*/`), smart SQL block comment stripping, inline `0x...` hex & Base64 decoding, covering SQLi, XSS/SSTI, Path Traversal, Command Injection, SSRF, and multilingual Prompt Injection.
73
+ - **L2 Smart TTL Cache**: SHA-256 keyed in-memory decision cache (`~0.05 ms`).
74
+ - **L3 ML Neural Engine**: Dual char/word TF-IDF `FeatureUnion` + `CalibratedLinearSVC` trained on **53,100 strictly unique samples** with calibrated threshold `0.75`.
75
+ - **LLM PromptGuard + PII & Secret Redactor**: `@guard.protect` blocks prompt injections, oversized inputs, and exposed secrets (`sk-...`, AWS `AKIA...`, GitHub `ghp_...`, JWTs) while automatically masking emails, Luhn-valid credit cards, IBANs, Italian Codice Fiscale, and phone numbers.
76
+ - **Universal Reverse-Proxy Sidecar & CLI**: Official `scudo-waf` CLI (`scan`, `stats`, `proxy`) to inspect payloads or protect any HTTP upstream app without touching application source code.
77
+
78
+ ---
79
+
80
+ ## ๐Ÿš€ Quick Start
81
+
82
+ ```bash
83
+ pip install scudo-waf
84
+ # Or include universal reverse-proxy & CLI server support:
85
+ pip install "scudo-waf[proxy]"
86
+ ```
87
+
88
+ ### FastAPI / Starlette
89
+
90
+ ```python
91
+ from fastapi import FastAPI
92
+ from scudo_waf import WafMiddleware
93
+
94
+ app = FastAPI()
95
+ app.add_middleware(WafMiddleware, expose_headers=True)
96
+ ```
97
+
98
+ ### LLM PromptGuard with PII Redaction & Secret Leak Blocking
99
+
100
+ ```python
101
+ from scudo_waf import PromptGuard, PromptInjectionError
102
+
103
+ guard = PromptGuard(redact_pii=True, block_secrets=True, max_prompt_chars=4000)
104
+
105
+ @guard.protect
106
+ def ask_llm(prompt: str) -> str:
107
+ # Sensitive emails / credit cards / IBANs are masked to [REDACTED_*] automatically!
108
+ return call_my_model(prompt)
109
+ ```
110
+
111
+ ### Universal Reverse-Proxy Sidecar & CLI
112
+
113
+ ```bash
114
+ scudo-waf scan "' OR 1=1 --" --json
115
+ scudo-waf proxy --upstream http://127.0.0.1:3000 --port 8081 --mode block
116
+ ```
117
+
118
+ ---
119
+
120
+ ## ๐Ÿ“Š Verified Holdout Evaluation & Benchmarks (`v1.0.0`)
121
+
122
+ | Metric | Measured Result |
123
+ |--------|-----------------|
124
+ | Training Corpus | `53,100` strictly unique samples (`30,000` benign / `23,100` malicious) |
125
+ | Selected Model | `CalibratedLinearSVC` (threshold `0.75`) |
126
+ | Holdout Accuracy / F1 / ROC-AUC | `1.0000` (`TN=6000, FP=0, FN=0, TP=4620` across `10,620` unseen samples) |
127
+ | Hard-Negative Smoke Checks | `24 / 24` Benign Passed (`0` FP) ยท `12 / 12` Attacks Blocked |
128
+ | **L1-Regex / L2-Cache / L3-ML p50** | `0.014 ms` / `0.054 ms` / `4.04 ms` |
129
+ | **ASGI Middleware Throughput** | `1,180.7 req/s` (1,000 mixed HTTP requests in `0.85 s`) |
130
+
131
+ ---
132
+
133
+ ## ๐Ÿ“„ License
134
+
135
+ MIT License โ€” Copyright (c) 2026 Mirko Rainone (KShield).
@@ -0,0 +1,79 @@
1
+ # ๐Ÿ›ก๏ธ Scudo WAF โ€” AI-Powered Hybrid Web Application & LLM Firewall
2
+
3
+ [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-3776ab.svg)](https://www.python.org/)
4
+ [![Version 1.0.0](https://img.shields.io/badge/version-1.0.0-10b981.svg)](https://pypi.org/project/scudo-waf/)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6
+ [![Typing: PEP 561](https://img.shields.io/badge/typing-PEP%20561-blueviolet.svg)](https://peps.python.org/pep-0561/)
7
+
8
+ **Scudo WAF** (`scudo-waf`) is an **in-memory Hybrid Web Application Firewall**, **LLM Prompt Injection & PII/Secret Guard**, and **Universal Reverse-Proxy Sidecar**. Run sub-millisecond protection inside your Python process (**FastAPI**, **Starlette**, **Flask**, **Django**) or place the `scudo-waf proxy` sidecar in front of any Node.js, Go, PHP, or Java service.
9
+
10
+ ---
11
+
12
+ ## โœจ Key Features (v1.0.0)
13
+
14
+ - **Multi-Layer Hybrid Engine**:
15
+ - **L0 Blocklist & Rate Limiter**: Explicit per-IP blocklists/allowlists (`403`) and sliding-window per-IP rate limiting (`429 Too Many Requests`).
16
+ - **L1 Structural De-obfuscation & Regex Shield**: Iterative URL/HTML/NFKC normalization, MySQL conditional comment unwrapping (`/*!50000...*/`), smart SQL block comment stripping, inline `0x...` hex & Base64 decoding, covering SQLi, XSS/SSTI, Path Traversal, Command Injection, SSRF, and multilingual Prompt Injection.
17
+ - **L2 Smart TTL Cache**: SHA-256 keyed in-memory decision cache (`~0.05 ms`).
18
+ - **L3 ML Neural Engine**: Dual char/word TF-IDF `FeatureUnion` + `CalibratedLinearSVC` trained on **53,100 strictly unique samples** with calibrated threshold `0.75`.
19
+ - **LLM PromptGuard + PII & Secret Redactor**: `@guard.protect` blocks prompt injections, oversized inputs, and exposed secrets (`sk-...`, AWS `AKIA...`, GitHub `ghp_...`, JWTs) while automatically masking emails, Luhn-valid credit cards, IBANs, Italian Codice Fiscale, and phone numbers.
20
+ - **Universal Reverse-Proxy Sidecar & CLI**: Official `scudo-waf` CLI (`scan`, `stats`, `proxy`) to inspect payloads or protect any HTTP upstream app without touching application source code.
21
+
22
+ ---
23
+
24
+ ## ๐Ÿš€ Quick Start
25
+
26
+ ```bash
27
+ pip install scudo-waf
28
+ # Or include universal reverse-proxy & CLI server support:
29
+ pip install "scudo-waf[proxy]"
30
+ ```
31
+
32
+ ### FastAPI / Starlette
33
+
34
+ ```python
35
+ from fastapi import FastAPI
36
+ from scudo_waf import WafMiddleware
37
+
38
+ app = FastAPI()
39
+ app.add_middleware(WafMiddleware, expose_headers=True)
40
+ ```
41
+
42
+ ### LLM PromptGuard with PII Redaction & Secret Leak Blocking
43
+
44
+ ```python
45
+ from scudo_waf import PromptGuard, PromptInjectionError
46
+
47
+ guard = PromptGuard(redact_pii=True, block_secrets=True, max_prompt_chars=4000)
48
+
49
+ @guard.protect
50
+ def ask_llm(prompt: str) -> str:
51
+ # Sensitive emails / credit cards / IBANs are masked to [REDACTED_*] automatically!
52
+ return call_my_model(prompt)
53
+ ```
54
+
55
+ ### Universal Reverse-Proxy Sidecar & CLI
56
+
57
+ ```bash
58
+ scudo-waf scan "' OR 1=1 --" --json
59
+ scudo-waf proxy --upstream http://127.0.0.1:3000 --port 8081 --mode block
60
+ ```
61
+
62
+ ---
63
+
64
+ ## ๐Ÿ“Š Verified Holdout Evaluation & Benchmarks (`v1.0.0`)
65
+
66
+ | Metric | Measured Result |
67
+ |--------|-----------------|
68
+ | Training Corpus | `53,100` strictly unique samples (`30,000` benign / `23,100` malicious) |
69
+ | Selected Model | `CalibratedLinearSVC` (threshold `0.75`) |
70
+ | Holdout Accuracy / F1 / ROC-AUC | `1.0000` (`TN=6000, FP=0, FN=0, TP=4620` across `10,620` unseen samples) |
71
+ | Hard-Negative Smoke Checks | `24 / 24` Benign Passed (`0` FP) ยท `12 / 12` Attacks Blocked |
72
+ | **L1-Regex / L2-Cache / L3-ML p50** | `0.014 ms` / `0.054 ms` / `4.04 ms` |
73
+ | **ASGI Middleware Throughput** | `1,180.7 req/s` (1,000 mixed HTTP requests in `0.85 s`) |
74
+
75
+ ---
76
+
77
+ ## ๐Ÿ“„ License
78
+
79
+ MIT License โ€” Copyright (c) 2026 Mirko Rainone (KShield).
@@ -0,0 +1,103 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "scudo-waf"
7
+ version = "1.0.0"
8
+ description = "AI-Powered Hybrid Web Application Firewall (Regex + Cache + ML) for Python APIs and LLM applications"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.9"
12
+ authors = [
13
+ { name = "Mirko Rainone", email = "mirkorainone@users.noreply.github.com" },
14
+ ]
15
+ keywords = [
16
+ "waf",
17
+ "security",
18
+ "fastapi",
19
+ "flask",
20
+ "django",
21
+ "ai",
22
+ "llm",
23
+ "prompt-injection",
24
+ "cybersecurity",
25
+ "xss",
26
+ "sql-injection",
27
+ "firewall",
28
+ ]
29
+ classifiers = [
30
+ "Development Status :: 4 - Beta",
31
+ "Intended Audience :: Developers",
32
+ "Topic :: Security",
33
+ "Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware",
34
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
35
+ "Programming Language :: Python :: 3",
36
+ "Programming Language :: Python :: 3.9",
37
+ "Programming Language :: Python :: 3.10",
38
+ "Programming Language :: Python :: 3.11",
39
+ "Programming Language :: Python :: 3.12",
40
+ "Programming Language :: Python :: 3.13",
41
+ "Programming Language :: Python :: 3.14",
42
+ "Typing :: Typed",
43
+ "Framework :: FastAPI",
44
+ "Framework :: Flask",
45
+ "Framework :: Django",
46
+ "Operating System :: OS Independent",
47
+ ]
48
+ dependencies = [
49
+ "starlette>=0.27.0",
50
+ "cachetools>=5.0.0",
51
+ "scikit-learn>=1.3.0",
52
+ "joblib>=1.3.0",
53
+ ]
54
+
55
+ [project.optional-dependencies]
56
+ telemetry = ["httpx>=0.24.0"]
57
+ proxy = ["httpx>=0.24.0", "uvicorn>=0.24.0"]
58
+ all = ["httpx>=0.24.0", "uvicorn>=0.24.0"]
59
+ dev = [
60
+ "pytest>=7.0",
61
+ "pytest-asyncio>=0.21",
62
+ "pytest-cov>=4.0",
63
+ "httpx>=0.24.0",
64
+ "uvicorn>=0.24.0",
65
+ "fastapi>=0.100.0",
66
+ "ruff>=0.4.0",
67
+ "mypy>=1.8",
68
+ "build>=1.0",
69
+ "twine>=5.0",
70
+ ]
71
+
72
+ [project.scripts]
73
+ scudo-waf = "scudo_waf.cli:main"
74
+
75
+ [project.urls]
76
+ Homepage = "https://github.com/MirkoRainone/scudo-waf"
77
+ Documentation = "https://github.com/MirkoRainone/scudo-waf#readme"
78
+ Repository = "https://github.com/MirkoRainone/scudo-waf"
79
+ Issues = "https://github.com/MirkoRainone/scudo-waf/issues"
80
+
81
+ [tool.setuptools.packages.find]
82
+ include = ["scudo_waf*"]
83
+
84
+ [tool.setuptools.package-data]
85
+ scudo_waf = ["py.typed", "models/*.pkl", "models/*.json"]
86
+
87
+ [tool.ruff]
88
+ line-length = 110
89
+ target-version = "py39"
90
+
91
+ [tool.ruff.lint]
92
+ select = ["E", "F", "I", "N", "W", "UP", "B", "C4"]
93
+ ignore = ["E501", "N803", "N806", "N999", "B905"]
94
+
95
+ [tool.mypy]
96
+ python_version = "3.9"
97
+ warn_return_any = true
98
+ warn_unused_configs = true
99
+ ignore_missing_imports = true
100
+
101
+ [tool.pytest.ini_options]
102
+ asyncio_mode = "auto"
103
+ testpaths = ["tests"]
@@ -0,0 +1,37 @@
1
+ """Scudo WAF โ€” AI-Powered Hybrid Web Application Firewall for Python APIs & LLMs."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from .adapters import (
6
+ PromptGuard,
7
+ PromptInjectionError,
8
+ ScudoDjangoMiddleware,
9
+ ScudoFlask,
10
+ )
11
+ from .config import InspectionResult, ThreatCategory, WafConfig, WafMode
12
+ from .engine import ScudoEngine, analyze, get_default_engine
13
+ from .middleware import WafMiddleware
14
+ from .pii import PiiRedactor, RedactionResult, redact_sensitive_data
15
+ from .proxy import create_proxy_app
16
+
17
+ __version__ = "1.0.0"
18
+
19
+ __all__ = [
20
+ "__version__",
21
+ "WafMiddleware",
22
+ "ScudoEngine",
23
+ "WafConfig",
24
+ "WafMode",
25
+ "ThreatCategory",
26
+ "InspectionResult",
27
+ "analyze",
28
+ "get_default_engine",
29
+ "ScudoFlask",
30
+ "ScudoDjangoMiddleware",
31
+ "PromptGuard",
32
+ "PromptInjectionError",
33
+ "PiiRedactor",
34
+ "RedactionResult",
35
+ "redact_sensitive_data",
36
+ "create_proxy_app",
37
+ ]