openapi: 3.0.0
info:
  title: Mi API de Startup
  version: 1.0.0
  description: API para gestión de usuarios y productos

servers:
  - url: https://api-staging.miapp.com
    description: Ambiente de staging

paths:
  /api/v1/users:
    get:
      summary: Lista usuarios
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Lista de usuarios
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          description: No autorizado

  /api/v1/users/{userId}:
    get:
      summary: Obtiene usuario por ID
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Usuario encontrado
        '404':
          description: Usuario no encontrado

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        role:
          type: string
          enum: [user, admin, moderator]
        createdAt:
          type: string
          format: date-time

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

import swaggerJsdoc from 'swagger-jsdoc'
import swaggerUi from 'swagger-ui-express'

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Mi API',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'], // Ruta a tus archivos de rutas
}

const specs = swaggerJsdoc(options)
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs))

from fastapi import FastAPI

app = FastAPI(
    title="Mi API",
    description="API para pentesting",
    version="1.0.0"
)

@app.get("/users/{user_id}")
async def read_user(user_id: str):
    """
    Obtiene información de un usuario específico.

    - **user_id**: UUID del usuario
    """
    return {"user_id": user_id}

# FastAPI genera automáticamente documentación en /docs

# .env.staging
NODE_ENV=staging
API_URL=https://api-staging.miapp.com
DATABASE_URL=postgresql://staging_db
REDIS_URL=redis://staging_cache

# Datos de prueba
ENABLE_TEST_DATA=true
ALLOW_DANGEROUS_OPERATIONS=true

# Rate limiting relajado para pentest
RATE_LIMIT_ENABLED=false

# Logging extendido
LOG_LEVEL=debug
LOG_ALL_REQUESTS=true

{
  "test_accounts": [
    {
      "role": "admin",
      "email": "admin@pentest.local",
      "password": "Test123!Admin",
      "description": "Cuenta con todos los privilegios"
    },
    {
      "role": "moderator",
      "email": "moderator@pentest.local",
      "password": "Test123!Mod",
      "description": "Cuenta con privilegios moderados"
    },
    {
      "role": "user",
      "email": "user@pentest.local",
      "password": "Test123!User",
      "description": "Usuario estándar"
    },
    {
      "role": "limited_user",
      "email": "limited@pentest.local",
      "password": "Test123!Limited",
      "description": "Usuario con cuenta de prueba gratuita"
    },
    {
      "role": "suspended_user",
      "email": "suspended@pentest.local",
      "password": "Test123!Suspended",
      "description": "Usuario suspendido/bloqueado"
    }
  ]
}

// seed-pentest-data.js
import { faker } from '@faker-js/faker'
import db from './database.js'

async function seedPentestData() {
  // Crear usuarios de prueba
  const testUsers = [
    { email: 'admin@pentest.local', role: 'admin' },
    { email: 'user@pentest.local', role: 'user' }
  ]

  for (const userData of testUsers) {
    await db.users.create({
      ...userData,
      password: await hashPassword('Test123!'),
      firstName: faker.person.firstName(),
      lastName: faker.person.lastName(),
      createdAt: faker.date.past()
    })
  }

  // Crear datos relacionales
  await createTestProducts(50)
  await createTestOrders(100)
  await createTestComments(200)

  console.log('✅ Datos de pentest creados')
}

seedPentestData()

## Autenticación

### Método: JWT Bearer Token

#### Obtener Token:
POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Respuesta:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "refresh_token_here",
  "expiresIn": 3600
}

#### Usar Token:
GET /api/v1/protected-endpoint
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

### Roles y Permisos

| Rol | Permisos |
|-----|----------|
| admin | Acceso total a todos los endpoints |
| moderator | Leer/escribir contenido, no puede gestionar usuarios |
| user | Leer su propio contenido, escribir posts |
| guest | Solo lectura de contenido público |

### Tokens de Larga Duración para Pentest

Para facilitar el pentest, genera tokens con mayor duración:

Token Admin (válido 7 días):
`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbkBwZW50ZXN0LmxvY2FsIiwicm9sZSI6ImFkbWluIiwiZXhwIjoxNzM1OTk5OTk5fQ...`

