No description
  • Python 89.6%
  • PHP 4.5%
  • Shell 3.6%
  • Dockerfile 2.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-23 09:28:21 -05:00
detection publish pass: GPL-2.0 license, SECURITY.md, and the scratch state is gone 2026-10-22 23:00:07 -05:00
docs tests: a deleted file is not a deleted name — walk every blob reachable from every ref 2026-10-23 06:46:32 -05:00
lab publish pass: GPL-2.0 license, SECURITY.md, and the scratch state is gone 2026-10-22 23:00:07 -05:00
runner publish pass: GPL-2.0 license, SECURITY.md, and the scratch state is gone 2026-10-22 23:00:07 -05:00
tests tests: a deleted file is not a deleted name — walk every blob reachable from every ref 2026-10-23 06:46:32 -05:00
.gitignore baseline snapshot before known-issue fixes (STATUS.md tasks A1-A5, B1-B17) 2026-10-21 12:51:05 -05:00
docker-compose.yml publish pass: GPL-2.0 license, SECURITY.md, and the scratch state is gone 2026-10-22 23:00:07 -05:00
LICENSE publish pass: GPL-2.0 license, SECURITY.md, and the scratch state is gone 2026-10-22 23:00:07 -05:00
README.md tests: a deleted file is not a deleted name — walk every blob reachable from every ref 2026-10-23 06:46:32 -05:00
SECURITY.md SECURITY.md and the branch rename agree: fixes land on main, not master 2026-10-23 09:28:21 -05:00

php-rce-test

A harness for PHP code-execution (RCE): one script that attempts a matrix of PHP code-injection vectors against a target you own, one script that hunts for what those attempts actually left on disk and in logs, and a set of detection rules that are validated against the exact IOCs the harness produces.

The point is not "find a shell". The point is to answer, per vector:

Can attacker-supplied PHP source reach the interpreter on this host — yes or no — and if it can, would my detection stack have seen it?


Read this first: scope and authorization

This tool sends real attack traffic and, with --allow-write, writes real files on the target. It is for:

  • your own staging / dev environments,
  • production systems you own, under a written change/approval record,
  • authorized penetration tests with an explicit scope document and a rules-of-engagement window.

It is not for hosts you do not own or are not explicitly authorized to test. An earlier version of this repo carried a run report against someone else's SaaS host. That was a mistake and the artifacts are gone from every file in this tree and from the repo's rewritten history — TestLicenceAndRepoHygiene walks every blob reachable from every ref and fails the build if that host's name comes back: a run against a host nobody owns is not evidence, it is a liability. Get the authorization in writing before testing a third-party host. Pre-flight checklist: docs/runbook.md.

The harness deliberately cannot be turned into an attack tool: it never executes commands on the target, never opens a shell, never makes the target talk to the network, and never reads or moves data. See docs/harness.md.

Every number in this README is measured, from a run against the lab in this repo. The remediation table is the record of what was wrong with the tool itself and which test now guards it.


