feat: adicionar 4 exemplos OWASP (sql-injection, xss, ssrf, path-traversal)

Cada exemplo inclui:
- vulnerable.py: código com a vulnerabilidade e comentários explicando o risco
- hardened.py: versão segura com comentários explicando a correção
- README.md: contexto do ataque, fix e como ShieldCode previne em Claude Code

Cenários cobertos: SQL Injection, XSS, SSRF e Path Traversal (FastAPI/Python)

Author: nikolasdehor

examples/path-traversal/README.md

@@ -0,0 +1,35 @@
+# Path Traversal Scenario
+
+This FastAPI example downloads invoice PDFs from a storage directory.
+
+## Attack
+
+The vulnerable endpoint accepts:
+
+```text
+GET /invoices/download?filename=../../.env
+```
+
+`vulnerable.py` joins the raw filename with the invoice directory. `../`
+segments can escape the intended folder and read application secrets or system
+files if the process has permission.
+
+## Fix
+
+`hardened.py` applies ShieldCode's file security rules:
+
+- Validate filenames with an allowlist regex.
+- Resolve the final path before reading it.
+- Verify the resolved path stays inside the allowed base directory.
+- Require a regular file and return the expected PDF media type.
+
+## ShieldCode in action
+
+Prompt Claude Code after installing ShieldCode:
+
+```text
+Create a FastAPI endpoint to download invoice files by filename.
+```
+
+With ShieldCode active, Claude should reject arbitrary path input and keep all
+file access inside an explicitly approved directory.

examples/path-traversal/hardened.py

@@ -0,0 +1,34 @@
+from pathlib import Path
+import re
+
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.responses import FileResponse
+
+app = FastAPI(title="Hardened invoice download")
+
+BASE_DIR = Path("storage/invoices").resolve()
+SAFE_INVOICE_NAME = re.compile(r"^[a-zA-Z0-9_-]+\.pdf$")
+
+
+@app.get("/invoices/download")
+def download_invoice(filename: str = Query(..., min_length=5, max_length=80)):
+    # FIX: allowlist the exact filename format the endpoint supports. Path
+    # separators, hidden files, and alternate extensions are rejected up front.
+    if not SAFE_INVOICE_NAME.fullmatch(filename):
+        raise HTTPException(status_code=400, detail="Invalid invoice filename")
+
+    target = (BASE_DIR / filename).resolve()
+
+    # FIX: resolve the final path and verify it remains inside BASE_DIR before
+    # reading. This defends even if symlinks or unusual path segments appear.
+    if BASE_DIR not in target.parents:
+        raise HTTPException(status_code=400, detail="Invalid invoice path")
+
+    if not target.is_file():
+        raise HTTPException(status_code=404, detail="Invoice not found")
+
+    return FileResponse(
+        target,
+        media_type="application/pdf",
+        filename=filename,
+    )

examples/path-traversal/vulnerable.py

@@ -0,0 +1,21 @@
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.responses import FileResponse
+
+app = FastAPI(title="Vulnerable invoice download")
+
+BASE_DIR = Path("storage/invoices")
+
+
+@app.get("/invoices/download")
+def download_invoice(filename: str = Query(...)):
+    # VULNERABLE: joining untrusted input allows ../ path traversal. A request
+    # like filename=../../.env can escape storage/invoices and read server files.
+    target = BASE_DIR / filename
+
+    if not target.exists():
+        raise HTTPException(status_code=404, detail="Invoice not found")
+
+    # VULNERABLE: the response returns whatever path the attacker reached.
+    return FileResponse(target)

examples/sql-injection/README.md

