diff --git a/README.md b/README.md index 94be9f51..d890b62a 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,15 @@ know more about crAPI, please check [crAPI's overview][overview]. ## QuickStart Guide +### Application Workflow (Happy Path) + +After setting up crAPI, it is recommended to follow the intended user workflow +to understand how the application is supposed to work before attempting any +security challenges. + +-[Application Workflow (Happy Path)](docs/happy-path.md) + + ### Docker and docker compose You'll need to have Docker and docker compose installed and running on your host system. Also, the version of docker compose should be `1.27.0` or above. Check your docker compose version using: @@ -29,14 +38,10 @@ You can use prebuilt images generated by our CI workflow by downloading the dock - Linux Machine ``` - curl -o /tmp/crapi.zip https://github.com/OWASP/crAPI/archive/refs/heads/main.zip - + curl -L -o /tmp/crapi.zip https://github.com/OWASP/crAPI/archive/refs/heads/main.zip unzip /tmp/crapi.zip - cd crAPI-main/deploy/docker - docker compose pull - docker compose -f docker-compose.yml --compatibility up -d ``` @@ -51,14 +56,10 @@ You can use prebuilt images generated by our CI workflow by downloading the dock - Windows Machine ``` - curl.exe -o crapi.zip https://github.com/OWASP/crAPI/archive/refs/heads/main.zip - + curl.exe -L -o crapi.zip https://github.com/OWASP/crAPI/archive/refs/heads/main.zip tar -xf .\crapi.zip - cd crAPI-main/deploy/docker - docker compose pull - docker compose -f docker-compose.yml --compatibility up -d ``` @@ -75,14 +76,10 @@ You can use prebuilt images generated by our CI workflow by downloading the dock - Linux Machine ``` - curl -o /tmp/crapi.zip https://github.com/OWASP/crAPI/archive/refs/heads/develop.zip - - unzip /tmp/crapi.zip - + curl -L -o /tmp/crapi.zip https://github.com/OWASP/crAPI/archive/refs/heads/develop.zip + unzip /tmp/crapi.zip cd crAPI-develop/deploy/docker - docker compose pull - docker compose -f docker-compose.yml --compatibility up -d ``` @@ -97,14 +94,10 @@ You can use prebuilt images generated by our CI workflow by downloading the dock - Windows Machine ``` - curl.exe -o crapi.zip https://github.com/OWASP/crAPI/archive/refs/heads/develop.zip - + curl.exe -L -o crapi.zip https://github.com/OWASP/crAPI/archive/refs/heads/develop.zip tar -xf .\crapi.zip - cd crAPI-develop/deploy/docker - docker compose pull - docker compose -f docker-compose.yml --compatibility up -d ``` diff --git a/docs/happy-path.md b/docs/happy-path.md new file mode 100644 index 00000000..9303a1e7 --- /dev/null +++ b/docs/happy-path.md @@ -0,0 +1,124 @@ +# crAPI – Happy Path Guide + +## Purpose of This Document +crAPI (Completely Ridiculous API) is intentionally vulnerable, but new users often struggle to understand +how the application is supposed to work *before* exploring security issues. + +This document explains the **happy path** — the normal, intended workflow — so users can: +- Understand application behavior +- Navigate APIs with confidence +- Clearly differentiate expected behavior vs vulnerabilities + +--- + +## Prerequisites +Before following this guide, ensure: +- crAPI is running locally using Docker +- You can access: + - Swagger UI (OpenAPI) + - Postman collection (optional but recommended) + +--- + +## Application Overview (Conceptual) +crAPI simulates a backend system for: +- User identity and authentication +- User profiles +- Mechanic services +- Orders and notifications + +The happy path represents **how a legitimate user interacts with the system**. + +--- + +## Happy Path Workflow (High Level) + +1. User signs up +2. User logs in +3. User accesses their profile +4. User interacts with available APIs as intended +5. System responds with valid data and permissions + +--- + +## Step-by-Step Happy Path + +### 1. User Registration +**Goal:** Create a new user account + +- Endpoint: `/identity/api/auth/signup` +- Action: + - Provide email, username, and password +- Expected Result: + - Successful registration confirmation + +This step establishes a valid user identity in the system. + +--- + +### 2. User Login +**Goal:** Authenticate and obtain an access token + +- Example endpoint: `/identity/api/auth/signup` +- Action: + - Login using registered credentials +- Expected Result: + - Access token returned + +This token is required for all authenticated API calls. + +--- + +### 3. Access User Profile +**Goal:** Verify authenticated access + +- Example endpoint: `/identity/api/auth/signup` +- Action: + - Include access token in Authorization header +- Expected Result: + - User’s own profile data is returned + +This confirms authentication and authorization are working as intended. + +--- + +### 4. Explore Available APIs +**Goal:** Understand normal system behavior + +- Browse Swagger UI to view: + - User APIs + - Mechanic APIs + - Order-related APIs +- Execute read-only or permitted actions + +This step helps users recognize **expected responses** and permissions. + +--- + +### 5. Normal Application Usage +**Goal:** Follow intended business logic + +- Create or view resources where permitted +- Receive appropriate success or error responses +- Observe correct access controls + +At this stage, users fully understand the baseline system behavior. + +--- + +## Why This Matters +Understanding the happy path allows users to: +- Identify where behavior deviates from expectations +- Recognize insecure authorization or validation +- Learn API security concepts more effectively + +This guide should be followed **before attempting any challenges or exploitation**. + +--- + +## Next Steps +Once the happy path is clear, users can proceed to: +- `docs/challenges.md` +- `docs/challengeSolutions.md` + +to explore vulnerabilities intentionally built into crAPI. diff --git a/docs/setup.md b/docs/setup.md index d9fd2ec2..533b6309 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -23,14 +23,10 @@ You can use prebuilt images generated by our CI workflow by downloading the dock - Linux Machine ``` - curl -o /tmp/crapi.zip https://github.com/OWASP/crAPI/archive/refs/heads/main.zip - + curl -L -o /tmp/crapi.zip https://github.com/OWASP/crAPI/archive/refs/heads/main.zip unzip /tmp/crapi.zip - cd crAPI-main/deploy/docker - docker compose pull - docker compose -f docker-compose.yml --compatibility up -d ``` @@ -45,14 +41,10 @@ You can use prebuilt images generated by our CI workflow by downloading the dock - Windows Machine ``` - curl.exe -o crapi.zip https://github.com/OWASP/crAPI/archive/refs/heads/main.zip - + curl.exe -L -o crapi.zip https://github.com/OWASP/crAPI/archive/refs/heads/main.zip tar -xf .\crapi.zip - cd crAPI-main/deploy/docker - docker compose pull - docker compose -f docker-compose.yml --compatibility up -d ``` @@ -64,19 +56,15 @@ You can use prebuilt images generated by our CI workflow by downloading the dock LISTEN_IP="0.0.0.0" docker compose -f docker-compose.yml --compatibility up -d ``` - - To use the latest development version + - To use the latest development version - Linux Machine ``` - curl -o /tmp/crapi.zip https://github.com/OWASP/crAPI/archive/refs/heads/develop.zip - + curl -L -o /tmp/crapi.zip https://github.com/OWASP/crAPI/archive/refs/heads/develop.zip unzip /tmp/crapi.zip - cd crAPI-develop/deploy/docker - docker compose pull - docker compose -f docker-compose.yml --compatibility up -d ``` @@ -91,14 +79,10 @@ You can use prebuilt images generated by our CI workflow by downloading the dock - Windows Machine ``` - curl.exe -o crapi.zip https://github.com/OWASP/crAPI/archive/refs/heads/develop.zip - + curl.exe -L -o crapi.zip https://github.com/OWASP/crAPI/archive/refs/heads/develop.zip tar -xf .\crapi.zip - cd crAPI-develop/deploy/docker - docker compose pull - docker compose -f docker-compose.yml --compatibility up -d ```