Introducing php2shell-test: A Closed-Loop Purple-Team Harness for PHP RCE & Detection Validation

Meet php2shell-test, our open-source GPL-2.0 purple-team verification harness, on-host artifact hunter, and validated Sigma/ModSecurity/auditd rule suite built to prove whether attacker-supplied PHP can reach your interpreter—and whether your detection stack actually notices.

php2shell-test Closed-Loop Purple-Team Harness for PHP RCE and Detection Validation
🧪
Open-Source Tool Release: php2shell-test Following our deep dive into PHP2Shell (CVE-2026-109618 & CVE-2026-109619), we are releasing php2shell-test: a GPL-2.0 closed-loop verification harness, on-host artifact hunter, and validated Sigma/ModSecurity/auditd rule suite built to prove whether attacker-supplied PHP can reach your interpreter—and whether your SIEM and WAF actually notice.

When a critical PHP vulnerability drops—whether it is core engine memory corruption like PHP2Shell (CVE-2026-109618 & CVE-2026-109619), a session.upload_progress file inclusion chain, an unauthenticated file upload bypass, or an unsafe unserialize() sink—security teams immediately ask two questions:

1. "Can attacker-supplied PHP source reach the interpreter on our host—yes or no?"
2. "If it can (or nearly can), would our detection stack actually have seen it?"

Most offensive scanners are terrible at answering both. Point a generic vulnerability scanner at a staging server and it will either spray blind payloads and declare victory on a soft 200 OK error page, or report "No vulnerabilities found" when an unexecuted .php payload actually landed squarely inside your webroot—sitting one .htaccess tweak or Apache AddType directive away from full Remote Code Execution (RCE).

Worse yet, almost no scanner closes the loop with your blue team. You get a PDF report from the scanner, while your ModSecurity WAF, Sigma rules, and auditd pipelines sit completely untested against the exact Indicators of Compromise (IOCs) generated during the test.

That is why we built and open-sourced php2shell-test.


1. Philosophy: A Closed-Loop Harness, Not a Weapon

php2shell-test is a closed-loop purple-team harness for systems you own or hold explicit written authorization to test. It is engineered from the ground up so that it cannot be turned into an offensive weapon:

  • It never executes system commands (system(), exec(), passthru()) on the target.
  • It never opens a shell, never establishes reverse network connections, and never exfiltrates application data.
  • It is strictly read-only by default: every test capable of writing to the target disk (or causing the target to write to its own disk) is gated behind --allow-write and reports SKIPPED unless explicitly unlocked under change approval.

Instead of dropping web shells, the harness ties four components together around a single per-run UUIDv4 canary token:

        ┌────────────────────────┐
        │  runner/php_rce_test.py│   1. Attempt 14-vector matrix & prove/disprove execution
        └───────────┬────────────┘
                    │ emits per-run UUIDv4 canary token + exact IOC manifest
                    ▼
        ┌────────────────────────┐
        │  detection/hunt.sh     │   2. Hunt on-disk & in logs on the target host
        └───────────┬────────────┘
                    │ confirms or refutes the HTTP-layer verdict
                    ▼
        ┌────────────────────────┐
        │  detection/*           │   3. Sigma / ModSecurity / auditd / SIEM rules
        └───────────┬────────────┘      validated against this run's exact IOCs
                    │
                    ▼
        ┌────────────────────────┐
        │  detection/mitigations │   4. Apply php.ini + code fixes, then re-run
        │  _reference.md         │      until 0 EXPLOITABLE / 0 INCONCLUSIVE
        └────────────────────────┘

2. The Canary Verdict Model: Why INCONCLUSIVE Matters

Every probe in runner/php_rce_test.py (a single-file Python 3 script using only the standard library) embeds a per-run UUIDv4 token inside a harmless, read-only PHP canary snippet:

<?php
echo "CANARY:<token>\n";
echo "UID:" . getmyuid() . "\n";
echo "PHP:" . PHP_VERSION . "\n";
/* Plus SAPI, php_uname(), cwd, disable_functions, open_basedir, docroot */
?>

When the harness probes a vector over HTTP, the verdict is mechanical and unambiguous:

HTTP Observation What Happened Verdict & Exit Code
CANARY:<token> present in response Attacker-supplied PHP source reached the interpreter and executed. EXPLOITABLE (Exit 2)
<token> present as raw <?php source The file landed on disk and is web-readable, but was not parsed as PHP. INCONCLUSIVE (Exit 1)
Nothing found at probed URLs Nothing executed or rendered at the HTTP layer probed. NOT_EXPLOITABLE (Exit 0)

The distinction between EXPLOITABLE and INCONCLUSIVE is the centerpiece of the design. When an uploaded file lands inside your webroot as raw text, calling that "safe" is a catastrophic mistake—it means your upload filter failed to block the write, and only the web server's current MIME handler stopped execution. Furthermore, because an HTTP 404 Not Found does not prove a file wasn't written to /tmp or a non-public directory, every run hands you a canary token for on-host verification via hunt.sh.