@@ -0,0 +1,36 @@
+# SQL Injection Scenario
+
+This FastAPI example shows a customer search endpoint that looks normal but
+builds SQL by concatenating a query string.
+
+## Attack
+
+The vulnerable endpoint accepts:
+
+```text
+GET /customers?q=' OR '1'='1
+```
+
+Because `vulnerable.py` inserts `q` directly into the SQL string, the attacker
+can change the meaning of the query and return records they should not see.
+Verbose database errors also leak schema hints.
+
+## Fix
+
+`hardened.py` applies ShieldCode's SQL injection rules:
+
+- Validate input length with FastAPI `Query`.
+- Use parameterized placeholders instead of string formatting.
+- Escape `%`, `_`, and `\` before using input in `LIKE`.
+- Log internal failures without returning raw database errors.
+
+## ShieldCode in action
+
+Prompt Claude Code after installing ShieldCode:
+
+```text
+Write a FastAPI endpoint to search customers by name or email.
+```
+
+With ShieldCode active, Claude should avoid f-strings in SQL and produce the
+parameterized pattern shown in `hardened.py`.

examples/sql-injection/hardened.py

@@ -0,0 +1,45 @@
+from fastapi import FastAPI, HTTPException, Query
+import logging
+import sqlite3
+
+app = FastAPI(title="Hardened SQL search")
+logger = logging.getLogger("shieldcode.sql")
+
+
+def get_connection() -> sqlite3.Connection:
+    connection = sqlite3.connect("shop.db")
+    connection.row_factory = sqlite3.Row
+    return connection
+
+
+def escape_like(value: str) -> str:
+    # FIX: escape LIKE wildcards so user input stays data, not pattern control.
+    return value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+
+
+@app.get("/customers")
+def search_customers(q: str = Query(..., min_length=1, max_length=80)):
+    connection = get_connection()
+    pattern = f"%{escape_like(q)}%"
+
+    # FIX: parameterized placeholders keep the SQL structure fixed. The
+    # database driver sends attacker input as values, not executable SQL.
+    sql = """
+        SELECT id, email, full_name
+        FROM customers
+        WHERE full_name LIKE ? ESCAPE '\\'
+           OR email LIKE ? ESCAPE '\\'
+        ORDER BY full_name
+    """
+
+    try:
+        rows = connection.execute(sql, (pattern, pattern)).fetchall()
+    except sqlite3.DatabaseError as exc:
+        # FIX: log the internal error server-side, return a generic client
+        # message, and avoid leaking table or column names.
+        logger.exception("customer_search_failed")
+        raise HTTPException(status_code=500, detail="Search failed") from exc
+    finally:
+        connection.close()
+
+    return {"results": [dict(row) for row in rows]}

examples/sql-injection/vulnerable.py

@@ -0,0 +1,35 @@
+from fastapi import FastAPI, HTTPException, Query
+import sqlite3
+
+app = FastAPI(title="Vulnerable SQL search")
+
+
+def get_connection() -> sqlite3.Connection:
+    connection = sqlite3.connect("shop.db")
+    connection.row_factory = sqlite3.Row
+    return connection
+
+
+@app.get("/customers")
+def search_customers(q: str = Query(..., min_length=1)):
+    connection = get_connection()
+
+    # VULNERABLE: user-controlled input is interpolated directly into SQL.
+    # An attacker can send q=' OR '1'='1 to turn the WHERE clause into a
+    # tautology, or append UNION queries to read unrelated tables.
+    sql = (
+        "SELECT id, email, full_name FROM customers "
+        f"WHERE full_name LIKE '%{q}%' OR email LIKE '%{q}%' "
+        "ORDER BY full_name"
+    )
+
+    try:
+        rows = connection.execute(sql).fetchall()
+    except sqlite3.DatabaseError as exc:
+        # VULNERABLE: returning raw database errors can reveal schema details
+        # that make injection attacks easier to refine.
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+    finally:
+        connection.close()
+
+    return {"results": [dict(row) for row in rows]}

examples/ssrf/README.md

@@ -0,0 +1,36 @@
+# SSRF Scenario
+
+This FastAPI example tests whether a webhook URL is reachable.
+
+## Attack
+
+The vulnerable endpoint accepts:
+
+```text
+GET /webhook/test?url=http://169.254.169.254/latest/meta-data/
+```
+
+Because `vulnerable.py` fetches any URL supplied by the caller, an attacker can
+make the server connect to cloud metadata services, localhost admin ports, or
+private network hosts that are not reachable from the public internet.
+
+## Fix
+
+`hardened.py` applies ShieldCode's SSRF controls:
+
+- Require `https`.
+- Allow only known webhook hosts.
+- Reject obvious literal private, loopback, and link-local IPs.
+- Disable redirects to avoid allowlist bypasses.
+- Return minimal reachability metadata instead of proxying response bodies.
+
+## ShieldCode in action
+
+Prompt Claude Code after installing ShieldCode:
+
+```text
+Build a FastAPI endpoint that tests whether a webhook URL is reachable.
+```
+
+With ShieldCode active, Claude should ask for or define an allowlist and avoid
+fetching arbitrary user-provided URLs.

examples/ssrf/hardened.py

@@ -0,0 +1,49 @@
+from ipaddress import ip_address
+from urllib.parse import urlparse
+
+from fastapi import FastAPI, HTTPException, Query
+import httpx
+
+app = FastAPI(title="Hardened webhook tester")
+
+ALLOWED_WEBHOOK_HOSTS = {"hooks.stripe.com", "api.github.com", "discord.com"}
+
+
+def validate_webhook_url(url: str) -> str:
+    parsed = urlparse(url)
+
+    # FIX: allow only HTTPS and an explicit host allowlist. This prevents users
+    # from turning the API into a proxy for arbitrary internal services.
+    if parsed.scheme != "https":
+        raise HTTPException(status_code=400, detail="Webhook URL must use HTTPS")
+    if parsed.hostname not in ALLOWED_WEBHOOK_HOSTS:
+        raise HTTPException(status_code=400, detail="Webhook host is not allowed")
+
+    # FIX: reject literal private, loopback, and link-local IP addresses. Host
+    # allowlists are still the main control; this blocks obvious bypass attempts.
+    try:
+        host_ip = ip_address(parsed.hostname)
+    except ValueError:
+        return url
+
+    if host_ip.is_private or host_ip.is_loopback or host_ip.is_link_local:
+        raise HTTPException(status_code=400, detail="Webhook host is not allowed")
+    return url
+
+
+@app.get("/webhook/test")
+async def test_webhook(url: str = Query(..., max_length=300)):
+    safe_url = validate_webhook_url(url)
+
+    try:
+        async with httpx.AsyncClient(
+            timeout=httpx.Timeout(3.0),
+            follow_redirects=False,
+        ) as client:
+            response = await client.get(safe_url)
+    except httpx.HTTPError as exc:
+        raise HTTPException(status_code=502, detail="Webhook test failed") from exc
+
+    # FIX: return only minimal metadata. Do not proxy response bodies or headers
+    # from third-party systems back to the caller.
+    return {"status_code": response.status_code, "reachable": response.is_success}

examples/ssrf/vulnerable.py

@@ -0,0 +1,24 @@
+from fastapi import FastAPI, HTTPException, Query
+import httpx
+
+app = FastAPI(title="Vulnerable webhook tester")
+
+
+@app.get("/webhook/test")
+async def test_webhook(url: str = Query(...)):
+    # VULNERABLE: the server fetches an arbitrary user-supplied URL. Attackers
+    # can target internal services such as http://169.254.169.254/latest/meta-data
+    # or http://localhost:8000/admin from the server's network position.
+    try:
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            response = await client.get(url)
+    except httpx.HTTPError as exc:
+        raise HTTPException(status_code=502, detail=str(exc)) from exc
+
+    # VULNERABLE: reflecting status and body from internal services can expose
+    # secrets, metadata, or private admin responses.
+    return {
+        "status_code": response.status_code,
+        "headers": dict(response.headers),
+        "body": response.text[:2000],
+    }

examples/xss/README.md

@@ -0,0 +1,34 @@
+# Cross-Site Scripting Scenario
+
+This FastAPI example renders a comment preview from submitted form fields.
+
+## Attack
+
+An attacker posts a comment such as:
+
+```html
+<img src=x onerror="fetch('/api/session').then(r=>r.text()).then(alert)">
+```
+
+`vulnerable.py` inserts that string directly into an HTML response. The browser
+parses it as markup and runs the event handler for any user who previews it.
+
+## Fix
+
+`hardened.py` applies ShieldCode's XSS rules:
+
+- Escape user-controlled output with `html.escape`.
+- Keep untrusted content as text, not markup.
+- Add a restrictive Content Security Policy.
+- Send defensive browser headers.
+
+## ShieldCode in action
+
+Prompt Claude Code after installing ShieldCode:
+
+```text
+Create a FastAPI route that previews a submitted comment as HTML.
+```
+
+With ShieldCode active, Claude should treat every form value as untrusted and
+escape it before returning `HTMLResponse`.