Initial public research release

Author: devploit

.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Unit tests
+        run: PYTHONDONTWRITEBYTECODE=1 python -m unittest discover -s tests -v
+
+  secrets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+.DS_Store
+vendor/
+lab/wordpress/wp/
+lab/rce/out/

ACCEPTABLE_USE.md

@@ -0,0 +1,44 @@
+# Acceptable use
+
+PHP2Shell is a research toolkit for **authorized** security testing. This page
+is part of the project's terms of use, together with [LICENSE](LICENSE) and
+[SECURITY.md](SECURITY.md).
+
+## You may use it only when
+
+- you own the target system, or
+- you have explicit, written permission from the owner to test it, and
+- your testing complies with the law and with the rules of any program you
+  participate in.
+
+A public website, an IP address you found online, or a domain that "looks like a
+lab" is **not** authorization.
+
+## You must not
+
+- test third-party or public infrastructure;
+- build or distribute target lists, scanners or mass-exploitation tooling;
+- use the remote worker-saturation mode against systems you do not own: it opens
+  many connections and is disruptive;
+- cause denial of service, data loss or persistence on systems without written
+  authorization;
+- publish data obtained from systems you do not own (hostnames, cookies,
+  credentials, file contents).
+
+## Disruptive behavior
+
+The chain sends large request bodies, triggers out-of-memory conditions and
+kills Apache children. Run it against disposable laboratories. The reference
+labs bind to `127.0.0.1` and mount an `/out` directory; keep it that way.
+
+## Disclosure
+
+If you find a new affected build or a new PHP issue, prefer coordinated
+disclosure with the PHP security team and the distribution vendor. Do not
+publish an unpatched exploit or third-party data.
+
+## No warranty
+
+The software is provided "as is", without warranty of any kind. The authors
+accept no liability for misuse or damage. The license grants copyright
+permissions only; it does not grant authorization to test any system.

CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Thanks for helping make PHP2Shell reproducible. Contributions are reviewed for
+correctness, safety and evidence.
+
+## Scope
+
+Welcome:
+
+- new build profiles with a real command proof and the exact image/tag;
+- offset extraction for new distributions and architectures;
+- laboratory fixes and calibration improvements;
+- tests, documentation, detection guidance and defensive tooling;
+- fixes for the open configurations (`display_errors=Off`, `expose_php=Off`,
+  FPM).
+
+Not welcome:
+
+- target lists, mass-exploitation tooling or automation against third parties;
+- data from systems you do not own (hostnames, IPs, cookies, credentials);
+- changes that make remote saturation pinning a default;
+- unverified "RCE" claims.
+
+## Adding a profile
+
+1. Use an exact image tag and the matching architecture.
+2. Run `tools/php2shell_calibrate.py` against a local lab.
+3. Confirm a real proof (`uid=...`), not just a successful response.
+4. Add `profiles/<build>.json` with the offsets, heap parameters and
+   `rce: true` only when the proof is reproducible.
+5. If stage 3 is probabilistic, say so in the profile and in the README table.
+6. Update `docs/profile-inventory.md` and the README status table together.
+
+Profiles must not contain target data. `rce: false` is a valid and useful
+result: negative data prevents false positives.
+
+## Code style
+
+- Python 3.11+ with the standard library; avoid new runtime dependencies.
+- Keep the dispatcher's safe defaults: loopback automatic, remote opt-in.
+- Error messages must not print secrets or raw target data.
+- Run the tests before opening a pull request:
+
+```sh
+python3 -m unittest discover -s tests -v
+gitleaks detect --source . --no-git --redact -v
+```
+
+## Pull request checklist
+
+- [ ] Tests pass and new logic has a test.
+- [ ] Profile changes include the exact image/tag and a proof.
+- [ ] README/inventory tables are updated and accurate.
+- [ ] No secrets, personal paths or third-party target data.
+- [ ] Credits are preserved (9bie, Karasawa2025, WoYinDao, PHP team).
+- [ ] The change does not weaken the authorization gates.
+
+## Disclosure
+
+This repository is not a vendor channel. If you find a new affected build or a
+new PHP issue, report it to the PHP security team and the distribution vendor
+through their coordinated disclosure process. Do not open a public issue with
+an unpatched exploit.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 devploit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,40 @@
+.PHONY: bootstrap test labs-up labs-down labs-status labs-test lint clean
+
+bootstrap:                     ## Fetch and pin the upstream exploit
+	python3 tools/bootstrap_upstream.py
+
+test:                          ## Run the unit test suite
+	python3 -m unittest discover -s tests -v
+
+lint:                          ## Run gitleaks to detect leaked secrets
+	gitleaks detect --source . --no-git --redact -v
+
+labs-up:                       ## Start all local laboratories (ports 8100-8106)
+	python3 tools/php2shell_labs.py up
+
+labs-down:                     ## Stop all local laboratories
+	python3 tools/php2shell_labs.py down
+
+labs-status:                   ## Show laboratory container status
+	python3 tools/php2shell_labs.py status
+
+labs-test:                     ## Run the dispatcher against each lab
+	python3 tools/php2shell_labs.py test
+
+inventory:                     ## Print the profile and offset inventory
+	python3 tools/php2shell_inventory.py
+
+validate-profiles:             ## Validate profiles (requires jsonschema)
+	python3 -c "import json, jsonschema; \
+	  schema = json.load(open('profiles/schema.json')); \
+	  from pathlib import Path; \
+	  [jsonschema.validate(json.loads(p.read_text()), schema) or print(f'  ok  {p.name}') \
+	   for p in sorted(Path('profiles').glob('*.json')) if p.name != 'schema.json']"
+
+clean:                         ## Remove generated files and vendor checkout
+	rm -rf vendor/php2shell-upstream
+	rm -rf lab/rce/out/
+
+help:                          ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | \
+	  awk 'BEGIN {FS = ":.*## "}; {printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2}'