phpwarden 2.2.0__tar.gz → 2.3.0__tar.gz

{phpwarden-2.2.0 → phpwarden-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phpwarden
-Version: 2.2.0
+Version: 2.3.0
 Summary: PHP vulnerability scanner for the PHP engine, Composer, WordPress, your own code and the live site. Ranked by real-world exploitation (CISA KEV, then EPSS), not CVSS. Offline, zero dependencies.
 Author: oroma-alfred
 License-Expression: Apache-2.0
@@ -59,7 +59,8 @@ $ phpwarden deps composer.lock
 | Composer dependency CVEs | `deps` | Snyk, `composer audit` |
 | WordPress core, plugin and theme CVEs | `wordpress` | Patchstack, Wordfence |
 | WordPress file integrity (wordpress.org checksums, injected files) | `integrity` | Wordfence CLI malware-scan (partly) |
-| Your own PHP code (75 rules) | `code` | — (not a PHPStan/Psalm replacement) |
+| Your own PHP code: whole-program, Laravel/Symfony/WordPress-aware (89 rules) | `code` | Snyk Code, Semgrep, Psalm taint |
+| Exploits of the vulnerabilities this site has, blocked inside PHP | `shield` | the WAF rule you would have to write |
 | Live site from outside: exposed files, debug endpoints | `probe` | — |
 | One ranked verdict across all of the above | `assess` | — |
 | Exploitation signatures in logs | `detect` | SIEM content |
@@ -120,7 +121,8 @@ phpwarden rules --format nginx --out php-block.conf   # PHP-specific WAF rules (
 phpwarden rules --format nginx --dry-run     # the same rules, log-only: nothing is blocked
 phpwarden rules --replay /var/log/nginx/access.log    # what the rules would have blocked in an existing log
 phpwarden probe https://example.com  # live check of a site you own: exposed files, debug endpoints, versions vs the feed
-phpwarden code .                     # your own PHP: 75 high-signal rules, 74 on by default (injection, unserialize, WordPress handlers)
+phpwarden code .                     # your own PHP, whole program: 89 rules (injection, auth, mass assignment, Blade/Twig, WordPress)
+phpwarden shield policy . && phpwarden shield install   # block exploits of what is installed here, inside PHP (log-only first)
 phpwarden assess . --url https://example.com --log access.log   # one ranked verdict; --out / --baseline shows what is fixed and verified
 phpwarden report web01.json web02.json --out fleet.html   # aggregate a fleet view
 phpwarden feed status                # which feed is active, how many advisories
@@ -133,7 +135,7 @@ phpwarden feed update                # pull a newer feed: free weekly snapshot,
 `probe`, `code`, `assess`, `--format sarif`, `rules --dry-run` / `--replay` and
 the no-key `feed update` are new in 2.2.0.
 
-Every command takes `--json`. Exit codes are shared across subcommands and
+Every scanning command takes `--json` (`shield install` and `shield promote` do not). Exit codes are shared across subcommands and
 built for gating: `0` clean, `1` exposed / vulnerable / signature hits / tampered
 files / high or critical `code` and `probe` findings (`probe` also on any
 known-exploited finding) / anything to act on now or this week (`assess`),
@@ -142,7 +144,7 @@ error, `5` `--report-to` upload failed on an otherwise clean run, `64` usage
 error. Full table: `phpwarden --help`.
 
 
-## New in 2.2.0
+## New in 2.3.0 and 2.2
 
 - **`phpwarden probe URL`**: a live check of a running site using GET and HEAD
   requests only. It looks for exposed files (`.env`, `.git`, backups), open debug
@@ -150,10 +152,21 @@ error. Full table: `phpwarden --help`.
   matches those against the feed. Active checks run only after you prove the
   site is yours (DNS TXT record, a file, or a meta tag; `--print-token` shows
   how). Without that it reads the homepage and stops.
-- **`phpwarden code PATH`**: 75 rules (74 on by default) for your own PHP code, following request
-  data to `eval`, shell commands, SQL, `unserialize`, includes and redirects.
-  It follows data through one level of same-file helper, not across files, and
-  does not replace PHPStan or Psalm. `phpwarden code --list-rules` lists every rule.
+- **`phpwarden code PATH`** (whole-program engine, default in 2.3.0): parses the
+  project, resolves namespaces, Composer autoloading, inheritance and types, and
+  follows request data across files to SQL, shell, `eval`, `unserialize`,
+  includes, redirects and HTTP clients, with a trace per finding (SARIF
+  `codeFlows`). Models Laravel, Symfony and WordPress: routes with no auth check,
+  mass assignment, raw Blade/Twig output, IDOR hints, CSRF exclusions, nonces.
+  Follows data stored in the session or WordPress options (second-order).
+  89 rules. On the same pinned apps it found more than Semgrep and Psalm with far
+  fewer findings on clean framework code ([comparison](https://github.com/oroma-alfred/phpwarden/tree/main/bench/sast-compare-2026-11)).
+  Data that round-trips through the database is not followed.
+- **`phpwarden shield`**: one PHP file loaded before your app that blocks exploit
+  attempts against the exploited vulnerabilities this site actually has, scoped
+  to their entry points. Logs until you promote rules (7-day burn-in, explicit
+  flag), fails open, has a kill switch, about 0.07 ms per request. Not an edge
+  WAF: no DDoS, bot or TLS handling.
 - **`phpwarden assess`**: one ranked list from every view of a site: installed
   versions, your code, the live site from outside, and the access log, with the
   reason for each item ("exploited, reachable, visible from outside, already
@@ -235,7 +248,7 @@ see [phpwarden/laravel](https://packagist.org/packages/phpwarden/laravel).
 ```yaml
 repos:
   - repo: https://github.com/oroma-alfred/phpwarden
-    rev: v2.1.0        # pin to a tag with `pre-commit autoupdate`
+    rev: v2.3.0        # pin to a tag with `pre-commit autoupdate`
     hooks:
       - id: phpwarden-deps
         # args: ["--no-reachability"]   # faster: skip the reachability pass

{phpwarden-2.2.0 → phpwarden-2.3.0}/README.md

@@ -37,7 +37,8 @@ $ phpwarden deps composer.lock
 | Composer dependency CVEs | `deps` | Snyk, `composer audit` |
 | WordPress core, plugin and theme CVEs | `wordpress` | Patchstack, Wordfence |
 | WordPress file integrity (wordpress.org checksums, injected files) | `integrity` | Wordfence CLI malware-scan (partly) |
-| Your own PHP code (75 rules) | `code` | — (not a PHPStan/Psalm replacement) |
+| Your own PHP code: whole-program, Laravel/Symfony/WordPress-aware (89 rules) | `code` | Snyk Code, Semgrep, Psalm taint |
+| Exploits of the vulnerabilities this site has, blocked inside PHP | `shield` | the WAF rule you would have to write |
 | Live site from outside: exposed files, debug endpoints | `probe` | — |
 | One ranked verdict across all of the above | `assess` | — |
 | Exploitation signatures in logs | `detect` | SIEM content |
@@ -98,7 +99,8 @@ phpwarden rules --format nginx --out php-block.conf   # PHP-specific WAF rules (
 phpwarden rules --format nginx --dry-run     # the same rules, log-only: nothing is blocked
 phpwarden rules --replay /var/log/nginx/access.log    # what the rules would have blocked in an existing log
 phpwarden probe https://example.com  # live check of a site you own: exposed files, debug endpoints, versions vs the feed
-phpwarden code .                     # your own PHP: 75 high-signal rules, 74 on by default (injection, unserialize, WordPress handlers)
+phpwarden code .                     # your own PHP, whole program: 89 rules (injection, auth, mass assignment, Blade/Twig, WordPress)
+phpwarden shield policy . && phpwarden shield install   # block exploits of what is installed here, inside PHP (log-only first)
 phpwarden assess . --url https://example.com --log access.log   # one ranked verdict; --out / --baseline shows what is fixed and verified
 phpwarden report web01.json web02.json --out fleet.html   # aggregate a fleet view
 phpwarden feed status                # which feed is active, how many advisories
@@ -111,7 +113,7 @@ phpwarden feed update                # pull a newer feed: free weekly snapshot,
 `probe`, `code`, `assess`, `--format sarif`, `rules --dry-run` / `--replay` and
 the no-key `feed update` are new in 2.2.0.
 
-Every command takes `--json`. Exit codes are shared across subcommands and
+Every scanning command takes `--json` (`shield install` and `shield promote` do not). Exit codes are shared across subcommands and
 built for gating: `0` clean, `1` exposed / vulnerable / signature hits / tampered
 files / high or critical `code` and `probe` findings (`probe` also on any
 known-exploited finding) / anything to act on now or this week (`assess`),
@@ -120,7 +122,7 @@ error, `5` `--report-to` upload failed on an otherwise clean run, `64` usage
 error. Full table: `phpwarden --help`.
 
 
-## New in 2.2.0
+## New in 2.3.0 and 2.2
 
 - **`phpwarden probe URL`**: a live check of a running site using GET and HEAD
   requests only. It looks for exposed files (`.env`, `.git`, backups), open debug
@@ -128,10 +130,21 @@ error. Full table: `phpwarden --help`.
   matches those against the feed. Active checks run only after you prove the
   site is yours (DNS TXT record, a file, or a meta tag; `--print-token` shows
   how). Without that it reads the homepage and stops.
-- **`phpwarden code PATH`**: 75 rules (74 on by default) for your own PHP code, following request
-  data to `eval`, shell commands, SQL, `unserialize`, includes and redirects.
-  It follows data through one level of same-file helper, not across files, and
-  does not replace PHPStan or Psalm. `phpwarden code --list-rules` lists every rule.
+- **`phpwarden code PATH`** (whole-program engine, default in 2.3.0): parses the
+  project, resolves namespaces, Composer autoloading, inheritance and types, and
+  follows request data across files to SQL, shell, `eval`, `unserialize`,
+  includes, redirects and HTTP clients, with a trace per finding (SARIF
+  `codeFlows`). Models Laravel, Symfony and WordPress: routes with no auth check,
+  mass assignment, raw Blade/Twig output, IDOR hints, CSRF exclusions, nonces.
+  Follows data stored in the session or WordPress options (second-order).
+  89 rules. On the same pinned apps it found more than Semgrep and Psalm with far
+  fewer findings on clean framework code ([comparison](https://github.com/oroma-alfred/phpwarden/tree/main/bench/sast-compare-2026-11)).
+  Data that round-trips through the database is not followed.
+- **`phpwarden shield`**: one PHP file loaded before your app that blocks exploit
+  attempts against the exploited vulnerabilities this site actually has, scoped
+  to their entry points. Logs until you promote rules (7-day burn-in, explicit
+  flag), fails open, has a kill switch, about 0.07 ms per request. Not an edge
+  WAF: no DDoS, bot or TLS handling.
 - **`phpwarden assess`**: one ranked list from every view of a site: installed
   versions, your code, the live site from outside, and the access log, with the
   reason for each item ("exploited, reachable, visible from outside, already
@@ -213,7 +226,7 @@ see [phpwarden/laravel](https://packagist.org/packages/phpwarden/laravel).
 ```yaml
 repos:
   - repo: https://github.com/oroma-alfred/phpwarden
-    rev: v2.1.0        # pin to a tag with `pre-commit autoupdate`
+    rev: v2.3.0        # pin to a tag with `pre-commit autoupdate`
     hooks:
       - id: phpwarden-deps
         # args: ["--no-reachability"]   # faster: skip the reachability pass

{phpwarden-2.2.0 → phpwarden-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phpwarden"
-version = "2.2.0"
+version = "2.3.0"
 description = "PHP vulnerability scanner for the PHP engine, Composer, WordPress, your own code and the live site. Ranked by real-world exploitation (CISA KEV, then EPSS), not CVSS. Offline, zero dependencies."
 readme = "README.md"
 requires-python = ">=3.8"
@@ -39,4 +39,4 @@ package-dir = { "" = "src" }
 where = ["src"]
 
 [tool.setuptools.package-data]
-phpwarden = ["data/*.json"]
+phpwarden = ["data/*.json", "shield/agent/*.php"]

{phpwarden-2.2.0 → phpwarden-2.3.0}/src/phpwarden/__init__.py

@@ -6,4 +6,4 @@ real-world exploitation (CISA KEV, then EPSS, then CVSS), and can watch PHP-FPM
 for active exploitation. The engine and the bundled feed are open; free users
 get weekly feed updates, and a subscription adds the feed rebuilt twice a day.
 """
-__version__ = "2.2.0"
+__version__ = "2.3.0"

{phpwarden-2.2.0 → phpwarden-2.3.0}/src/phpwarden/cli.py

@@ -13,6 +13,7 @@
   phpwarden probe URL            safe live HTTP check of a site you own
   phpwarden code PATH            scan your own PHP code for high-signal security bugs
   phpwarden assess PATH --url U --log L   one ranked verdict from every view
+  phpwarden shield policy PATH   protection inside PHP for the exploited vulns installed here
 
 Exit codes (shared by every subcommand; usable as a CI gate):
   0   nothing applies / clean
@@ -562,6 +563,85 @@ def _assess(args):
     return vd.exit_code(res)
 
 
+def _shield(args):
+    from pathlib import Path as _P
+    from phpwarden.shield import policy as sp, report as sr
+    if args.shield_cmd == "policy":
+        root = _P(args.path)
+        if not root.is_dir():
+            sys.stderr.write(f"error: not a directory: {args.path}\n")
+            return 4
+        pol = sp.build_policy_for_path(str(root), FeedManager().current(), php_version=args.php_version,
+                                       php_sapi=args.php_sapi, log_path=args.log)
+        out = args.out or "phpwarden-shield.policy.json"
+        j, php = sp.write_policy(pol, out)
+        if args.json:
+            print(json.dumps(pol, indent=2))
+            return 0
+        print(f"wrote {j} and {php}  ({len(pol['rules'])} rule(s), mode: log)")
+        for r in pol["rules"]:
+            print(f"  + {r['id']:<34} {r.get('cve') or '':<16} {r['component']}: {r['why']}")
+        if not pol["rules"]:
+            print("  No exploited vulnerability with a known request shape is installed here; the policy only has")
+            print("  the generic checks, if any applied. Nothing to protect against beyond those.")
+        print("\nNext: `phpwarden shield install` shows how to load the agent. It only logs until you promote rules.")
+        return 0
+    if args.shield_cmd == "install":
+        agent = _P(__file__).resolve().parent / "shield" / "agent" / "phpwarden-shield.php"
+        dest = _P(args.dest) if args.dest else None
+        if dest:
+            try:
+                dest.mkdir(parents=True, exist_ok=True)
+                (dest / "phpwarden-shield.php").write_bytes(agent.read_bytes())
+            except OSError as e:
+                sys.stderr.write(f"error: {e}\n")
+                return 4
+            where = (dest / "phpwarden-shield.php").resolve()
+            print(f"copied the agent to {where}")
+        else:
+            where = "/path/to/phpwarden-shield.php"
+            print(f"The agent ships with phpwarden at {agent}. Copy it next to your site, or rerun with --dest DIR.")
+        print(f"""
+Load it before your application (pick one; nothing is changed for you):
+  php.ini or .user.ini:   auto_prepend_file={where}
+  WordPress:              add  require '{where}';  as the first line of wp-config.php
+  Laravel / other apps:   add  require '{where}';  at the top of public/index.php
+
+Put phpwarden-shield.policy.php (from `phpwarden shield policy`) next to the agent, or set
+PHPWARDEN_SHIELD_POLICY to its path. It starts in log-only mode and fails open on any error.
+Turn it off instantly: create a file named phpwarden-shield.off next to the agent, or set
+PHPWARDEN_SHIELD=off.""")
+        return 0
+    if args.shield_cmd == "report":
+        try:
+            with open(args.log, errors="replace") as fh:
+                summ = sr.summarize(fh)
+        except OSError as e:
+            sys.stderr.write(f"error: {e}\n")
+            return 4
+        print(json.dumps(summ, indent=2, default=list) if args.json else sr.to_text(summ))
+        return 0
+    if args.shield_cmd == "promote":
+        try:
+            pol = json.loads(_P(args.policy).read_text())
+            with open(args.log, errors="replace") as fh:
+                summ = sr.summarize(fh)
+        except (OSError, ValueError) as e:
+            sys.stderr.write(f"error: {e}\n")
+            return 4
+        pol, rep = sp.promote(pol, summ, operator_ack=args.i_understand_this_blocks_requests,
+                              rule_ids=set(args.rule) if args.rule else None)
+        for rid in rep["promoted"]:
+            print(f"  BLOCK  {rid}")
+        for r in rep["refused"]:
+            print(f"  still logging  {r['id']}: {r['reason']}")
+        if rep["promoted"]:
+            sp.write_policy(pol, args.policy)
+            print(f"\nupdated {args.policy} (and its .php twin). Promoted rules now return 403.")
+        return 0
+    return EX_USAGE
+
+
 def _integrity(args):
     from phpwarden import integrity as integ
     res = integ.check(args.path, locale=args.locale, plugins=not args.no_plugins)
@@ -674,6 +754,29 @@ def main(argv=None):
     _report_args(wpc)
     wpc.set_defaults(func=_wordpress)
 
+    sh = sub.add_parser("shield", help="protection inside PHP: block exploits of the vulnerabilities this site "
+                                       "actually has (log-only until you promote rules)")
+    shs = sh.add_subparsers(dest="shield_cmd", required=True, parser_class=_Parser)
+    shp = shs.add_parser("policy", help="build a policy for the exploited vulnerabilities installed at PATH")
+    shp.add_argument("path", nargs="?", default=".", help="project or WordPress root (default: .)")
+    shp.add_argument("--out", help="policy file (default phpwarden-shield.policy.json; a .php twin is written too)")
+    shp.add_argument("--php-version", help="the production PHP version, for engine CVE rules")
+    shp.add_argument("--php-sapi", choices=["fpm", "cgi", "cli"], help="the production SAPI")
+    shp.add_argument("--log", help="where the agent should write its log (default: next to the agent)")
+    shp.add_argument("--json", action="store_true", help="print the policy as JSON")
+    shi = shs.add_parser("install", help="show how to load the agent (and copy it with --dest)")
+    shi.add_argument("--dest", metavar="DIR", help="copy phpwarden-shield.php into this folder")
+    shr = shs.add_parser("report", help="summarise the agent's log")
+    shr.add_argument("log", help="phpwarden-shield.log")
+    shr.add_argument("--json", action="store_true", help="machine-readable JSON output")
+    shm = shs.add_parser("promote", help="switch rules from logging to blocking after a clean burn-in")
+    shm.add_argument("policy", help="the policy JSON to update")
+    shm.add_argument("--log", required=True, help="the agent log covering the burn-in")
+    shm.add_argument("--rule", action="append", metavar="ID", help="only this rule (repeatable)")
+    shm.add_argument("--i-understand-this-blocks-requests", action="store_true",
+                     help="required: promoted rules return 403 to matching requests")
+    sh.set_defaults(func=_shield)
+
     asx = sub.add_parser("assess", help="one ranked verdict from every view: installed versions, your code, "
                                         "the live site from outside, and attacks in the access log")
     asx.add_argument("path", nargs="?", help="project or site root (composer.lock, WordPress, PHP code)")