3. Inside the 14-Vector Test Matrix

Running python3 runner/php_rce_test.py --list displays the full matrix of controls and attack vectors:

  1. Baseline Controls (baseline.reachable, baseline.notfound, baseline.txt_parsed):Before running a single exploit probe, the harness tests whether a nonexistent /zz-<token>-nonexistent.php path returns HTTP 200. If your server returns soft-200s for missing files, the harness flags baseline.notfound as INCONCLUSIVE and warns you that upload results cannot be trusted until 404 handling is fixed.
  2. File Upload Bypass Matrix (upload.extensions, upload.traversal, upload.htaccess):When --allow-write is enabled, the runner probes 13 extension variations (.php, .phtml, .php5, .php7, .phar, .phps, case permutations like .PhP, trailing dots like .php., and double extensions like .php.jpg and .jpg.php), relative filename traversal (../c<token>.php), and Apache .htaccess handler injection via AddType application/x-httpd-php .t<token>.
  3. LFI & Stream Wrapper Sinks (lfi.php_input, lfi.php_data, lfi.filter_read, lfi.traversal, lfi.log_poison):Tests whether include/require sinks accept php://input, data://text/plain;base64,..., php://filter/read=convert.base64-encode/resource=... (which proves credential and source disclosure), path traversal, or poisoned User-Agent strings written into Apache/Nginx access logs.
  4. Session Upload Progress & Deserialization (session.upload_progress, deser.gadget, deser.sink_probe):Probes multipart PHP_SESSION_UPLOAD_PROGRESS injection into /tmp/sess_<token> (which works even when file_uploads=Off) and tests PHP object injection (unserialize()) using customizable POP gadget chains (--gadget-class, --gadget-path-prop, --gadget-write-path).

4. Closing the Loop: On-Host Hunting & Validated Detection

Step A: On-Host Truth with detection/hunt.sh

Once the HTTP runner finishes, you take the printed canary token onto the target host (or container) and run hunt.sh:

./detection/hunt.sh <canary-token> /var/www/html /srv/app /tmp

hunt.sh inspects 7 distinct host layers:

  • Canary source on disk: grep -Rnl "php-rce-test canary $TOKEN" across all webroots, /tmp, and /var/tmp.
  • Files named for the run: Prints timestamps, octal permissions, user ownership, and paths.
  • Orphaned session files: Checks /tmp and /var/lib/php/sessions for sess_$TOKEN* artifacts left by PHP_SESSION_UPLOAD_PROGRESS.
  • Recent .htaccess tampering: Finds any .htaccess modified within the last 4 hours.
  • Access log & log-poisoning verification: Confirms both that the runner's requests reached your log pipeline and whether raw <?php tags were written into access logs via User-Agent poisoning.
  • Kernel auditd telemetry: Runs ausearch -k php_upload_write and ausearch -k php_htaccess_write.
  • Review-first cleanup: Prints ready-to-paste, properly quoted rm and find -delete commands—commented out so you never destroy forensic evidence before reviewing it.

Step B: Validated Sigma, ModSecurity, and auditd Rules

Every detection rule in detection/ is continuously tested against the harness's exact output:

  • 7 Sigma Rules (detection/sigma_php_rce.yml): Six web_server rules and one auditd rule, each using deterministic UUIDv5 identifiers derived from the rule title so IDs never drift across regenerations.
  • 14 ModSecurity / Coraza Rules (detection/modsecurity_php.conf):
    • 12 Phase 1/2 Request-Blocking Rules (950010–950020, 950023): Block stream wrappers, base64 filter reads, PHP tags in User-Agent, dangerous upload extensions (including trailing-dot .php. via rule 950023), .htaccess uploads, PHP_SESSION_UPLOAD_PROGRESS multipart bodies, and serialized PHP object payloads.
    • 2 Load-Bearing Phase 5 Response Rules (950021 & 950022): Inspect outbound response bodies for CANARY:<32 hex> (proving PHP execution occurred) and unparsed canary source. Without Phase 5 response rules, a WAF alert cannot tell you whether an attack was blocked at the gate or succeeded on the backend!
  • WAF-Less Rule Replay (detection/replay_rules.py): Don't have ModSecurity loaded on a local dev environment? Run python3 detection/replay_rules.py --base http://127.0.0.1:8080 --allow-write to replay all 14 ModSecurity regexes directly against the live HTTP request/response transcript (verifying 14/14 matches on the vulnerable lab).

5. Battle-Tested Engineering: What Building the Lab Taught Us

