# 0xdimas/nginx-rift-private-lab architecture

> Architecture diagram of the GitHub repository 0xdimas/nginx-rift-private-lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0xdimas/nginx-rift-private-lab
- Repository: https://github.com/0xdimas/nginx-rift-private-lab

## Overview

1. **What this repo is**
   - This is a security research and exploit-lab repository for an NGINX heap overflow PoC, with a strong focus on ASLR bypass techniques.
   - It is organized around one vulnerable NGINX target, one HTTP-accessible file-read primitive, and multiple exploit/assessment runners that chain those pieces together.

2. **Primary runtime boundary**
   - The architecture is split between an **attacker/controller side** (Python tooling in the repo) and a **target side** (NGINX + PHP application stack in containers or a VM).
   - The attacker never talks to the target through an internal API; everything is driven by HTTP requests to the same exposed listener and by reading files exposed through the file-read primitive.

3. **Main orchestration entry point**
   - `nginx_rifter.py` is the current central orchestrator.
   - Its role is assessment-first: it profiles the target, tests the file-read primitive, fingerprints the environment, discovers nginx worker/process state, and only runs the exploit when explicitly asked.
   - It is also the current integrated exploit entry point for the **coreless proc-mem** path.

4. **Legacy exploit path**
   - `nginx_rifter_core_v2_1.py` preserves the older **core-guided** path, where a worker crash is used to create a readable core file that is then mined for exploit data.
   - Older `demo_ctf_exploit_v1_*` scripts and `poc.py` represent earlier operator-facing or demo-oriented runners for the same underlying vulnerability chain.
   - The repo keeps these for comparison, reproducibility, and artifact-driven demos, but they are no longer the preferred architecture.

5. **Exploit data flow**
   - The exploit chain is: vulnerable nginx request handling → heap overflow during rewrite processing → heap shaping and target selection → memory disclosure via LFI/procfs → derivation of runtime addresses → final code execution verification.
   - The default ASLR bypass path uses PHP file reads to access nginx worker `/proc/<pid>/maps`, mapped libc, and `/proc/<pid>/mem`, then computes the runtime `system()` address and searches live memory for usable heap targets.
   - The legacy path replaces live procfs reads with a crash core dump.

6. **Target-side lab composition**
   - The `env/` directory contains the deployment layer: Dockerfiles, Compose files, nginx configs, PHP endpoints, and entrypoint scripts.
   - Important lab endpoints include the vulnerable nginx route, `/lfi.php` for local file reads, and `/phpinfo.php` for environment disclosure.
   - `env/server.py` and the nginx/PHP configs define the same-port topology the exploit expects: the vulnerable request path and the disclosure primitive must be reachable from the same target service.

7. **Deployment and repro environments**
   - `setup.sh`, `Vagrantfile`, and `vagrant/provision.sh` support repeatable lab setup across containerized and VM-based environments.
   - The repo explicitly supports both a deterministic Docker-style reproduction and a more realistic ASLR-enabled VM-style setup.
   - The architecture changes depending on environment only in the disclosure assumptions, not in the high-level exploit flow.

8. **Research probes and alternate leak search**
   - `tools/non_lfi_leak_probe.py` and `tools/non_lfi_active_response_probe.py` are negative/research probes that test whether nginx itself leaks useful state without LFI.
   - `tools/lfi_proc_mem_scan.py` and `tools/proc_mem_coreless_exploit.py` are more specialized harnesses for the proc-mem research path.
   - These tools sit on the research side of the boundary; they are not part of the target stack.

9. **Knowledge base and constraints**
   - `known_layout_patterns.json` appears to store empirically derived layout patterns used to recognize or validate memory layouts across runs.
   - The `docs/` directory is the project’s evidence and methodology layer: plans, findings, test logs, ASLR notes, and recording workflows.
   - This repo is therefore not just exploit code; it is also a reproducibility and analysis workspace.

10. **Artifacts as first-class outputs**
   - The `artifacts/` directory contains recorded terminal sessions, JSON run outputs, and verification logs from multiple exploit iterations.
   - These artifacts are important to the architecture because they document the evolution of the chain and provide proof of behavior across variants.
   - They also show that the repo is built as a research lab, not merely a single-shot PoC.

