Test an LB rule with a managed CVE lab
Use mockforge cve to reproduce a reviewed CVE against a real vulnerable
application, then test the same request through your load balancer. MockForge
downloads pinned container images, runs the checks, records the evidence, and
removes its containers after the run.
The default catalog exposes the verified Next.js CVE-2025-29927, the Node.js CVE-2026-111497 Node2Shell Brotli decoder lab, and the CVE-2024-4577 Windows PHP-CGI pack. Node2Shell uses a pinned official Node image, reviewed app, and HTTP/2-capable recorder. The PHP-CGI image remains refused until its reviewed digest is pinned. The PHP2Shell 2026 pair remains hidden by default; those PHP core packs are distinct from the 2024 Windows CGI pack.
All packs support Linux amd64 with Python 3.11+ and a local Docker or Podman engine. Install those prerequisites separately. No Compose installation, pip packages, Nuclei installation, or source checkout is required.
Check prerequisites
mockforge cve doctor
mockforge cve list
For Podman, put --engine podman before the subcommand:
mockforge cve --engine podman doctor
The catalog contains reviewed packs and clearly marks any image still pending review. An unsupported CVE fails before any
download or request. Image versions are pinned by digest, and the runner
refuses any pack whose application image is not digest-pinned yet. Upgrading
MockForge
updates the reviewed catalog; runs do not silently select newer image tags or
community templates. mockforge cve list prints one catalog entry per
reviewed pack, keyed by CVE, including each pack’s image review status.
Check which pinned images this machine holds
The image digests are reviewed pack data, the same as the test cases. A run pulls exactly the pinned digests - never a newer tag - and refuses a pack whose application image has no reviewed digest yet; see Where does this go? for how cases and images land.
Digest-pulled images do not show up in docker images output the way tagged
images do, so after a run you cannot tell from that listing whether the
reviewed images are actually on your machine. The images check answers
that from the pack catalog: it inspects every pinned image by digest with
your container engine - the same check prepare and every run perform -
and prints one present/missing entry per image:
mockforge cve images # every verified pack
mockforge cve images CVE-2025-29927 # one verified pack
By default, images reports verified packs. Add --include-unverified before
images to include packs still under development; an explicit unverified CVE
is refused without that flag, matching run and prepare.
The command exits 0 when every pinned image is present and 1 when any
is missing, so it works as a scriptable pre-flight check. A missing image
is fixed by mockforge cve prepare <CVE> (online) or by loading the exact
digests (see Air-gapped lab hosts).
Every run records the same verification in report.json under
image_verification - the two pinned images with their digests and their
present status at run time - and prints a one-line
Images verified on this machine: 2/2 ... summary, so each report attests
exactly which images produced its evidence.
Know before you run: where the recorder listens
Every run prints its plan before anything downloads or starts:
Recorder endpoint: 127.0.0.1:18082
Target under test: https://your-test-lb.example, configure its LB/WAAP upstream to forward to the recorder endpoint above before requests flow
- The recorder endpoint is
<listen-address>:<origin-port>and defaults to127.0.0.1:18082. A default bind only accepts connections from the lab host itself; when your LB/WAAP runs on another machine, the plan prints a reminder to pass--listen-address <an isolated lab interface IP>. mockforge cve listshows the default origin port and the listen-address guidance for each reviewed pack, so you can configure the LB upstream before the first attempt instead of debugging after one.- Without
--target, the plan notes that the lab reproduces the CVE directly and no LB/WAAP is tested.
Run the direct application baseline
mockforge cve run CVE-2025-29927 --output-dir nextjs-baseline
On first use, the command downloads the required images. Subsequent runs reuse the image cache. To download them ahead of time, run:
mockforge cve prepare CVE-2025-29927
prepare is the only step that needs a registry connection, and only when an
image is missing from your engine. Every run repeats the same local check
first: it inspects each pinned image by digest and pulls only if that exact
image is absent. So after prepare (or after loading the images as described
in Air-gapped lab hosts), later runs for that CVE need
no internet access and no registry. MockForge itself talks only to your
container engine, the lab application on loopback, and your --target. If you
remove the images (for example with docker image prune -a), the next run
pulls them again. prepare is per CVE: each pack has its own application
image, so prepare every CVE you plan to run.
A successful baseline reports baseline-confirmed: an ordinary request receives
an authentication redirect, and the test request reaches the protected dashboard.
This result does not test an LB. The application and test client stop automatically.
Each invocation requires a new output directory to preserve earlier evidence.
Test your load balancer
Configure your test LB to forward to the lab recorder on port 18082. The
recorder forwards requests to the real vulnerable application and records which
requests reached the origin. It runs only for the duration of the command.
The recorder always speaks plain HTTP. It has no TLS listener and no
certificate. Configure the LB’s upstream (pool) member as http://<recorder address>:18082, not https://, and turn off any upstream TLS or server-side
re-encryption for that pool. Only the LB’s own listener, the address you pass
as --target, can use HTTPS. The traffic path looks like this:
MockForge client --https (or http)--> your LB --plain http--> recorder <listen-address>:18082 --> lab app
If you changed --origin-port, use that port instead of 18082.
--skip-tls-verify applies only to the first leg (MockForge client to
--target); it has no effect on the LB-to-recorder leg, which has no TLS to
verify.
For an LB on the same host:
mockforge cve run CVE-2025-29927 \
--target https://your-test-lb.example \
--output-dir nextjs-lb-test
The recorder binds to 127.0.0.1 by default. For a remote LB, bind to a specific
isolated lab interface, then configure the LB’s upstream to that address:
mockforge cve run CVE-2025-29927 \
--listen-address 192.168.2.10 --origin-port 18082 \
--target https://your-test-lb.example \
--output-dir nextjs-lb-test
Replace the address with your lab host’s address. This exposes a vulnerable lab through the recorder, so keep that interface accessible only to the test network. The application container itself publishes only on loopback. Remote Docker engines and non-Linux container hosts are not supported by this pack.
Preserve the X-Mockforge-Cve header and __mockforge_cve query parameter through
the LB. Use a trusted HTTPS certificate for the LB. TLS verification on the
--target connection is on by default; for self-signed test certificates pass
--skip-tls-verify: an explicit, per-run opt-in that also disables certificate
validation inside the test client and prints a warning while active. Never use
it against an untrusted network. If the configured rejection code differs from
403, pass --block-status with that code.
The Node2Shell pack (CVE-2026-111497)
This pack reproduces the Brotli decoder out-of-bounds write bundled with
Node.js (GHSA-9v8h-qqgm-4m35, fixed in Node 22.23.4, 24.22.1, and 26.12.1).
The lab runs the pinned official node:22.23.3 image with a small reviewed
lab application that decompresses request bodies on POST /decode - the
exposure surface the advisory names - plus healthy / and /health routes
for the controls.
The exploit request rides cleartext HTTP/2 (prior knowledge), matching the “HTTP2Shell” exposure shape, and carries the reviewed crash trigger. The trigger is generated locally (never downloaded), and its SHA256 is asserted on every build. Because the expected outcome is a crashed origin rather than an HTTP response, the evidence differs from the Next.js pack:
- A direct run confirms the reproduction when the lab application process
dies after the trigger arrives (the container exits). On a patched runtime
the same request is answered with
422and the application stays healthy. - Through an LB,
passmeans the exploit request was blocked and the origin stayed healthy;failmeans the exploit reached the origin, which then crashed - a dead control after the exploit corroborates the failure instead of masking it.
Both directions of the trigger were verified locally against official Node
22.23.3 (SIGSEGV) and 22.23.4 (clean 422 ERR__ERROR_FORMAT_BLOCK_SWITCH)
before this pack shipped; the pinned image uses the identical bundled decoder.
The recorder accepts HTTP/2 and HTTP/1.1 on the same recorder port, so an
LB/WAAP can forward over either protocol. Configure --block-status to
whatever your LB returns for the blocked request.
CVE-2024-4577 lab pack (PHP-CGI argument injection)
Image pending review
The CVE-2024-4577 pack covers the PHP CGI argument injection that affects
php-cgi on Windows with a best-fit codepage (fixed in PHP 8.1.29, 8.2.20, and
8.3.8). Because the bug is Windows-CGI-specific, the lab image is not a stock
Linux PHP container: it runs a pinned, vulnerable PHP 8.3.7 php-cgi.exe
under Wine behind Apache httpd in a CGI arrangement, defined and reviewed per
examples/cve-lab/cve-2024-4577-lab-image/ in the MockForge repository.
The image has not completed its build-and-review yet, so the pack’s catalog
entry carries an explicit pending-lab-host-review status. The runner refuses
any pack whose images are not digest-pinned, so until a reviewed image digest
is published with a MockForge release, prepare and run for this pack stop
with a clear message and touch no containers:
docker.io/mockforge/cve-lab-phpcgi-wine:pending-lab-host-review is not pinned
by digest; reviewed packs refuse unreviewed images. ...
When the reviewed image ships, the pack works like the Next.js one: run
reproduces the injection directly against the lab, and --target compares
your LB/WAAP, where pass requires the exploit request (the %AD argument
injection with a PHP payload body) to be blocked while benign and ordinary
requests still reach the application.
The PHP2Shell 2026 packs (CVE-2026-109618 / CVE-2026-109619)
These development packs are unverified and hidden from the default catalog.
Live Docker runs on Docker 29.1.4 / PHP 8.4.26 / Apache 2.4.69 returned
200 upload processed without the expected crash marker, so they did not
reproduce and cannot establish a vulnerability verdict. list, prepare, and
run omit or refuse them by default. For development only, pass the global
--include-unverified option before the subcommand (for example,
mockforge cve --include-unverified list or
mockforge cve --include-unverified run CVE-2026-109618 --output-dir php2shell-dev).
They are not verified, working packs.
These two packs cover the PHP core request-lifecycle disclosures of October 2026: CVE-2026-109618 (an out-of-memory failure during request input parsing leaves partly-initialized state that request shutdown then consumes, GHSA-w8hw-w9fx-j79w) and CVE-2026-109619 (worker-global state can outlive freed request memory and is consumed by a later request on the same worker, GHSA-6wmf-4rv5-p3rp). Both are fixed in PHP 8.2.35, 8.3.36, 8.4.27, and 8.5.12.
They are a different vulnerability family from the CVE-2024-4577 pack
(Windows CGI argument injection): no Wine image, no Windows anything. The lab
is the digest-pinned official php:8.4.26-apache image - Apache with mod_php,
the SAPI the advisories confirmed - running a small reviewed lab application
and configuration that ship inside the pack. The configuration deliberately
sets memory_limit below post_max_size so the advisory’s OOM-during-parse
trigger class is reachable with bounded request bodies.
- The CVE-2026-109618 pack sends one oversized multipart request whose part headers exhaust the memory limit mid-parse.
- The CVE-2026-109619 pack sends a producer request (the same memory pressure with session upload progress active) followed by a consumer request on one keep-alive connection, so both reach the same Apache child.
The containers keep --cap-drop=ALL and no-new-privileges; Apache receives
only SETUID and SETGID so its prefork children can switch to www-data.
The expected outcome is a crashed Apache worker, confirmed from the
deterministic exit signal Segmentation fault entry in the application
container log. pass requires the exploit request to be blocked by your
LB/WAAP while benign and ordinary requests still reach the application;
fail means the exploit reached the origin, which then crashed.
Verification status: the image is the official digest-pinned PHP build, but
the trigger choreography is advisory-derived - no public proof-of-concept
existed when this pack shipped - and mockforge cve doctor requires a Linux
amd64 lab host, so the packs carry an explicit
pending-lab-host-verification status. On a lab host the packs run their full
choreography; if the documented corruption marker does not appear, the run
reports inconclusive rather than a verdict. Adjust nothing by hand: the
request bodies are generated with pinned SHA256 digests, so any change is a
pack revision, not an edit.
Air-gapped lab hosts
The pack is designed for lab VMs that never touch the internet. Images are
pinned by digest, so a host that already holds the exact images needs no
network access: prepare inspects each pinned image locally and skips pulling
when the digest is present.
On a connected machine with the same container engine:
mockforge cve prepare CVE-2025-29927
docker save -o mockforge-cve-images.tar \
$(mockforge cve list | python3 -c "import json,sys; c=json.load(sys.stdin); p=c['CVE-2025-29927']; print(p['application_image'], p['runner_image'])")
Transfer mockforge-cve-images.tar to the air-gapped VM and load it with the
same engine, then confirm before running:
docker load -i mockforge-cve-images.tar
mockforge cve prepare CVE-2025-29927 # verifies by digest; does not pull
mockforge cve run CVE-2025-29927 --output-dir nextjs-baseline
Podman hosts use the identical podman save/podman load commands. Do not
re-tag or mutate the loaded images; the digest reference must keep matching.
Read the report
Open report.json in the output directory. The directory also retains Nuclei’s
request and response evidence, the exact generated templates, application logs,
and container ownership information.
pass: the direct reproduction succeeded, the LB returned the expected rejection, no correlated signature request reached the origin during the observation window, and benign requests reached the application.fail: the signature request reached the origin, including cases where the LB returned a rejection after forwarding it.inconclusive: the application baseline, client execution, routing, control requests, or expected response could not be verified.baseline-confirmed: the direct reproduction succeeded without an LB target.
The CLI also prints a plain-language summary that states the exposure
conclusion directly: <target> is NOT exposed to <CVE> on pass,
<target> is EXPOSED to <CVE> on fail, followed by the reason and the
individual evidence checks that produced the verdict. The same checks are
stored in report.json under evidence_checks.
What each Details line means
A few terms first. The application is the vulnerable lab MockForge starts.
The recorder is the small proxy MockForge runs on the listen address: it
writes down every request that reaches it, then passes it to the application.
Your LB’s upstream points at the recorder, so “reached the origin” means “the
recorder saw it”. The signature request is the one request that reproduces
the CVE, as described in the advisory. Controls are harmless requests used to
prove your LB is forwarding normally. Each request carries a unique token for
this run (the X-Mockforge-Cve header and __mockforge_cve query parameter),
which is how MockForge matches what it sent to what the recorder saw.
For the Next.js CVE-2025-29927 pack, the checks run in this order:
| Details line | In plain words |
|---|---|
| direct baseline reproduces the vulnerability | Before your LB is involved, MockForge sent the signature request straight to its own lab application and confirmed the bypass works (HTTP 200 with the protected page’s content). If this is not satisfied, the lab itself did not behave as expected and nothing can be concluded about your LB. |
| benign controls corroborate origin reachability | A harmless request to the login page was sent through your LB before and after the signature request. It must return 200 and the recorder must have seen exactly one matching request. This proves the LB really forwards to the recorder and is not blocking everything. |
| ordinary requests to the protected route match the application redirect | A plain request to the protected route (no signature) was sent through your LB before and after. The application answers it with a redirect (307) to its login page, and the recorder must have seen it. This proves normal traffic still reaches the application and the application’s own protection works. |
| every origin request correlates with this run | Every request the recorder saw carries this run’s token. Stray traffic, or an LB that strips the header and query parameter, makes a blocking verdict impossible, so the run stops as inconclusive. |
| signature request was blocked at the target | The signature request did not reach the recorder. If it did, the line shows the status the application returned and the verdict is fail, even if your LB then sent the client a 403. |
| target response matched the configured block status (403) | The LB answered the signature request with the status from --block-status (default 403). |
Checks run top to bottom and stop at the first one that is not satisfied, so a short list means the run stopped there. The wording of the lines differs slightly for other packs (the CVE-2024-4577 pack says “exploit request” and “executes the injected PHP payload”), but the order and meaning are the same.
Only pass and baseline-confirmed exit successfully. Nuclei observations in
this pack match any HTTP response for evidence collection. A Nuclei JSON row is
not itself a vulnerability finding; use MockForge’s final verdict.
What a run tests, and how to add cases
Each pack has exactly one signature scenario: one request that reproduces the
CVE. A pack may additionally declare signature variants: more must-be-blocked
placements of the attack signature, reviewed as pack data (see below). Around
the signature, the run sends two kinds of controls: a benign request to the
vulnerable endpoint and an ordinary request to a normal route. One --target
run sends 8 requests in total:
- direct to the lab (not through your LB): the two controls, then the signature request, as the baseline;
- through your LB: the two controls, the signature request, then the two controls again. The controls before and after prove the LB was still forwarding normally when the signature request was handled.
Each pack’s coverage field in mockforge cve list states its scope, for
example “One reviewed authorization-bypass case and benign controls; not all
variants”. A pack is data (the signature request, the controls and their
expected statuses, the pinned images) plus its own evidence checks that decide
the verdict.
Coverage today. Both shipped packs fully cover their documented scenario:
CVE-2025-29927 runs its signature request plus the benign and ordinary
controls in every phase (8 requests per --target run), and CVE-2024-4577
does the same for the CGI injection. Neither pack has missing cases within
its reviewed scope; what they could not do until now is gain additional
cases without editing verdict code. That is what the mechanism below adds.
Adding a test case to an existing pack (data only)
A pack can declare extra cases in its catalog entry, and the runner and the verdict checks pick them up without any code change. Each case is one more request with its own expected status:
"extra_cases": [
{
"id": "robots",
"path": "/robots.txt?__mockforge_cve={token}",
"expect_status": 200,
},
{
"id": "apiversion",
"method": "GET",
"path": "/api/version?__mockforge_cve={token}",
"headers": {"Accept": "application/json"},
"expect_status": 404,
},
],
Every extra case runs once in the direct baseline and once before and after
the signature request through your LB (a run sends 8 + 3 per extra case
requests). Each carries its own correlation token; the verdict checks that
the origin answered every extra case with exactly its expect_status, both
before and after the signature request. A wrong status, a missing origin
observation, or a transport error makes the run inconclusive - it can
never turn a fail into a pass. Cases are still reviewed content: they
ship with a pack revision and their tests, not as a per-run option.
Where does this go?
Nowhere at run time. There is no per-run case file: mockforge cve run
takes a CVE ID and its options, nothing else. Every mockforge cve command
unpacks the lab scripts bundled inside the CLI, including the catalog, into
a temporary directory and runs exactly those. What runs is what was
reviewed and pinned - never a file you provide.
A case reaches the shipped CLI as catalog data:
- Edit the pack’s entry in
scripts/cve_lab_catalog.pyin the MockForge repository: add the case toextra_cases, or tosignature_variantsfor a must-be-blocked case. - Add or adjust tests in
scripts/tests/test_managed_cve_lab.py. - Regenerate the bundled copy with
python3 scripts/bundle_cli_tools.py(--checkreports a stale bundle). - Open a pull request. The case is reviewed as pack data, like the rest of the catalog, and ships with a MockForge release.
To request a case instead of writing it, open an issue with the advisory link and the behavior to test.
To try your own cases today, without a release or a source checkout, export
the bundled scripts and edit the exported copy. mockforge tools export
requires a new directory and never overwrites one:
mockforge tools export --output-dir cve-lab-local
python3 cve-lab-local/scripts/cve_lab.py list
python3 cve-lab-local/scripts/cve_lab.py run --help
Edit cve-lab-local/scripts/cve_lab_catalog.py and run the exported
cve_lab.py with the same subcommands as mockforge cve. A wrongly
declared case fails loudly, never silently changes a verdict: the verdict
checks require every declared case to answer exactly its expected status,
and the data-driven and variant paths validate the declared shape before
anything downloads. Results from an edited catalog are unreviewed and stay
on that machine - MockForge itself always runs the catalog bundled in its
release.
Adding signature variants (more must-be-blocked cases, data only)
The signature is one reviewed attack request. A pack can declare
signature_variants: additional requests that place the same attack signature
in other positions (request URI, query parameters, headers, another body
position), so a blocking rule must cover the pattern wherever it appears, not
just where the signature request carries it. Each variant is data of the form:
"signature_variants": [
{
"id": "marker-in-query",
"method": "POST",
"path": "/upload.php?PHP_SESSION_UPLOAD_PROGRESS=...&__mockforge_cve={token}",
"headers": {"X-Mockforge-Cve": "{token}"},
"body_ref": "oom_body", # or body_template + body_sha256
"expect": "blocked",
"reproduces_directly": True,
},
],
Every variant runs twice per --target run. In the direct baseline it must
reach the origin (its correlation token is observed), and a variant marked
reproduces_directly: true must additionally reproduce the pack’s reviewed
crash evidence - a variant whose direct behavior was not demonstrated makes
the run inconclusive instead of asserting blocking for it. Through your LB
the variant must be blocked: no origin observation for its token, answered
with the configured block status. The verdict is reported per variant in
report.json (signature_variants, with direct, target and a per-variant
verdict) and in the evidence details; one variant that got through fails the
run and is named, never averaged away. Variant evidence can only downgrade
the verdict - it can never turn a fail into a pass.
Bodies stay generated and digest-pinned: body_ref names a reviewed builder
in scripts/cve_lab_payloads.py (each re-asserts its pinned SHA256 before
anything is sent), a literal body_template must pin its exact bytes
with body_sha256 and carry no run token, and a variant with neither sends
no body (a plain-GET probe). validate_data_driven_pack
refuses malformed variants - missing fields, an expect other than
"blocked", unknown body references, unpinned bodies, a reproduces_directly
mark on a pack without crash evidence - before any download. The
CVE-2026-109618 pack ships five variants covering the PHP_SESSION_UPLOAD_PROGRESS
marker as a URI segment, a query parameter (on a multipart POST and on a
plain bodyless GET), a request header, and a urlencoded body field name -
the source cases are the field requests Srikanth (srikr) shared on
issue #79.
The CVE-2026-109619 pack ships ten variants covering its ini_set,
php_value and php_admin markers as the raw text/plain request body,
as a query parameter, and as a request-URI path segment (with the
x-php/test header swap the source cases carry), plus one marker carried
in a request header - from the same field requests.
Adding a new CVE pack (data only, when the outcome is a status)
A pack whose evidence model is “the signature request must be blocked while
every control is answered with its declared status” needs no verdict code at
all: it names data-driven for both its baseline_gate and classifier
and declares its probe, controls, expected statuses, and any extra cases as
data. run validates the shape before anything downloads
(validate_data_driven_pack in scripts/cve_lab_catalog.py), so a
wrongly declared pack fails loudly instead of producing unverifiable verdicts.
A pack that needs a different evidence model - a crash marker, a body
signature - still gets its own baseline gate and classifier, because the
verdict logic must be reviewed with the behavior it judges.
To add either kind of pack:
- Add its entry to
PACKSinscripts/cve_lab_catalog.py(images pinned by digest;data-drivengate and classifier when the outcome is a status). - For a non-status evidence model, add the matching baseline gate and
classifier in
scripts/cve_lab_evidence.py. - Add tests in
scripts/tests/test_managed_cve_lab.py, regenerate the bundled copy withpython3 scripts/bundle_cli_tools.py, and open a pull request. Adding cases or signature variants to an existing pack follows the same path: edit the pack’sextra_casesorsignature_variants, add tests, open the pull request.
If you want an additional scenario for a CVE already in the catalog, open an issue with the advisory link and the behavior to test.
To exercise your own extra requests today without changing MockForge, use the
signature-only per-CVE rule packs: its profile.json accepts
up to five benign controls next to the signature. Those tools do not start a
vulnerable application.
This tests one request-blocking scenario per pack. It does not establish protection against every CVE variant, prove that the application was patched, or evaluate an LB policy that intentionally forwards a sanitized request. The PHP2Shell 2026 packs assert the reviewed crash outcome, not remote code execution, which these labs do not attempt. Log4Shell and other CVEs are not managed packs in this release. The older CVE signature tools remain available separately.
Recover an interrupted run
Normal completion, errors, and handled termination attempt to remove only the containers owned by the run. After a forced kill or host interruption, run:
mockforge cve down --output-dir nextjs-lb-test
Use the same engine as the original run. Cleanup checks container ownership labels before removing anything. Reports and cached images remain available.