diff --git a/README.md b/README.md index 45f70b2..4d78502 100644 --- a/README.md +++ b/README.md @@ -1,171 +1,114 @@ -# Exploit Lab (C/C++) - Safe Memory Vulnerability Learning Lab +# Exploit Lab -> A structured, multi-phase lab for understanding memory vulnerabilities from first principles using safe, controlled demonstrations. +Hands-on C demos for observing unsafe input, stack layout, overflow behavior, and control-flow concepts in a controlled, educational environment. -A modular, beginner-friendly lab for understanding memory vulnerability concepts in C through conceptual demonstration and controlled simulation. +## Overview -This project is educational only. It does not include exploit payloads or exploitation instructions. +This repository is a memory-safety learning lab built around small, focused C programs. It exists to show how unsafe input handling behaves, how stack memory is laid out at runtime, how undefined behavior can appear after an out-of-bounds write, and how function-pointer reassignment changes execution flow in a safe, explicit way. -## What This Lab Covers +The project is relevant to application security, systems programming, and debugging workflows. It is designed to help developers and learners understand why bounded input, runtime inspection, and defensive coding practices matter in real programs. -- Unsafe vs safe input handling -- Stack memory layout observation -- Overflow behavior observation (controlled) -- Conceptual control-flow redirection using function pointers -- Practical debugging with GDB -- Runtime protection concepts (ASLR, NX, stack canaries) +## Features -## Core Programs (5) +- Demonstrates unsafe input handling with `scanf("%s", ...)` in a small stack-buffer example. +- Demonstrates safe input handling with `fgets(...)` and newline cleanup. +- Prints stack-frame addresses for local variables and function parameters. +- Shows overflow-related instability in a controlled demo that warns when input exceeds the buffer capacity. +- Simulates control-flow redirection with a function pointer reassignment. +- Includes GDB-oriented walkthroughs for inspecting locals, registers, and stack state. +- Documents runtime protections such as ASLR, NX, and stack canaries at a conceptual level. +- Provides captured screenshots and notes for the demos in `docs/images/`. +- Includes a GitHub Actions workflow that compiles all active demos on push and pull request. -1. `vuln_buffer_overflow` - unsafe input pattern demonstration -2. `safe_input_demo` - bounded input with `fgets(...)` -3. `stack_layout_demo` - stack address observation -4. `overflow_behavior_demo` - controlled overflow behavior observation -5. `control_flow_simulation` - conceptual control-flow redirection +## Tech Stack -## Project Structure - -```text -exploit-lab-cpp/ -|-- src/ -| |-- vuln_buffer_overflow.c -| |-- safe_input_demo.c -| |-- stack_layout_demo.c -| |-- overflow_behavior_demo.c -| `-- control_flow_simulation.c -|-- archive/ -| |-- main.c -| `-- stack_behavior_demo.c -|-- docs/ -| |-- gdb-guide.md -| |-- memory-layout.md -| |-- protections.md -| |-- advanced-concepts.md -| |-- lab-exercises.md -| |-- demo.md -| `-- images/ -|-- Makefile -`-- README.md -``` +- Language: C +- Compiler: GCC +- Debugger: GDB +- Build tool: Make +- CI: GitHub Actions +- Target platforms: Linux and Windows with MinGW-compatible builds -## Build +## Project Structure -Compile all core programs: +- `src/` -> active lab programs that build into the five demo binaries + - `vuln_buffer_overflow.c` -> unsafe input demo using `scanf("%s", ...)` + - `safe_input_demo.c` -> bounded input demo using `fgets(...)` + - `stack_layout_demo.c` -> prints stack addresses for local values and a parameter + - `overflow_behavior_demo.c` -> shows undefined behavior risk after oversized input + - `control_flow_simulation.c` -> safe function-pointer reassignment demo +- `docs/` -> guided learning material and reference notes + - `demo.md` -> quick walkthrough and sample outputs + - `gdb-guide.md` -> debugging workflow for the active binaries + - `lab-exercises.md` -> step-by-step beginner exercises + - `memory-layout.md` -> stack and buffer basics + - `protections.md` -> ASLR, NX, and stack canaries overview + - `advanced-concepts.md` -> conceptual theory only + - `images/` -> screenshots and supporting visual assets +- `archive/` -> deprecated placeholder files retained for compatibility + - `main.c` -> inactive placeholder + - `stack_behavior_demo.c` -> inactive placeholder +- `.github/workflows/` -> CI workflow that compiles the demo programs +- `Makefile` -> build, verify, and clean targets +- `README.md` -> project overview and setup guide + +## Setup & Installation + +Clone the repository: ```bash -make +git clone https://github.com/urvalkheni/exploit-lab-cpp.git +cd exploit-lab-cpp ``` -## Manual Compilation (No Make) - -If `make` is not available, compile each program directly: +Install the required tools: -```bash -gcc src/vuln_buffer_overflow.c -o vuln_buffer_overflow -gcc src/safe_input_demo.c -o safe_input_demo -gcc src/stack_layout_demo.c -o stack_layout_demo -gcc src/overflow_behavior_demo.c -o overflow_behavior_demo -gcc src/control_flow_simulation.c -o control_flow_simulation -``` +- Linux: `gcc`, `make`, and optionally `gdb` +- Windows: MinGW or another GCC-compatible toolchain, plus `make` -## Verification (Quick Check) - -Run this to verify setup in seconds: +Build all demos: ```bash make -./vuln_buffer_overflow -``` - -Windows (MinGW): - -```powershell -make -.\vuln_buffer_overflow.exe ``` -## Quick Sanity Check - -1. Safe demo: - - Run `./safe_input_demo` - - Expected: input works normally with no warnings. -2. Overflow demo: - - Run `./overflow_behavior_demo` with long input. - - Expected: warning appears and behavior may change. -3. Control flow demo: - - Run `./control_flow_simulation`. - - Expected: output changes before/after pointer reassignment. - -## Run Commands - -Linux/macOS: +Run a demo: ```bash -./vuln_buffer_overflow ./safe_input_demo -./stack_layout_demo -./overflow_behavior_demo -./control_flow_simulation ``` Windows (MinGW): ```powershell -.\vuln_buffer_overflow.exe .\safe_input_demo.exe -.\stack_layout_demo.exe -.\overflow_behavior_demo.exe -.\control_flow_simulation.exe ``` -## Learning Path - -1. Start with `vuln_buffer_overflow` (unsafe behavior). -2. Compare with `safe_input_demo` (bounded input). -3. Run `stack_layout_demo` and observe address relationships. -4. Run `overflow_behavior_demo` with long input and observe effects. -5. Run `control_flow_simulation` to understand conceptual redirection. -6. Use GDB to inspect variables, stack state, and registers. - -## Lab Exercises - -Step-by-step exercises: -- [docs/lab-exercises.md](docs/lab-exercises.md) - -## Demo Guide +If you want to verify compilation without using the default build target, run: -Commands + sample outputs: -- [docs/demo.md](docs/demo.md) - -## Protection Mechanisms - -Beginner explanation of ASLR, NX bit, and stack canaries: -- [docs/protections.md](docs/protections.md) - -## Advanced Concepts (Theory Only) - -Conceptual overview of stack smashing, shellcode, and ROP: -- [docs/advanced-concepts.md](docs/advanced-concepts.md) +```bash +make verify +``` -## Debugging Guide +## Available Demos -Current GDB workflow for modular binaries: -- [docs/gdb-guide.md](docs/gdb-guide.md) +- `vuln_buffer_overflow` -> unsafe input behavior demonstration +- `safe_input_demo` -> bounded input demonstration +- `stack_layout_demo` -> runtime stack address observation +- `overflow_behavior_demo` -> overflow effect observation with a warning +- `control_flow_simulation` -> conceptual control-flow redirection via a function pointer -## Demo Assets +## Helpful Docs -Screenshots and visual captures: -- `docs/images/` -- `docs/images/gdb-session.png` -- `docs/images/overflow-output.png` -- `docs/images/control-flow.png` +- [Demo guide](docs/demo.md) +- [Lab exercises](docs/lab-exercises.md) +- [GDB guide](docs/gdb-guide.md) +- [Memory layout basics](docs/memory-layout.md) +- [Runtime protections](docs/protections.md) +- [Advanced concepts](docs/advanced-concepts.md) ## Safety and Scope -- Educational use only. -- Focused on understanding behavior and prevention. -- No exploit payloads, no exploitation walkthroughs. - -## Disclaimer +This project is educational and defensive in scope. It does not include exploit payloads or a real exploitation walkthrough. The focus is on understanding memory behavior, debugging, and safer programming patterns. -Do not test on systems you do not own or have explicit permission to analyze. +Do not run these experiments on systems you do not own or have explicit permission to analyze.