11. **Operational shape of the current tool**
   - `nginx_rifter.py` is parameterized around the target host/port and a pluggable file-read template, so it can adapt to different vulnerable deployments.
   - That makes the file-read primitive a clean abstraction boundary: the exploit logic consumes “read arbitrary path/range” capability without hard-coding a specific LFI implementation.
   - The rest of the chain assumes only that the primitive can reach the relevant process files and read enough data to resolve addresses.

12. **What an architecture diagram should emphasize**
   - Show three layers: the **target web stack**, the **file-read disclosure channel**, and the **Python exploit/assessment controller**.
   - Within the controller, distinguish the current `nginx_rifter.py` path from the legacy core-guided and demo scripts.
   - The crucial dependency arrows are: HTTP request spray to nginx, disclosure reads via PHP/LFI to procfs and libc, then address derivation back into the final exploit attempt and verification.

Main entry points: [`nginx_rifter.py`](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/nginx_rifter.py) (nginx_rifter.py), [`env/nginx.conf`](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/env/nginx.conf) (nginx stack), [`env/server.py`](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/env/server.py) (rewrite overflow), [`env/lfi.php`](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/env/lfi.php) (lfi.php)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_controller["Controller"]
  node_nginx_rifter["nginx_rifter.py<br/>assessor+exploit<br/>[nginx_rifter.py]"]
  node_nginx_rifter_core["core_v2_1<br/>legacy exploit"]
  node_demo_ctf["demo_ctf<br/>legacy demos"]
  node_ctf_remote["ctf_remote<br/>remote runner"]
  node_poc["poc.py<br/>poC runner<br/>[poc.py]"]
  node_proc_mem_scan["proc_mem_scan<br/>memory scan"]
  node_coreless_exploit["coreless exploit<br/>proc-mem exploit"]
  node_lfi_probe["lfi probe<br/>negative probe"]
  node_active_probe["active probe<br/>negative probe"]
end

subgraph group_target["Target Lab"]
  node_nginx_stack[("nginx stack<br/>vulnerable web stack<br/>[nginx.conf]")]
  node_rewrite_overflow["rewrite overflow<br/>heap overflow<br/>[server.py]"]
  node_lfi_endpoint["lfi.php<br/>file-read primitive<br/>[lfi.php]"]
  node_phpinfo_endpoint["phpinfo.php<br/>env disclosure<br/>[phpinfo.php]"]
  node_lab_entrypoints["entrypoints<br/>container hooks<br/>[entrypoint.sh]"]
end

subgraph group_env["Environments"]
  node_compose_defs["compose files<br/>deployment spec<br/>[docker-compose.yml]"]
  node_dockerfiles["Dockerfiles<br/>build recipes"]
  node_vagrant_setup["Vagrant<br/>vm repro"]
  node_setup_sh["setup.sh<br/>bootstrap<br/>[setup.sh]"]
end

subgraph group_research["Research"]
  node_knowledge_base["patterns<br/>layout knowledge"]
  node_docs["docs<br/>methodology"]
  node_artifacts["artifacts<br/>run outputs"]
end

node_nginx_rifter -->|"sprays requests to"| node_rewrite_overflow
node_nginx_rifter -->|"reads via"| node_lfi_endpoint
node_nginx_rifter -->|"fingerprints via"| node_phpinfo_endpoint
node_nginx_rifter -->|"matches layouts with"| node_knowledge_base
node_nginx_rifter -->|"records results in"| node_artifacts
node_nginx_rifter -->|"invokes path"| node_coreless_exploit
node_nginx_rifter_core -->|"sprays requests to"| node_rewrite_overflow
node_nginx_rifter_core -->|"stores runs in"| node_artifacts
node_demo_ctf -->|"exercises"| node_rewrite_overflow
node_ctf_remote -->|"targets"| node_rewrite_overflow
node_poc -->|"demonstrates"| node_rewrite_overflow
node_proc_mem_scan -->|"scans through"| node_lfi_endpoint
node_coreless_exploit -->|"derives from"| node_lfi_endpoint
node_lfi_probe -->|"tests"| node_nginx_stack
node_active_probe -->|"tests"| node_nginx_stack
node_nginx_stack -->|"contains"| node_rewrite_overflow
node_nginx_stack -->|"exposes"| node_lfi_endpoint
node_nginx_stack -->|"exposes"| node_phpinfo_endpoint
node_lab_entrypoints -->|"starts"| node_nginx_stack
node_compose_defs -->|"orchestrates"| node_lab_entrypoints
node_dockerfiles -->|"builds"| node_compose_defs
node_vagrant_setup -.->|"mirrors"| node_compose_defs
node_setup_sh -->|"bootstraps"| node_vagrant_setup
node_docs -.->|"documents"| node_nginx_rifter
node_artifacts -.->|"evidence for"| node_docs

