Project 8: Linux /proc + ptrace Memory Observer

Build a simple observer that reads a target value from a process using /proc and ptrace permissions.

Quick Reference

Attribute Value
Difficulty Level 4
Time Estimate 2-3 weeks
Main Programming Language C or Rust
Alternative Programming Languages Python (bindings)
Coolness Level Level 4
Business Potential Level 1
Prerequisites P07 watchpoints
Key Topics /proc, ptrace, permissions

1. Learning Objectives

By completing this project, you will:

  1. Understand Linux process memory maps via /proc.
  2. Use ptrace permissions to read memory safely.
  3. Log HP values at fixed intervals.

2. All Theory Needed (Per-Concept Breakdown)

Linux Process Introspection with /proc and ptrace

  • Fundamentals Linux exposes process information through the /proc filesystem. Files like /proc/<pid>/maps describe memory regions, while /proc/<pid>/mem provides raw memory access. Access to these resources is restricted and typically governed by ptrace permissions. A memory observer is essentially a controlled, authorized read of process memory.

  • Deep Dive into the concept The /proc filesystem is a live view into kernel-managed data structures. The maps file lists virtual memory regions, their permissions, and their backing files. This allows you to identify which regions are likely to contain heap objects or the main executable. The mem file provides a raw interface to process memory, but it is protected: Linux enforces that only a process with ptrace permission can read or write another process’s memory. This is part of the kernel’s security model.

    ptrace is the underlying mechanism for debuggers and tracers. When a tracer attaches, the kernel stops the target and allows the tracer to inspect registers and memory. The Yama security module often restricts ptrace to same-user processes by default, which is why you must run your lab in a safe, controlled environment. If you cannot attach, your observer will fail. Documenting these permissions is part of the project’s deliverable.

    The practical workflow is: identify the correct region in /proc/<pid>/maps, compute the address you want to read (usually from a pointer chain discovered earlier), then read that address from /proc/<pid>/mem. Because direct writes are dangerous, this project focuses on reading and logging values only. The observer should sample at fixed intervals to produce a deterministic timeline of HP changes.

    It is important to understand that memory reads can be inconsistent if the process changes state while you read. For this reason, you may choose to pause the process while reading or sample frequently and tolerate minor inconsistencies. In a deterministic sandbox, this is simpler: state changes are predictable, and you can correlate logs with tick counts. The result is a tool that mirrors how memory scanners operate at a low level but stays within ethical and legal boundaries.

  • How this fit on projects This concept builds on scanning and watchpoint work, and it feeds the Capstone cross-platform lab.

  • Definitions & key terms
    • /proc: Pseudo-filesystem exposing process state.
    • maps: Memory region list with permissions.
    • mem: Raw process memory file.
    • ptrace: Kernel mechanism for process tracing.
  • Mental model diagram ``` Observer Flow

[Observer] –ptrace–> [Target] | | +– /proc//maps +-- /proc//mem


- **How it works (step-by-step)**
  1. Identify target PID.
  2. Read `/proc/<pid>/maps` to locate regions.
  3. Ensure ptrace permission to read memory.
  4. Read the HP address from `/proc/<pid>/mem`.
  5. Log values at fixed intervals.

- **Minimal concrete example**

T=00.0s HP=100 T=02.0s HP=95


- **Common misconceptions**
  - “/proc is unrestricted.” (It is permission-controlled.)
  - “Reading memory is harmless.” (It can still violate privacy or rules.)

- **Check-your-understanding questions**
  1. Why does Linux restrict ptrace by default?
  2. What does `/proc/<pid>/maps` tell you?
  3. Why is sampling important for consistent logs?

- **Check-your-understanding answers**
  1. To prevent unauthorized memory inspection.
  2. It lists regions, permissions, and backing files.
  3. It gives a timeline and reduces ambiguity.

- **Real-world applications**
  - Process monitoring and debugging.
  - Security instrumentation (authorized).

- **Where you’ll apply it**
  - This project’s §5.4 and §6.2.
  - Also used in: P10-cross-platform-game-hacking-lab.md.

- **References**
  - `ptrace(2)` man page.
  - `proc_pid_maps(5)` and `proc_pid_mem(5)`.

- **Key insights**
  /proc is powerful but tightly controlled; permissions are part of the design.

- **Summary**
  Linux process introspection requires both technical understanding and ethical discipline.

- **Homework/Exercises to practice the concept**
  1. Identify the heap region in a maps file.
  2. Explain how ptrace permissions are enforced.

- **Solutions to the homework/exercises**
  1. Look for the region labeled `[heap]`.
  2. The kernel checks ownership and security policies.

---

## 3. Project Specification

### 3.1 What You Will Build

A small observer that logs HP values from your sandbox process by reading `/proc/<pid>/mem`. The observer must document required permissions and produce a deterministic log.

### 3.2 Functional Requirements

1. Identify PID of sandbox.
2. Read `/proc/<pid>/maps` to locate memory region.
3. Read HP value at a known address.
4. Log values at fixed intervals.

### 3.3 Non-Functional Requirements

- **Performance**: Sampling overhead under 5%.
- **Reliability**: Log aligns with sandbox tick log.
- **Usability**: Clear instructions for permissions.

### 3.4 Example Usage / Output

T=00.0s HP=100 T=02.0s HP=95


### 3.5 Data Formats / Schemas / Protocols

- **Observer log**: timestamp -> HP value.

### 3.6 Edge Cases

- Permission denied errors.
- Address invalid after restart.

### 3.7 Real World Outcome

#### 3.7.1 How to Run (Copy/Paste)

1. Launch sandbox.
2. Run observer with target PID.

#### 3.7.2 Golden Path Demo (Deterministic)

Observer log matches sandbox log at tick 10.

#### 3.7.3 Failure Demo

Observer fails with permission denied; document required settings.

---

## 4. Solution Architecture

### 4.1 High-Level Design

[PID] -> [/proc/maps] -> [Address] -> [/proc/mem] -> [Log]


### 4.2 Key Components

| Component | Responsibility | Key Decisions |
|-----------|----------------|---------------|
| Maps Parser | Locate regions | Heap focus |
| Reader | Read address | Fixed interval |

### 4.3 Data Structures (No Full Code)

- **Region record**: start, end, permissions, path.

### 4.4 Algorithm Overview

**Key Algorithm: Memory Sampling**
1. Locate region.
2. Read address.
3. Log value.

**Complexity Analysis**
- Time: O(n) region scan + O(samples).
- Space: O(n) region list.

---

## 5. Implementation Guide

### 5.1 Development Environment Setup

- Linux VM with permissions to attach to own processes.

### 5.2 Project Structure

observer/ ├── logs/ └── notes.md


### 5.3 The Core Question You're Answering

> "How do scanners read memory at the OS level on Linux?"

### 5.4 Concepts You Must Understand First

- /proc maps format
- ptrace permissions

### 5.5 Questions to Guide Your Design

1. How will you avoid scanning unnecessary regions?
2. How will you handle permission errors?

### 5.6 Thinking Exercise

Sketch the path from PID to memory read and list required permissions.

### 5.7 The Interview Questions They'll Ask

1. "What is /proc and why is it useful?"
2. "How does ptrace restrict access?"
3. "Why is reading /proc/pid/mem sensitive?"

### 5.8 Hints in Layers

**Hint 1:** Start with maps and find heap.
**Hint 2:** Use a known HP address.
**Hint 3:** Sample on a fixed interval.
**Hint 4:** Document all permission steps.

### 5.9 Books That Will Help

| Topic | Book | Chapter |
|-------|------|---------|
| Process memory | CSAPP | Ch. 9 |

### 5.10 Implementation Phases

#### Phase 1: Maps Parsing (4 hours)
- Extract region list.

**Checkpoint:** Heap region identified.

#### Phase 2: Memory Read (6 hours)
- Read HP address and log.

**Checkpoint:** HP appears in log.

#### Phase 3: Permission Handling (4 hours)
- Document required ptrace settings.

**Checkpoint:** Permissions documented.

### 5.11 Key Implementation Decisions

| Decision | Options | Recommendation | Rationale |
|----------|---------|----------------|-----------|
| Sampling | Continuous vs fixed | Fixed | Deterministic logs |

---

## 6. Testing Strategy

### 6.1 Test Categories

| Category | Purpose | Examples |
|----------|---------|----------|
| Accuracy | Value match | Compare logs |
| Permissions | Attach allowed | Same-user process |

### 6.2 Critical Test Cases

1. Observer log matches sandbox log at tick 10.
2. Permission denied case documented.

### 6.3 Test Data

Expected HP at tick 10: 95 ```

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

