- Python 89.6%
- PHP 4.5%
- Shell 3.6%
- Dockerfile 2.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| detection | ||
| docs | ||
| lab | ||
| runner | ||
| tests | ||
| .gitignore | ||
| docker-compose.yml | ||
| LICENSE | ||
| README.md | ||
| SECURITY.md | ||
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_EXPLOITABLEstill means "not at the HTTP layer I probed". Pair it with a code-level grep.INCONCLUSIVEstill needs a server-side check.hunt.shand 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.shcheck 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.inithat 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.