click node_nginx_rifter "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/nginx_rifter.py"
click node_nginx_rifter_core "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/nginx_rifter_core_v2_1.py"
click node_demo_ctf "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/demo_ctf_exploit.py"
click node_ctf_remote "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/ctf_remote_exploit.py"
click node_poc "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/poc.py"
click node_proc_mem_scan "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/tools/lfi_proc_mem_scan.py"
click node_coreless_exploit "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/tools/proc_mem_coreless_exploit.py"
click node_lfi_probe "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/tools/non_lfi_leak_probe.py"
click node_active_probe "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/tools/non_lfi_active_response_probe.py"
click node_nginx_stack "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/env/nginx.conf"
click node_rewrite_overflow "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/env/server.py"
click node_lfi_endpoint "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/env/lfi.php"
click node_phpinfo_endpoint "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/env/phpinfo.php"
click node_lab_entrypoints "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/env/entrypoint.sh"
click node_compose_defs "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/env/docker-compose.yml"
click node_dockerfiles "https://github.com/0xdimas/nginx-rift-private-lab/tree/main/env/Dockerfile"
click node_vagrant_setup "https://github.com/0xdimas/nginx-rift-private-lab/tree/main/Vagrantfile"
click node_knowledge_base "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/known_layout_patterns.json"
click node_docs "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/docs/CORELESS_ASLR_PLAN.md"
click node_artifacts "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/artifacts/nginx_rifter_20260515-v2-final.json"
click node_setup_sh "https://github.com/0xdimas/nginx-rift-private-lab/blob/main/setup.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_nginx_rifter,node_nginx_rifter_core,node_demo_ctf,node_ctf_remote,node_poc,node_proc_mem_scan,node_coreless_exploit,node_lfi_probe,node_active_probe toneBlue
class node_nginx_stack,node_rewrite_overflow,node_lfi_endpoint,node_phpinfo_endpoint,node_lab_entrypoints toneAmber
class node_compose_defs,node_dockerfiles,node_vagrant_setup,node_setup_sh toneMint
class node_knowledge_base,node_docs,node_artifacts toneRose
```

## Components

### Controller

Python-side assessment, disclosure, and exploit orchestration

- [nginx_rifter.py](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/nginx_rifter.py): assessor+exploit · Current central orchestrator for assessment-first profiling and coreless proc-mem exploitation · `nginx_rifter.py`
- [core_v2_1](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/nginx_rifter_core_v2_1.py): legacy exploit · Older core-guided exploit path that mines crash cores for data · `nginx_rifter_core_v2_1.py`
- [demo_ctf](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/demo_ctf_exploit.py): legacy demos · Operator-facing demo runners for earlier exploit iterations · `demo_ctf_exploit.py`
- [ctf_remote](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/ctf_remote_exploit.py): remote runner · Remote exploit entrypoint for target execution · `ctf_remote_exploit.py`
- [poc.py](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/poc.py): poC runner · Minimal proof-of-concept exploit harness · `poc.py`
- [proc_mem_scan](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/tools/lfi_proc_mem_scan.py): memory scan · Specialized harness for proc-mem disclosure research · `tools/lfi_proc_mem_scan.py`
- [coreless exploit](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/tools/proc_mem_coreless_exploit.py): proc-mem exploit · Specialized coreless exploitation harness using live procfs reads · `tools/proc_mem_coreless_exploit.py`
- [lfi probe](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/tools/non_lfi_leak_probe.py): negative probe · Tests for useful leaks without LFI-assisted disclosure · `tools/non_lfi_leak_probe.py`
- [active probe](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/tools/non_lfi_active_response_probe.py): negative probe · Tests whether nginx responses reveal exploitable state · `tools/non_lfi_active_response_probe.py`

### Target Lab

NGINX/PHP deployment and vulnerable request path

- [nginx stack](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/env/nginx.conf): vulnerable web stack · Target-side NGINX and PHP service exposed on one listener · `env/nginx.conf`
- [rewrite overflow](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/env/server.py): heap overflow · Vulnerable NGINX request handling and heap-shaping path · `env/server.py`
- [lfi.php](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/env/lfi.php): file-read primitive · HTTP-accessible arbitrary file read used to reach procfs and libc mappings · `env/lfi.php`
- [phpinfo.php](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/env/phpinfo.php): env disclosure · Supplementary endpoint for environment fingerprinting · `env/phpinfo.php`
- [entrypoints](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/env/entrypoint.sh): container hooks · Container startup scripts for lab services and modes · `env/entrypoint.sh`

### Environments

Container and VM repro/deployment scaffolding

- [compose files](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/env/docker-compose.yml): deployment spec · Docker Compose variants for standard, LFI, CTF, and non-LFI leak modes · `env/docker-compose.yml`
- [Dockerfiles](https://github.com/0xdimas/nginx-rift-private-lab/tree/main/env/Dockerfile): build recipes · Container build definitions for the lab images · `env/Dockerfile`
- [Vagrant](https://github.com/0xdimas/nginx-rift-private-lab/tree/main/Vagrantfile): vm repro · VM-based reproducible lab setup and provisioning · `Vagrantfile`
- [setup.sh](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/setup.sh): bootstrap · Top-level helper for repeatable lab setup · `setup.sh`

### Research

Support tooling, notes, and captured artifacts

- [patterns](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/known_layout_patterns.json): layout knowledge · Empirical layout patterns used to recognize and validate memory layouts · `known_layout_patterns.json`
- [docs](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/docs/CORELESS_ASLR_PLAN.md): methodology · Plans, findings, logs, and workflow notes for the research lab · `docs/CORELESS_ASLR_PLAN.md`
- [artifacts](https://github.com/0xdimas/nginx-rift-private-lab/blob/main/artifacts/nginx_rifter_20260515-v2-final.json): run outputs · Recorded sessions, JSON outputs, and verification logs from exploit iterations · `artifacts/nginx_rifter_20260515-v2-final.json`

## Connections

- nginx_rifter.py → rewrite overflow: sprays requests to · Drives the vulnerable request-handling path against the target
- nginx_rifter.py → lfi.php: reads via · Uses the file-read primitive as the disclosure boundary
- nginx_rifter.py → phpinfo.php: fingerprints via · Collects environment details for ASLR and process-state inference
- nginx_rifter.py → patterns: matches layouts with · Consults empirically derived layout patterns during assessment
- nginx_rifter.py → artifacts: records results in · Writes assessment, derive, and exploit outputs as artifacts
- nginx_rifter.py → coreless exploit: invokes path · Integrated current exploit path for live proc-mem ASLR bypass
- core_v2_1 → rewrite overflow: sprays requests to · Uses the same overflow chain but with legacy core-guided recovery
- core_v2_1 → artifacts: stores runs in · Captures legacy core-guided iterations and evidence
- demo_ctf → rewrite overflow: exercises · Earlier operator-facing demo execution of the vulnerability chain
- ctf_remote → rewrite overflow: targets · Remote exploit runner aimed at the same vulnerable request path
- poc.py → rewrite overflow: demonstrates · Minimal PoC for the underlying heap overflow
- proc_mem_scan → lfi.php: scans through · Specialized scanner for proc-mem disclosure over the file-read primitive
- coreless exploit → lfi.php: derives from · Reads live procfs data through the disclosure channel
- lfi probe → nginx stack: tests · Research probe for nginx-native leaks without LFI
- active probe → nginx stack: tests · Research probe for active-response leakage from nginx
- nginx stack → rewrite overflow: contains · Target web stack exposes the vulnerable handling path
- nginx stack → lfi.php: exposes · Same listener also exposes the file-read endpoint
- nginx stack → phpinfo.php: exposes · Same target service exposes environment disclosure
- entrypoints → nginx stack: starts · Container entrypoints bootstrap the target service
- compose files → entrypoints: orchestrates · Compose variants define which entrypoint and service mode is launched
- Dockerfiles → compose files: builds · Image definitions underpin the deployment variants
- Vagrant → compose files: mirrors · VM repro path mirrors the containerized lab topology
- setup.sh → Vagrant: bootstraps · Top-level setup helper prepares the VM-based lab workflow
- docs → nginx_rifter.py: documents · Methodology and findings track the current orchestrator and exploit flow
- artifacts → docs: evidence for · Captured runs support the project notes, plans, and logs