Pitfall Symptom Solution
Wrong region Value incorrect Re-check maps
Permission denied No read Use same user + lab VM

7.2 Debugging Strategies

  • Validate address via GDB first.
  • Use deterministic timing to align logs.

8. Extensions & Challenges

8.1 Beginner Extensions

  • Log ammo instead of HP.

8.2 Intermediate Extensions

  • Log two addresses simultaneously.

8.3 Advanced Extensions

  • Build a pointer chain resolver in the observer.

9. Real-World Connections

9.1 Industry Applications

  • Performance monitoring and debugging.
  • Sandbox from P01.

9.3 Interview Relevance

  • Shows understanding of OS introspection and permissions.

10. Resources

10.1 Essential Reading

  • ptrace(2) man page
  • proc_pid_maps(5), proc_pid_mem(5)

10.2 Video Resources

  • Linux debugging tutorials.

10.3 Tools & Documentation

  • GDB docs, man7.org.
  • P07-linux-gdb-watchpoints.md
  • P10-cross-platform-game-hacking-lab.md

11. Self-Assessment Checklist

11.1 Understanding

  • I can explain /proc maps and mem.
  • I can describe ptrace permissions.

11.2 Implementation

  • Observer logs HP correctly.
  • Permission requirements documented.

11.3 Growth

  • I can adapt observer to another variable.

12. Submission / Completion Criteria

Minimum Viable Completion:

  • Observer reads HP and logs values.

Full Completion:

  • Logs aligned with sandbox ticks and permissions documented.

Excellence (Going Above & Beyond):

  • Pointer chain resolution added to observer.