phpwarden 2.2.1__tar.gz → 2.4.0__tar.gz

{phpwarden-2.2.1 → phpwarden-2.4.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: phpwarden
-Version: 2.2.1
-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.
+Version: 2.4.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; blocks exploits inside PHP (shield). Offline, zero dependencies.
 Author: oroma-alfred
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://phpwarden.io
 Project-URL: Source, https://github.com/oroma-alfred/phpwarden
 Project-URL: Issues, https://github.com/oroma-alfred/phpwarden/issues
-Keywords: php,composer,wordpress,php-fpm,security,vulnerability,cve,kev,epss,sca,scanner
+Keywords: php,composer,wordpress,php-fpm,security,vulnerability,cve,kev,epss,sca,sast,waf,scanner
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: System Administrators
@@ -28,8 +28,9 @@ exploited (CISA KEV, as of 2026-11-14). phpwarden puts those first, then sorts
 by EPSS probability, then CVSS — so a `composer.lock` with 30 findings tells
 you which one to fix today.
 
-It scans the PHP engine/FPM version, Composer dependencies and WordPress
-installs against one bundled, offline advisory feed. Zero runtime dependencies
+It scans the PHP engine/FPM version, Composer dependencies, WordPress installs
+and your own PHP code, checks live sites from outside, and can block exploits
+inside PHP, against one bundled, offline advisory feed. Zero runtime dependencies
 (Python 3.8+), Apache-2.0.
 
 **Reproducible benchmark:** on four real PHP stacks, phpwarden found 295 of 295
@@ -59,7 +60,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 +122,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 +136,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 +145,26 @@ 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.4.0, 2.3.0 and 2.2
+
+- **2.4.0: `phpwarden code` follows data through the database and callbacks.**
+  Request data saved with raw SQL, `$wpdb`, Eloquent, the query builder or
+  Doctrine and read back from the same table is traced to where it is printed
+  or queried (stored XSS, second-order SQL injection), and callbacks passed to
+  `array_map`, `usort`, `preg_replace_callback`, `add_filter` and the like,
+  `$f()` and first-class callables are followed. DVWA: 8/8/7 of 8 types under
+  the comparison's scorer (was 7/7/6); clean-code counts unchanged.
+- **2.4.0: shield rate limits.** Per-client limits on WordPress login, password
+  reset, xmlrpc and `system.multicall`, Laravel login and reset, component
+  writes, and a burst guard. Log-only until promoted, then 429; APCu or file
+  store; fails open. `--trust-proxy CIDR`, `--no-limits`, `--limit-path REGEX`.
+  0 trips on 6,000 ordinary requests; 6 of 6 abuse scenarios caught. Pairing
+  with Cloudflare or nginx: [EDGE.md](src/phpwarden/shield/EDGE.md).
+- **2.4.0: `phpwarden trivy-import` and `assess --trivy FILE` / `--run-trivy`.**
+  Trivy's JSON (npm/JS, OS packages, images, IaC, secrets) in the same ranked
+  list as PHP findings: KEV, then EPSS (`--kev`, `--epss`), then severity.
+  Secrets by file and line only. Never downloads Trivy. See
+  [src/phpwarden/thirdparty/README.md](src/phpwarden/thirdparty/README.md).
 
 - **`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,11 +172,20 @@ 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 across files (helper functions and classes elsewhere in the
-  project, fixed includes, class properties); it is not a type checker like
-  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)).
+- **`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
@@ -236,7 +267,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.4.0        # pin to a tag with `pre-commit autoupdate`
     hooks:
       - id: phpwarden-deps
         # args: ["--no-reachability"]   # faster: skip the reachability pass
@@ -247,14 +278,14 @@ timer recipes are in [`docs/recipes.md`](docs/recipes.md).
 
 ## The feed
 
-The bundled community feed (2026.11.13.3 in this release) works forever, offline:
+The bundled community feed (2026.11.14.2 in this release) works forever, offline:
 
 - **~21,300 advisories**: ~8,800 Composer (from [OSV.dev](https://osv.dev) and
   [FriendsOfPHP](https://github.com/FriendsOfPHP/security-advisories)),
   ~12,300 WordPress (from [NVD](https://nvd.nist.gov): plugin, core and theme),
-  and 145 PHP engine/FPM CVEs, including hand-curated entries with per-branch
-  fixed versions, exposure conditions and detection signatures. About 19,700 carry an
-  EPSS score; 41 distinct vulnerabilities were in KEV when this feed was built.
+  and 146 PHP engine/FPM CVEs, including hand-curated entries with per-branch
+  fixed versions, exposure conditions and detection signatures. About 19,800 carry an
+  EPSS score; 54 distinct vulnerabilities were in KEV when this feed was built.
 - **License-independent by construction.** Every source is open or
   public-domain (OSV, NVD, FriendsOfPHP, php-src release notes, CISA KEV, FIRST EPSS). No commercial
   vendor's feed is used, so coverage cannot be revoked or priced away.

{phpwarden-2.2.1 → phpwarden-2.4.0}/README.md

@@ -6,8 +6,9 @@ exploited (CISA KEV, as of 2026-11-14). phpwarden puts those first, then sorts
 by EPSS probability, then CVSS — so a `composer.lock` with 30 findings tells
 you which one to fix today.
 
-It scans the PHP engine/FPM version, Composer dependencies and WordPress
-installs against one bundled, offline advisory feed. Zero runtime dependencies
+It scans the PHP engine/FPM version, Composer dependencies, WordPress installs
+and your own PHP code, checks live sites from outside, and can block exploits
+inside PHP, against one bundled, offline advisory feed. Zero runtime dependencies
 (Python 3.8+), Apache-2.0.
 
 **Reproducible benchmark:** on four real PHP stacks, phpwarden found 295 of 295
@@ -37,7 +38,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 +100,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 +114,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 +123,26 @@ 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.4.0, 2.3.0 and 2.2
+
+- **2.4.0: `phpwarden code` follows data through the database and callbacks.**
+  Request data saved with raw SQL, `$wpdb`, Eloquent, the query builder or
+  Doctrine and read back from the same table is traced to where it is printed
+  or queried (stored XSS, second-order SQL injection), and callbacks passed to
+  `array_map`, `usort`, `preg_replace_callback`, `add_filter` and the like,
+  `$f()` and first-class callables are followed. DVWA: 8/8/7 of 8 types under
+  the comparison's scorer (was 7/7/6); clean-code counts unchanged.
+- **2.4.0: shield rate limits.** Per-client limits on WordPress login, password
+  reset, xmlrpc and `system.multicall`, Laravel login and reset, component
+  writes, and a burst guard. Log-only until promoted, then 429; APCu or file
+  store; fails open. `--trust-proxy CIDR`, `--no-limits`, `--limit-path REGEX`.
+  0 trips on 6,000 ordinary requests; 6 of 6 abuse scenarios caught. Pairing
+  with Cloudflare or nginx: [EDGE.md](src/phpwarden/shield/EDGE.md).
+- **2.4.0: `phpwarden trivy-import` and `assess --trivy FILE` / `--run-trivy`.**
+  Trivy's JSON (npm/JS, OS packages, images, IaC, secrets) in the same ranked
+  list as PHP findings: KEV, then EPSS (`--kev`, `--epss`), then severity.
+  Secrets by file and line only. Never downloads Trivy. See
+  [src/phpwarden/thirdparty/README.md](src/phpwarden/thirdparty/README.md).
 
 - **`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,11 +150,20 @@ 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 across files (helper functions and classes elsewhere in the
-  project, fixed includes, class properties); it is not a type checker like
-  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)).
+- **`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
@@ -214,7 +245,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.4.0        # pin to a tag with `pre-commit autoupdate`
     hooks:
       - id: phpwarden-deps
         # args: ["--no-reachability"]   # faster: skip the reachability pass
@@ -225,14 +256,14 @@ timer recipes are in [`docs/recipes.md`](docs/recipes.md).
 
 ## The feed
 
-The bundled community feed (2026.11.13.3 in this release) works forever, offline:
+The bundled community feed (2026.11.14.2 in this release) works forever, offline:
 
 - **~21,300 advisories**: ~8,800 Composer (from [OSV.dev](https://osv.dev) and
   [FriendsOfPHP](https://github.com/FriendsOfPHP/security-advisories)),
   ~12,300 WordPress (from [NVD](https://nvd.nist.gov): plugin, core and theme),
-  and 145 PHP engine/FPM CVEs, including hand-curated entries with per-branch
-  fixed versions, exposure conditions and detection signatures. About 19,700 carry an
-  EPSS score; 41 distinct vulnerabilities were in KEV when this feed was built.
+  and 146 PHP engine/FPM CVEs, including hand-curated entries with per-branch
+  fixed versions, exposure conditions and detection signatures. About 19,800 carry an
+  EPSS score; 54 distinct vulnerabilities were in KEV when this feed was built.
 - **License-independent by construction.** Every source is open or
   public-domain (OSV, NVD, FriendsOfPHP, php-src release notes, CISA KEV, FIRST EPSS). No commercial
   vendor's feed is used, so coverage cannot be revoked or priced away.

{phpwarden-2.2.1 → phpwarden-2.4.0}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phpwarden"
-version = "2.2.1"
-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."
+version = "2.4.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; blocks exploits inside PHP (shield). Offline, zero dependencies."
 readme = "README.md"
 requires-python = ">=3.8"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 authors = [{ name = "oroma-alfred" }]
-keywords = ["php", "composer", "wordpress", "php-fpm", "security", "vulnerability", "cve", "kev", "epss", "sca", "scanner"]
+keywords = ["php", "composer", "wordpress", "php-fpm", "security", "vulnerability", "cve", "kev", "epss", "sca", "sast", "waf", "scanner"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Environment :: Console",
@@ -39,4 +39,4 @@ package-dir = { "" = "src" }
 where = ["src"]
 
 [tool.setuptools.package-data]
-phpwarden = ["data/*.json"]
+phpwarden = ["data/*.json", "shield/agent/*.php", "shield/*.md"]

{phpwarden-2.2.1 → phpwarden-2.4.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.1"
+__version__ = "2.4.0"

{phpwarden-2.2.1 → phpwarden-2.4.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
@@ -545,8 +546,29 @@ def _assess(args):
         if any("homepage unreachable" in n for n in probe_result.get("notes", [])):
             sys.stderr.write(f"error: could not reach {url}\n")
             return 4
+    trivy_fs, trivy_note = None, None
+    if args.trivy or args.run_trivy:
+        from phpwarden.thirdparty import trivy as tv
+        try:
+            kev, epss = tv.load_kev(args.kev), tv.load_epss(args.epss)
+            docs = [tv.load_report(f) for f in (args.trivy or [])]
+        except (OSError, ValueError) as e:
+            sys.stderr.write(f"error: {e}\n")
+            return 4
+        if args.run_trivy and args.path:
+            doc, msg = tv.run_trivy_fs(args.path)
+            if doc is not None:
+                docs.append(doc)
+            else:
+                trivy_note = msg
+                sys.stderr.write(msg + "\n")
+        trivy_fs = [f for d in docs for f in tv.findings(d, kev, epss)]
+        if docs and not (args.kev or args.epss):
+            trivy_note = (trivy_note + "; " if trivy_note else "") + \
+                "non-PHP findings ranked by severity only (pass --kev and --epss for exploitation data)"
     try:
-        res = vd.assess(args.path, probe_result=probe_result, logfile=args.log, run_code=not args.no_code)
+        res = vd.assess(args.path, probe_result=probe_result, logfile=args.log, run_code=not args.no_code,
+                        trivy_findings=trivy_fs, trivy_note=trivy_note)
     except OSError as e:                      # unreadable access log
         sys.stderr.write(f"error: {e}\n")
         return 4
@@ -562,6 +584,112 @@ def _assess(args):
     return vd.exit_code(res)
 
 
+def _trivy_import(args):
+    from phpwarden.thirdparty import trivy as tv
+    try:
+        kev, epss = tv.load_kev(args.kev), tv.load_epss(args.epss)
+        fs = [f for p in args.files for f in tv.findings(tv.load_report(p), kev, epss)]
+    except (OSError, ValueError) as e:
+        sys.stderr.write(f"error: {e}\n")
+        return 4
+    doc = tv.to_report_doc(fs, args.files)
+    if args.json:
+        print(json.dumps(doc, indent=2))
+    else:
+        kev_n = sum(1 for f in fs if f["known_exploited"])
+        print(f"{len(fs)} finding(s) from {len(args.files)} Trivy report(s); {kev_n} known exploited. "
+              f"Ranked by exploitation{'' if (args.kev or args.epss) else ' (no --kev/--epss: by severity)'}:")
+        for f in fs[:50]:
+            tag = " [KEV]" if f["known_exploited"] else (f" [EPSS {f['epss'] * 100:.0f}%]" if f.get("epss") else "")
+            dev = " (dev)" if f["dev"] else ""
+            print(f"  {f['severity']:<8} {tv.ident(f)}{tag}{dev}  {f['title'][:90]}")
+        if len(fs) > 50:
+            print(f"  ... and {len(fs) - 50} more; use --json for all")
+    rc = 1 if any(f["known_exploited"] or f["severity"] in ("critical", "high") for f in fs) else 0
+    return _combine(rc, _maybe_report(args, doc))
+
+
+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,
+                                       limits=not args.no_limits, limit_paths=args.limit_path or [],
+                                       trust_proxy=args.trust_proxy or [])
+        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 +802,44 @@ def main(argv=None):
     _report_args(wpc)
     wpc.set_defaults(func=_wordpress)
 
+    tvi = sub.add_parser("trivy-import", help="read Trivy JSON reports (npm/JS, OS packages, images, IaC), "
+                                              "rank them by exploitation, optionally send them to the dashboard")
+    tvi.add_argument("files", nargs="+", metavar="TRIVY_JSON", help="output of trivy fs/image/config --format json")
+    tvi.add_argument("--kev", metavar="FILE", help="CISA KEV catalogue JSON")
+    tvi.add_argument("--epss", metavar="FILE", help="FIRST EPSS CSV (.csv or .csv.gz)")
+    tvi.add_argument("--json", action="store_true", help="machine-readable JSON output")
+    _report_args(tvi)
+    tvi.set_defaults(func=_trivy_import)
+
+    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("--no-limits", action="store_true",
+                     help="leave out the rate limits (login, password reset, xmlrpc, burst guard)")
+    shp.add_argument("--limit-path", action="append", metavar="REGEX",
+                     help="also rate-limit requests to this path (repeatable)")
+    shp.add_argument("--trust-proxy", action="append", metavar="CIDR",
+                     help="trust forwarded client IPs only from this proxy range, e.g. your CDN (repeatable)")
+    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)")
@@ -686,6 +852,12 @@ def main(argv=None):
     asx.add_argument("--baseline", metavar="FILE",
                      help="an earlier --out file: report what is fixed and verified, still open, and new")
     asx.add_argument("--json", action="store_true", help="machine-readable JSON output")
+    asx.add_argument("--trivy", metavar="FILE", action="append",
+                     help="add a Trivy JSON report (npm/JS, OS packages, images, IaC); repeatable")
+    asx.add_argument("--run-trivy", action="store_true",
+                     help="run `trivy fs` on the path if Trivy is installed (never downloads it)")
+    asx.add_argument("--kev", metavar="FILE", help="CISA KEV catalogue JSON, to rank non-PHP CVEs by exploitation")
+    asx.add_argument("--epss", metavar="FILE", help="FIRST EPSS CSV (.csv or .csv.gz) for non-PHP CVEs")
     asx.set_defaults(func=_assess)
 
     cd = sub.add_parser("code", help="scan your own PHP code for high-signal security bugs "