How the pieces fit

        ┌────────────────────────┐
        │  runner/php_rce_test.py│   attempt vectors, prove/disprove execution
        └───────────┬────────────┘
                    │ prints a per-run canary token + IOC list
                    ▼
        ┌────────────────────────┐
        │  detection/hunt.sh     │   find what actually landed on disk + in logs
        └───────────┬────────────┘
                    │ confirms or refutes the HTTP-layer verdict
                    ▼
        ┌────────────────────────┐
        │  detection/*           │   Sigma / ModSecurity / auditd / SIEM rules
        └───────────┬────────────┘   validated against this run's IOCs
                    │
                    ▼
        ┌────────────────────────┐
        │  detection/mitigations │   the php.ini + code fixes that make it
        │  _reference.md         │   NOT_EXPLOITABLE, then re-run
        └────────────────────────┘

lab/ is a deliberately vulnerable PHP app so the whole loop can be exercised locally without touching anything real.


Quickstart (local lab only)

# 1. build + start the intentionally-vulnerable lab
docker compose up --build -d
# lab is bound to 127.0.0.1:8080 only — not reachable from the network
# if 8080 is already taken on your machine, change the mapping in docker-compose.yml
# (e.g. "127.0.0.1:8088:80") and use that port in every command below

# 2. read-only pass (write-capable tests are SKIPPED)
python3 runner/php_rce_test.py --base http://127.0.0.1:8080

# 3. full pass, including tests that write files on the target
python3 runner/php_rce_test.py --base http://127.0.0.1:8080 --allow-write

# 4. hunt for what the run left behind — use the token the runner printed.
#    hunt.sh is written for a target host; copy it into the lab container to run it there:
docker compose cp detection/hunt.sh php-lab:/tmp/hunt.sh
docker compose exec php-lab bash /tmp/hunt.sh <token> /var/www/html
./detection/hunt.sh <token> /var/www/html /tmp      # on a real target

# 5. validate detection. Without a WAF loaded, replay the ModSecurity regexes against the
#    requests this run actually sent:
python3 detection/replay_rules.py --base http://127.0.0.1:8080 --allow-write
#    then feed the run's IOCs to your real SIEM/WAF and confirm alerts (docs/detection.md)

# 6. tear down
docker compose down

Measured against this lab, --allow-write: 10 EXPLOITABLE, 0 ERROR, exit 2 — every vector the harness probes is observable here, including lfi.log_poison, session.upload_progress and deser.gadget. The hardened half: 0 EXPLOITABLE, exit 0. replay_rules.py: 14/14 rules match that transcript, 5/14 without --allow-write. See docs/lab.md.

Against a real target you own, the same three commands apply, plus the pre-flight checklist in docs/runbook.md.


File map

Path What it is
runner/php_rce_test.py The test harness. 12 tests, canary-based verdicts, JSON + Markdown reports.
tests/ Regression tests for the harness itself: tests/test_runner.py + tests/fakelab.py, an in-memory stand-in for the lab. No network, no Docker, no pytest.
detection/hunt.sh Post-run artifact hunt and cleanup checklist, run on the target host.
detection/sigma_php_rce.yml 7 Sigma rules (web logs + auditd) for the same IOCs. Deterministic UUIDv5 ids.
detection/modsecurity_php.conf 14 ModSecurity rules: 12 blocking (phase 1/2), 2 response-side (phase 5).
detection/auditd_php.rules auditd watches on upload dirs, webroot, session dir, /tmp, .htaccess.
detection/siem_queries.md Splunk-style queries for the same signals.
detection/mitigations_reference.md The php.ini hardening block that makes tests go negative.
lab/ Intentionally vulnerable PHP app + a hardened counterpart, in Docker.
docs/ This documentation: harness, hunt, detection, lab, runbook.
LICENSE GPL-2.0. See License.
SECURITY.md How to report a bug in this tool, and what this tool considers a security bug.
report.md / report.json Output of a run. Generated artifacts, gitignored, never committed.

Check the tool before trusting it

python3 runner/php_rce_test.py --list      # the test matrix, no traffic sent
python3 tests/test_runner.py               # 45 tests, no network, no Docker

tests/ is what keeps the bugs in the remediation table below from coming back: it asserts the Result field order, that no upload POST happens without --allow-write, that verdicts point at the URL that actually executed, that reports list the files a run really wrote, that every extension the harness probes is matched by at least one detection rule, that serialized payloads carry byte lengths, that a t:lowercase ModSecurity rule does not carry a mixed-case pattern, and — since this repo is published — that LICENSE is the verbatim GPL-2.0 text, that every source file carries the matching SPDX header, that SECURITY.md exists and links to a reachable contact, and that no host outside this repo's own lab is named anywhere in the tree or in any commit in git history (TestLicenceAndRepoHygiene).


How the harness decides anything (the canary model)

Every test is built on one idea: make the target print a value that could only exist if PHP source you supplied was actually executed.

Each run generates a unique token (uuid4). That token is embedded in a small read-only PHP program (the canary) which prints CANARY:<token> plus host facts (uid, PHP version, SAPI, uname, cwd, disable_functions, open_basedir, docroot).

Then the verdict is mechanical:

What comes back over HTTP Meaning Verdict contribution
CANARY:<token> present your source ran in the interpreter EXPLOITABLE
<token> present, but as raw <?php source file landed, was not parsed INCONCLUSIVE (a real finding)
nothing found nothing landed at the URLs probed NOT_EXPLOITABLE — HTTP layer only

The distinction between the first two rows is the whole design. A file sitting in the webroot unexecuted is one AddType, one .htaccess, or one dependency upgrade away from being RCE.

Because a 404 does not prove nothing was written, the harness hands you a token and hunt.sh verifies on-disk truth. See docs/hunt.md.


Status vocabulary (read this before trusting a report)

Status Meaning Action
EXPLOITABLE attacker-supplied PHP executed. Incident. Preserve artifacts, stop re-running, open a ticket. Harness exits 2.
INCONCLUSIVE primitive landed but did not execute, or the test cannot tell mitigation from permissions. Resolve with hunt.sh / a server-side check. Never close as "not vulnerable".
NOT_EXPLOITABLE negative at the HTTP layer only. Pair with a code-level grep (unserialize(, include, eval, assert, phar://, …).
SKIPPED write-capable test, --allow-write not given — including the baseline.txt_parsed control, which uploads. Re-run under change approval.
ERROR the test itself failed. Not a security verdict. Fix the test.
OK control/baseline test behaved as expected. Nothing.

The three baseline.* controls exist so that NOT_EXPLOITABLE is not confusable with "the test silently broke". If baseline.notfound returns 200, every upload result in the report is untrustworthy.


Exit codes

Code Meaning
0 nothing exploitable, nothing inconclusive
1 one or more INCONCLUSIVE / ERROR results — needs follow-up
2 at least one EXPLOITABLE — code execution confirmed

Safe to wire straight into CI as a guardrail.


Known issues: what was wrong, and what fixed them

This table is the record. The task-by-task detail — which file, which evidence, which command proved it — is in git log --oneline from c1c2db2 forward; there is no separate status file, and commits are the only place that record is kept.

Every report generated before these fixes has to be read differently from a current one: all lfi.*, session.* and deser.* results in it are meaningless, because those test functions were crashing and the runner recorded ERROR for each one.

# What was wrong What it looks like now Guard
1 8 of 12 tests crashed — Result(id, name, vector, writes, "") put False in status and omitted evidence, producing the ERROR=8 block in the old report every result is built at PENDING and assigned a status afterwards; Result.__post_init__ rejects the old shape TestResultContract
2 baseline.txt_parsed uploaded without --allow-write, so "read-only by default" was false it is gated like every other write and reports SKIPPED test_baseline_txt_control_is_write_gated
3 Sigma rule ids were not valid UUIDs (…-phpwrapper01) deterministic UUIDv5 from each rule title, derivation documented in the file TestDetectionAssets
4 hunt.sh collapsed multiple webroots into one array element and used them unquoted webroots are an array, quoted everywhere, spaces safe bash -n + a spaced-path run
5 report.md / report.json were stale artifacts of a third-party run deleted, and gitignored git check-ignore

A second pass over every file found 18 more issues of the same kind — a lab .htaccess of 0 bytes, a hardened include pointing at pages that did not exist, a ModSecurity rule that could not match an extension the harness probes, a report that hardcoded its own IOCs. Each one is guarded by a named test in tests/test_runner.py.

Then the lab was actually run end to end, and it found six more — none of which the repo's own tests could see, because the test lab was more permissive than Apache and PHP:

# What was wrong What it is now Guard
6 Serialized payloads used Python character counts; the canary contains an em-dash, so the lab answered unserialize(): Error at offset 1014 of 1019 bytes and deser.gadget reported INCONCLUSIVE for a gadget the lab supports php_strlen() for every s:<n>:"…" length fakelab.serialized_lengths_ok()
7 upload.htaccess used the marker .<token>.txt; Apache's AddType matches the final extension segment, so it could never fire on a real server single-segment .t<token> final-segment matching in the test lab
8 session.upload_progress left a 0-byte sess_<token> (PHP's default cleanup=1), and the report did not say which failure it was cleanup=0 in the lab; empty file → INCONCLUSIVE, absent or refused → NOT_EXPLOITABLE three tests in TestC4LabFindings
9 The base image symlinks access.log to /dev/stdout, so log poisoning could not work and grep -R /var/log/apache2 never returned a real access.log plus a vhost-level CustomLog /dev/stdout; hunt.sh selects -type f build-time grep in lab/Dockerfile
10 ModSecurity 950017/950018 carried t:lowercase with mixed-case patterns, which cannot match anything, on any host patterns lowercased TestDetectionAssets rejects uppercase in a t:lowercase pattern
11 hunt.sh searched the access log for CANARY:<token>, which a combined log never contains searches for the run token, and separately for <?php docs/hunt.md states what to enable for the response-body signal

Two things are deliberately not "fixed", because they are not bugs:

  • NOT_EXPLOITABLE still means "not at the HTTP layer I probed". Pair it with a code-level grep.
  • INCONCLUSIVE still needs a server-side check. hunt.sh and auditd are how you do it.

And the pass that made this repo publishable:

# What was wrong What it is now Guard
12 the tool had no license, so "you may reuse this" was undefined and every downstream user was guessing LICENSE is the verbatim GPL-2.0 text; all 23 source files carry SPDX-License-Identifier: GPL-2.0-only TestLicenceAndRepoHygiene
13 there was no way to report a bug in a tool that writes files on other people's systems SECURITY.md: a contact, what counts as a bug in this repo, and where a misuse report goes same
14 STATUS.md was 466 lines of session state — scratch work shipped as documentation, full of absolute /home/james/... paths deleted; the record it held is the table above plus git log same (a shipped STATUS.md fails the test)
15 the file map advertised .gitea/workflows/ci.yml, which does not exist in this repo the claim is gone until the workflow exists the file map is checked by eye before every release
16 the deleted host's name was still readable from the pushed history, and the baseline commit was authored by a placeholder identity history rewritten with git filter-repo (--replace-text for the host name, --mailmap for the identity) before force-pushing TestLicenceAndRepoHygiene walks every blob in every commit

The name of the third-party host from the deleted run appears in no file in this tree and in no commit reachable from any ref: history was rewritten with git filter-repo and force-pushed. The denylist test is what keeps it out — including the case a deletion commit cannot catch, a name that is added and then removed but still readable from the commit that added it. It is also why the denylist in tests/test_runner.py is assembled from fragments: a guard that spells the name out loud re-introduces it to the tree it is protecting.


Deeper docs

  • docs/harness.md — every test, what it proves, what it can't prove, all CLI flags
  • docs/hunt.md — hunt.sh check by check, and the cleanup decision tree
  • docs/detection.md — Sigma / ModSecurity / auditd / SIEM, and the validation loop
  • docs/lab.md — the vulnerable and hardened lab endpoints, and the php.ini that makes them differ
  • docs/runbook.md — the end-to-end procedure against a real system you own

License

GPL-2.0-only — see LICENSE. Every source file in this repo carries the matching SPDX-License-Identifier: GPL-2.0-only header. You may use, modify, and redistribute this under the GPL, including commercially, on the GPL's terms (source for derivative works, same license downstream, notices preserved).

What the license does not do is grant you permission to point this at a host you are not authorized to test: that permission comes only from the target's owner, in writing.

Reported problems — including misuse against a host you own: SECURITY.md.