Token User (válido 7 días):
`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyQHBlbnRlc3QubG9jYWwiLCJyb2xlIjoidXNlciIsImV4cCI6MTczNTk5OTk5OX0...`

## Alcance del Pentest de API

### EN SCOPE (Permitido)

#### Endpoints a Probar:
- ✅ Todos los endpoints en /api/v1/*
- ✅ Autenticación y autorización
- ✅ Endpoints de administración (/api/v1/admin/*)
- ✅ WebSockets en /ws/*
- ✅ GraphQL endpoint (/graphql)

#### Tipos de Pruebas:
- ✅ Inyección (SQL, NoSQL, Command)
- ✅ Broken Authentication
- ✅ Broken Access Control (IDOR, escalación de privilegios)
- ✅ SSRF
- ✅ XXE
- ✅ Deserialización insegura
- ✅ Rate limiting bypass
- ✅ Business logic flaws

#### Acciones Permitidas:
- ✅ Crear/modificar/eliminar datos de prueba
- ✅ Intentos de autenticación ilimitados
- ✅ Fuzzing de endpoints
- ✅ Ataques de fuerza bruta contra cuentas de prueba

### FUERA DE SCOPE (NO Permitido)

- ❌ Ataques de denegación de servicio (DoS/DDoS)
- ❌ Ingeniería social
- ❌ Phishing
- ❌ Ataques físicos
- ❌ Modificar datos de usuarios reales
- ❌ Acceder a ambientes de producción
- ❌ Compartir credenciales con terceros

### Datos Sensibles

⚠️ **Datos que NO deben exfiltrarse:**
- Ningún dato de clientes reales (si por error están en staging)
- Credenciales de servicios de terceros
- Claves API de producción

## Contactos del Pentest

### Equipo Técnico
- **Lead Developer**: Juan Pérez
  - Email: juan@miapp.com
  - Slack: @juan
  - Teléfono: +57 300 123 4567
  - Disponibilidad: Lun-Vie 9am-6pm COT

- **DevOps**: María García
  - Email: maria@miapp.com
  - Slack: @maria
  - Emergencias: +57 300 765 4321

### Escalación de Incidentes

Si se encuentra una vulnerabilidad CRÍTICA:
1. Notificar inmediatamente por Slack (#security-alerts)
2. Enviar email a security@miapp.com
3. Si no hay respuesta en 2 horas, llamar a número de emergencias

### Reportes de Progreso

- Daily standup: Todos los días 10am COT
- Canal Slack: #pentest-proyecto
- Updates escritos: Al final de cada día

// logging-config.js para pentest
export const pentestLoggingConfig = {
  level: 'debug',

  // Registrar todas las requests
  logAllRequests: true,

  // Logs específicos de seguridad
  security: {
    failedLogins: true,
    authorizationFailures: true,
    suspiciousPatterns: true,
    rateLimitHits: true,
    invalidTokens: true
  },

  // Formato detallado
  format: 'json',

  // Incluir metadata útil
  metadata: {
    ip: true,
    userAgent: true,
    requestId: true,
    userId: true,
    endpoint: true,
    method: true,
    responseTime: true,
    statusCode: true
  }
}

# Monitorear logs en tiempo real
tail -f /var/log/api/access.log | grep "pentest"

# Filtrar errores
tail -f /var/log/api/error.log | grep -E "5xx|ERROR|CRITICAL"

## Plan de Remediación - Vulnerabilidades API

### Críticas (0)
✅ Ninguna encontrada

### Altas (2)

#### 1. IDOR en /api/v1/orders/{orderId}
- **Descripción**: Cualquier usuario puede acceder a órdenes de otros usuarios
- **Responsable**: Juan Pérez
- **Fecha límite**: 2025-12-10
- **Status**: En progreso
- **PR**: #234

#### 2. Mass Assignment en /api/v1/users/profile
- **Descripción**: Se puede modificar el rol de usuario vía request
- **Responsable**: María García
- **Fecha límite**: 2025-12-12
- **Status**: Pendiente

### Medias (5)
[...]

### Bajas (8)
[...]