php2shell-test ships with a self-contained Docker lab (docker compose up --build -d, bound strictly to 127.0.0.1:8080) containing both an intentionally vulnerable PHP application (/vuln/) and a hardened counterpart (/hardened/) sharing the exact same php.ini. Running the vulnerable half with --allow-write yields 10 EXPLOITABLE, 0 ERROR (exit 2); running the hardened half yields 0 EXPLOITABLE, 0 INCONCLUSIVE (exit 0).

🛠️
Why We Test the Tester: 45 Unit Tests & Real-World Edge Cases Building a trustworthy security harness means hunting down false negatives in the tool itself. Running python3 tests/test_runner.py executes 45 zero-dependency tests against an in-memory fakelab to guarantee that subtle protocol bugs never silently invalidate a report.

Here are five of the most fascinating real-world bugs we uncovered and permanently guarded against while building php2shell-test:

  1. The UTF-8 Em-Dash Deserialization Trap: PHP's unserialize() format (s:<n>:"...") counts UTF-8 bytes, not Unicode characters. Because our canary comment contained an em-dash (—, which is 1 character in Python's len() but 3 bytes in UTF-8), Python's len(canary) was 2 bytes short! PHP threw unserialize(): Error at offset 1014 of 1019 bytes while still returning HTTP 200, causing deser.gadget to falsely report INCONCLUSIVE on a vulnerable endpoint. The harness now uses a strict byte-length php_strlen() helper guarded by fakelab.serialized_lengths_ok().
  2. Apache's Final-Segment AddType Rule: An early version of upload.htaccess uploaded AddType application/x-httpd-php .<token>.txt. On a real Apache server, multi-dot markers in AddType fail because Apache matches the final extension segment. Switching to a single-segment .t<token> made the test reliably prove AllowOverride exposure.
  3. The 0-Byte session.upload_progress.cleanup=1 Race: By default, PHP sets session.upload_progress.cleanup = 1, which wipes the session progress array the instant a fast upload completes—leaving a 0-byte /tmp/sess_<token> file. The harness now explicitly distinguishes an empty session file (INCONCLUSIVE) from a missing or refused include path (NOT_EXPLOITABLE).
  4. ModSecurity's t:lowercase Mixed-Case Trap: ModSecurity rules that specify transformation t:lowercase convert the input buffer to lowercase before matching. If the rule's regex pattern still contains uppercase characters (like AddType or PHP_SESSION_UPLOAD_PROGRESS), it becomes mathematically impossible for the rule to ever match! TestDetectionAssets now parses modsecurity_php.conf and fails the build if any t:lowercase rule contains an uppercase character.
  5. Docker's /dev/stdout Access Log Symlink Hang: Official php:*-apache Docker images symlink /var/log/apache2/access.log to /dev/stdout. Running grep -R /var/log/apache2 inside a container tries to read an infinite pipe that never closes, hanging forever—and preventing log poisoning from landing on disk. Our lab configures a real file-backed access.log alongside stdout, and hunt.sh filters log searches with find -type f.

6. Quickstart: Try It in 60 Seconds

You can exercise the entire closed loop—exploit matrix, artifact hunting, WAF rule replay, and hardened verification—locally in Docker without touching any external network:

# 1. Clone the repository & run the 45-test self-check suite
git clone https://git.colibrisec.org/ColibriSec/php2shell-test.git
cd php2shell-test
python3 tests/test_runner.py

# 2. Start the local vulnerable + hardened lab (bound strictly to 127.0.0.1:8080)
docker compose up --build -d

# 3. Run the full matrix against the vulnerable endpoints (exits 2 with 10 EXPLOITABLE)
python3 runner/php_rce_test.py --base http://127.0.0.1:8080 --allow-write

# 4. Hunt for on-disk artifacts inside the container using the printed canary token
docker compose cp detection/hunt.sh php-lab:/tmp/hunt.sh
docker compose exec php-lab bash /tmp/hunt.sh <token> /var/www/html

# 5. Replay all 14 ModSecurity rules against the live HTTP traffic (14/14 matches)
python3 detection/replay_rules.py --base http://127.0.0.1:8080 --allow-write

# 6. Verify the hardened endpoints return 0 EXPLOITABLE, 0 INCONCLUSIVE (exits 0)
python3 runner/php_rce_test.py --base http://127.0.0.1:8080 --allow-write \
  --upload-path /hardened/upload.php \
  --include-path /hardened/include.php \
  --deser-path /hardened/deser.php

# 7. Tear down the lab
docker compose down
📦
Open Source & Available Now php2shell-test is licensed under GPL-2.0-only and maintained by the ColibriSec team.
Repository & Documentation: git.colibrisec.org/ColibriSec/php2shell-test
Previous Post: Dissecting PHP2Shell (CVE-2026-109618 & CVE-2026-109619): Pre-Auth RCE in PHP Core, Mitigation & Patching

Read more