# Aegis - Plan de Tareas — Plataforma de Cobertura MITRE ATT&CK

> **Instrucciones de uso**: Cada tarea (T-XXX) es una unidad de trabajo independiente que debe
> resultar en un commit. Están ordenadas secuencialmente — cada tarea puede depender de las
> anteriores pero nunca de las posteriores. Cada tarea incluye una sección de validación:
> no hagas commit hasta que todos los checks pasen.

---

## FASE 0 — Infraestructura y Scaffolding

### T-001: Inicializar proyecto y Docker Compose base

**Objetivo:** Tener el entorno de desarrollo levantado con todos los servicios necesarios.

**Archivos a crear:**
```
proyecto/
├── docker-compose.yml
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt
│   └── app/
│       ├── __init__.py
│       └── main.py
└── frontend/
    └── (vacío por ahora)
```

**docker-compose.yml** debe definir 3 servicios:

- **postgres**: imagen `postgres:15`, variables `POSTGRES_USER=postgres`, `POSTGRES_PASSWORD=postgres`, `POSTGRES_DB=attackdb`, puerto `5432:5432`, volumen persistente para data.
- **minio**: imagen `minio/minio`, command `server /data --console-address ":9001"`, variables `MINIO_ROOT_USER=minioadmin`, `MINIO_ROOT_PASSWORD=minioadmin`, puertos `9000:9000` y `9001:9001`.
- **backend**: build desde `./backend`, puerto `8000:8000`, variable `DATABASE_URL=postgresql://postgres:postgres@postgres:5432/attackdb`, depends_on postgres y minio. Comando: `uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload`.

**requirements.txt** inicial:
```
fastapi
uvicorn[standard]
sqlalchemy
psycopg2-binary
alembic
python-jose[cryptography]
passlib[bcrypt]
boto3
apscheduler
requests
taxii2-client
python-multipart
```

**main.py** mínimo:
```python
from fastapi import FastAPI

app = FastAPI(title="Attack Coverage Platform")

@app.get("/health")
def health():
    return {"status": "ok"}
```

**Validación:**

- [ ] `docker-compose up --build` levanta los 3 servicios sin errores
- [ ] `curl http://localhost:8000/health` → `{"status":"ok"}`
- [ ] Acceder a MinIO Console en `http://localhost:9001` (login minioadmin/minioadmin)
- [ ] `psql -h localhost -U postgres -d attackdb -c "SELECT 1"` responde correctamente

---

### T-002: Configuración y conexión a base de datos

**Objetivo:** Centralizar configuración y establecer conexión SQLAlchemy a PostgreSQL.

**Archivos a crear:**

- `backend/app/config.py`
- `backend/app/database.py`

**config.py:**

- Usar `pydantic_settings` (paquete `pydantic-settings`). Clase `Settings(BaseSettings)` con:
  - `DATABASE_URL: str` con default `postgresql://postgres:postgres@postgres:5432/attackdb`
  - `SECRET_KEY: str` con default `"change-me-in-production"`
  - `ALGORITHM: str = "HS256"`
  - `ACCESS_TOKEN_EXPIRE_MINUTES: int = 60`
  - `MINIO_ENDPOINT: str = "minio:9000"`
  - `MINIO_ACCESS_KEY: str = "minioadmin"`
  - `MINIO_SECRET_KEY: str = "minioadmin"`
  - `MINIO_BUCKET: str = "evidence"`
- Añadir `pydantic-settings` a `requirements.txt`.
- Instanciar `settings = Settings()` al final del módulo.

**database.py:**

- Crear engine con `create_engine(settings.DATABASE_URL)`
- Crear `SessionLocal` con `sessionmaker(autocommit=False, autoflush=False, bind=engine)`
- Crear `Base = declarative_base()`
- Función generadora `get_db()` que hace yield de una sesión y la cierra en el finally.

**Actualizar main.py:**

- Importar `engine` y `Base` desde database.
- Añadir al startup: `Base.metadata.create_all(bind=engine)` (temporal, luego lo reemplaza Alembic).

**Validación:**

- [ ] Backend arranca sin errores de conexión a BD
- [ ] Los logs muestran conexión establecida a PostgreSQL
- [ ] Importar `settings` desde config funciona y tiene todos los valores

---

### T-003: Inicializar Alembic para migraciones

**Objetivo:** Tener Alembic configurado y funcionando para manejar migraciones de esquema.

**Pasos:**

1. Dentro de `backend/`, ejecutar `alembic init alembic`
2. Editar `alembic/env.py`:
   - Importar `Base` desde `app.database`
   - Importar `settings` desde `app.config`
   - Setear `target_metadata = Base.metadata`
   - En la función `run_migrations_online()`, usar `settings.DATABASE_URL` como URL de conexión
3. Editar `alembic.ini`: poner `sqlalchemy.url` vacío (se overridea desde env.py)
4. Eliminar `Base.metadata.create_all(bind=engine)` de `main.py` (ya no es necesario)

**Validación:**

- [ ] `alembic revision --autogenerate -m "init"` genera un archivo de migración (vacío está bien, aún no hay modelos)
- [ ] `alembic upgrade head` se ejecuta sin errores
- [ ] `alembic current` muestra la revisión actual

---

## FASE 1 — Modelos de Datos y Migraciones

### T-004: Modelo User

**Objetivo:** Crear la tabla `users` en la BD.

**Archivo a crear:** `backend/app/models/user.py`

**Crear también** `backend/app/models/__init__.py` que importe todos los modelos (para que Alembic los detecte).

**Campos del modelo:**

| Campo           | Tipo                   | Restricciones              |
|-----------------|------------------------|----------------------------|
| id              | UUID                   | PK, default uuid4          |
| username        | String                 | unique, not null            |
| email           | String                 | nullable                   |
| hashed_password | String                 | not null                   |
| role            | String                 | not null, default "viewer"  |
| is_active       | Boolean                | default True               |
| created_at      | DateTime               | default utcnow             |
| last_login      | DateTime               | nullable                   |

**Roles posibles** (documentar como comentario): `admin`, `red_tech`, `blue_tech`, `red_lead`, `blue_lead`

**Generar migración:** `alembic revision --autogenerate -m "add_users_table"`

**Validación:**

- [ ] `alembic upgrade head` crea la tabla `users`
- [ ] Verificar con `\d users` en psql que tiene todas las columnas con los tipos correctos
- [ ] `alembic downgrade -1` elimina la tabla sin errores

---

### T-005: Modelo Technique

**Archivo a crear:** `backend/app/models/technique.py`

**Enum a crear** (en el mismo archivo o en `models/enums.py`):
```python
class TechniqueStatus(str, enum.Enum):
    not_evaluated = "not_evaluated"
    in_progress = "in_progress"
    validated = "validated"
    partial = "partial"
    not_covered = "not_covered"
    review_required = "review_required"
```

**Campos del modelo:**

| Campo              | Tipo               | Restricciones                              |
|--------------------|--------------------|--------------------------------------------|
| id                 | UUID               | PK, default uuid4                          |
| mitre_id           | String             | unique, not null (ej: "T1059.001")         |
| name               | String             | not null                                   |
| description        | Text               | nullable                                   |
| tactic             | String             | nullable                                   |
| platforms          | JSONB              | nullable, default []                       |
| mitre_version      | String             | nullable                                   |
| mitre_last_modified| DateTime           | nullable                                   |
| is_subtechnique    | Boolean            | default False                              |
| parent_mitre_id    | String             | nullable                                   |
| status_global      | Enum(TechniqueStatus) | default not_evaluated                   |
| review_required    | Boolean            | default False                              |
| last_review_date   | DateTime           | nullable                                   |

**Relación:** `tests = relationship("Test", back_populates="technique")`

**Actualizar** `models/__init__.py` para importar Technique.

**Generar migración:** `alembic revision --autogenerate -m "add_techniques_table"`

**Validación:**

- [ ] `alembic upgrade head` crea la tabla `techniques`
- [ ] La columna `status_global` es de tipo enum en Postgres
- [ ] La columna `platforms` es de tipo jsonb
- [ ] `alembic downgrade -1` limpia sin errores

---

### T-006: Modelo Test

**Archivo a crear:** `backend/app/models/test.py`

**Enums a crear:**
```python
class TestState(str, enum.Enum):
    draft = "draft"
    in_review = "in_review"
    validated = "validated"
    rejected = "rejected"

class TestResult(str, enum.Enum):
    detected = "detected"
    not_detected = "not_detected"
    partially_detected = "partially_detected"
```

**Campos:**

| Campo          | Tipo              | Restricciones                          |
|----------------|-------------------|----------------------------------------|
| id             | UUID              | PK, default uuid4                      |
| technique_id   | UUID              | FK → techniques.id, not null           |
| name           | String            | not null                               |
| description    | Text              | nullable                               |
| platform       | String            | nullable                               |
| procedure_text | Text              | nullable                               |
| tool_used      | String            | nullable                               |
| execution_date | DateTime          | nullable                               |
| created_by     | UUID              | FK → users.id, nullable                |
| result         | Enum(TestResult)  | nullable                               |
| state          | Enum(TestState)   | default draft                          |
| validated_by   | UUID              | FK → users.id, nullable                |
| validated_at   | DateTime          | nullable                               |
| created_at     | DateTime          | default utcnow                         |

**Relaciones:**

- `technique = relationship("Technique", back_populates="tests")`
- `evidences = relationship("Evidence", back_populates="test")`
- `creator = relationship("User", foreign_keys=[created_by])`
- `validator = relationship("User", foreign_keys=[validated_by])`

**Generar migración.**

**Validación:**

- [ ] `alembic upgrade head` crea tabla `tests` con FKs correctas
- [ ] FK a `techniques.id` y `users.id` existen
- [ ] Insertar un test con technique_id inexistente falla por FK constraint

---

### T-007: Modelo Evidence

**Archivo a crear:** `backend/app/models/evidence.py`

**Campos:**

| Campo       | Tipo     | Restricciones                |
|-------------|----------|------------------------------|
| id          | UUID     | PK, default uuid4            |
| test_id     | UUID     | FK → tests.id, not null      |
| file_name   | String   | not null                     |
| file_path   | String   | not null (path en MinIO)     |
| sha256_hash | String   | not null                     |
| uploaded_by | UUID     | FK → users.id, nullable      |
| uploaded_at | DateTime | default utcnow               |

**Relación:** `test = relationship("Test", back_populates="evidences")`

**Generar migración.**

**Validación:**

- [ ] Tabla `evidences` creada con FKs a `tests` y `users`
- [ ] Todas las columnas con tipos correctos

---

### T-008: Modelo IntelItem

**Archivo a crear:** `backend/app/models/intel.py`

**Campos:**

| Campo        | Tipo     | Restricciones                    |
|--------------|----------|----------------------------------|
| id           | UUID     | PK, default uuid4                |
| technique_id | UUID     | FK → techniques.id, nullable     |
| url          | String   | not null                         |
| title        | String   | nullable                         |
| source       | String   | nullable                         |
| detected_at  | DateTime | default utcnow                   |
| reviewed     | Boolean  | default False                    |

**Generar migración.**

**Validación:**

- [ ] Tabla `intel_items` creada
- [ ] FK a techniques funciona

---

### T-009: Modelo AuditLog

**Archivo a crear:** `backend/app/models/audit.py`

**Campos:**

| Campo       | Tipo     | Restricciones              |
|-------------|----------|----------------------------|
| id          | UUID     | PK, default uuid4          |
| user_id     | UUID     | FK → users.id, nullable    |
| action      | String   | not null                   |
| entity_type | String   | nullable                   |
| entity_id   | String   | nullable                   |
| timestamp   | DateTime | default utcnow             |
| details     | JSONB    | nullable                   |

**Crear función helper** `log_action` en `backend/app/services/audit_service.py`:
```python
def log_action(db: Session, user_id, action: str, entity_type: str = None, entity_id: str = None, details: dict = None):
    log = AuditLog(
        user_id=user_id,
        action=action,
        entity_type=entity_type,
        entity_id=str(entity_id) if entity_id else None,
        details=details,
    )
    db.add(log)
    db.commit()
```

**Generar migración.**

**Validación:**

- [ ] Tabla `audit_logs` creada
- [ ] Llamar a `log_action()` en un script de prueba inserta un registro correctamente

---

## FASE 2 — Autenticación y Autorización

### T-010: Utilidades de seguridad (hashing y JWT)

**Archivo a crear:** `backend/app/auth.py`

**Implementar:**

- `pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")`
- `hash_password(password: str) -> str`
- `verify_password(plain: str, hashed: str) -> bool`
- `create_access_token(data: dict) -> str` — incluye claim `exp` usando `ACCESS_TOKEN_EXPIRE_MINUTES` de settings
- Usa `python-jose` para encode/decode JWT

**No crear endpoints aquí**, solo funciones puras.

**Validación:**

- [ ] `hash_password("test123")` retorna un hash bcrypt
- [ ] `verify_password("test123", hash)` retorna True
- [ ] `verify_password("wrong", hash)` retorna False
- [ ] `create_access_token({"sub": "admin"})` retorna un token JWT decodificable

---

### T-011: Dependency de autenticación y RBAC

**Archivo a crear:** `backend/app/dependencies/auth.py`

**Implementar:**

1. `oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")`
2. Función `get_current_user(token, db)`:
   - Decodifica JWT
   - Extrae `sub` (username)
   - Busca User en BD
   - Si no existe o token inválido → HTTP 401
   - Retorna User
3. Función `require_role(required_role: str)`:
   - Retorna un dependency que verifica `user.role == required_role or user.role == "admin"`
   - Si no cumple → HTTP 403

**Crear** `backend/app/dependencies/__init__.py`

**Validación:**

- [ ] Importar `get_current_user` y `require_role` sin errores
- [ ] Las funciones tienen los Depends correctos en su firma

---

### T-012: Endpoint de Login y registro de admin

**Archivo a crear:** `backend/app/routers/auth.py`

**Schemas a crear** en `backend/app/schemas/auth.py`:

- `LoginRequest`: username (str), password (str)
- `TokenResponse`: access_token (str), token_type (str)
- `UserOut`: id, username, email, role, is_active

**Endpoints:**

1. `POST /auth/login` — recibe `OAuth2PasswordRequestForm`, valida credenciales, retorna JWT
2. `GET /auth/me` — requiere autenticación, retorna datos del usuario actual

**Crear script de seed** `backend/app/seed.py`:

- Crea un usuario admin inicial: username=`admin`, password=`admin123`, role=`admin`
- Solo lo crea si no existe
- Ejecutable con `python -m app.seed`

**Registrar router** en `main.py` con prefijo `/api/v1`.

**Validación:**

- [ ] Ejecutar seed crea usuario admin en BD
- [ ] `POST /api/v1/auth/login` con credenciales correctas retorna token
- [ ] `POST /api/v1/auth/login` con credenciales incorrectas retorna 400
- [ ] `GET /api/v1/auth/me` con token válido retorna datos del admin
- [ ] `GET /api/v1/auth/me` sin token retorna 401

---

### T-013: Middleware CORS

**Objetivo:** Configurar CORS para que el frontend (React en localhost:3000) pueda comunicarse con el backend.

**Modificar** `main.py`:
```python
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000", "http://localhost:5173"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
```

**Validación:**

- [ ] Una petición desde un origin distinto incluye headers CORS en la respuesta
- [ ] OPTIONS preflight request retorna 200

---

## FASE 3 — CRUD Core (Techniques y Tests)

### T-014: Schemas de Techniques y Tests

**Archivos a crear:**

- `backend/app/schemas/technique.py`
- `backend/app/schemas/test.py`
- `backend/app/schemas/__init__.py`

**Schemas de Technique:**

- `TechniqueCreate`: mitre_id, name, description (opt), tactic (opt), platforms (opt, list[str])
- `TechniqueUpdate`: name (opt), description (opt), tactic (opt), platforms (opt), status_global (opt)
- `TechniqueOut`: todos los campos del modelo, con `model_config = ConfigDict(from_attributes=True)`
- `TechniqueSummary`: id, mitre_id, name, tactic, status_global (para listados ligeros)

**Schemas de Test:**

- `TestCreate`: technique_id, name, description (opt), platform (opt), procedure_text (opt), tool_used (opt)
- `TestUpdate`: name (opt), description (opt), platform (opt), procedure_text (opt), tool_used (opt), result (opt)
- `TestOut`: todos los campos, con from_attributes
- `TestValidate`: result (TestResult), comments (opt, str)

**Validación:**

- [ ] Todos los schemas se importan sin errores
- [ ] `TechniqueCreate(mitre_id="T1059", name="Command Line")` instancia correctamente
- [ ] `TechniqueCreate(name="test")` falla por falta de mitre_id

---

### T-015: CRUD Techniques

**Archivo a crear:** `backend/app/routers/techniques.py`

**Endpoints:**

| Método | Ruta                            | Auth       | Descripción                              |
|--------|---------------------------------|------------|------------------------------------------|
| GET    | /techniques                     | autenticado | Listar todas. Filtros opcionales: tactic, status_global, review_required |
| GET    | /techniques/{mitre_id}          | autenticado | Detalle de una técnica con sus tests     |
| POST   | /techniques                     | admin       | Crear técnica manualmente                |
| PATCH  | /techniques/{mitre_id}          | admin       | Actualizar campos de una técnica         |
| PATCH  | /techniques/{mitre_id}/review   | red_lead, blue_lead, admin | Marcar como revisada (review_required=False, last_review_date=now) |

**Detalles de implementación:**

- El GET de listado debe soportar query params: `?tactic=initial-access&status=validated&review_required=true`
- El GET de detalle debe incluir los tests asociados (usar `joinedload` o cargar explícitamente)
- Cada mutación debe llamar a `log_action()`

**Registrar router** en main.py con prefijo `/api/v1`.

**Validación:**

- [ ] `POST /techniques` crea una técnica y la retorna
- [ ] `GET /techniques` retorna lista de técnicas
- [ ] `GET /techniques?tactic=execution` filtra correctamente
- [ ] `GET /techniques/T1059` retorna la técnica con sus tests
- [ ] `PATCH /techniques/T1059` actualiza campos
- [ ] `PATCH /techniques/T1059/review` actualiza review_required y last_review_date
- [ ] Un usuario sin rol admin no puede hacer POST (403)
- [ ] Cada operación genera un registro en audit_logs

---

### T-016: CRUD Tests

**Archivo a crear:** `backend/app/routers/tests.py`

**Endpoints:**

| Método | Ruta                    | Auth             | Descripción                        |
|--------|-------------------------|------------------|------------------------------------|
| POST   | /tests                  | red_tech, admin  | Crear test                         |
| GET    | /tests/{id}             | autenticado      | Detalle de un test con evidencias  |
| PATCH  | /tests/{id}             | creador o admin  | Actualizar test (solo si state=draft) |
| POST   | /tests/{id}/validate    | red_lead, blue_lead, admin | Validar test                |
| POST   | /tests/{id}/reject      | red_lead, blue_lead, admin | Rechazar test               |

**Detalles:**

- Al crear, setear `created_by` con el user actual y `state=draft`
- PATCH solo permitido si el test está en `draft` o `rejected`, si no → 400
- Validar: cambiar state a `validated`, setear validated_by, validated_at, y llamar a recalcular estado de la técnica
- Rechazar: cambiar state a `rejected`

**Servicio de recalculación** — crear `backend/app/services/status_service.py`:
```python
def recalculate_technique_status(db: Session, technique: Technique):
    tests = technique.tests
    if not tests:
        technique.status_global = TechniqueStatus.not_evaluated
    elif any(t.state != "validated" for t in tests):
        technique.status_global = TechniqueStatus.in_progress
    else:
        results = [t.result for t in tests]
        if all(r == "detected" for r in results):
            technique.status_global = TechniqueStatus.validated
        elif any(r == "partially_detected" for r in results):
            technique.status_global = TechniqueStatus.partial
        else:
            technique.status_global = TechniqueStatus.not_covered
    db.commit()
```

**Validación:**

- [ ] Crear test asociado a técnica existente → 201
- [ ] Crear test con technique_id inexistente → 404
- [ ] PATCH test en draft funciona
- [ ] PATCH test en validated → 400
- [ ] Validar test cambia state + validated_by + validated_at
- [ ] Tras validar todos los tests de una técnica con result=detected, la técnica pasa a status validated
- [ ] Audit log se genera para cada operación

---

### T-017: Upload y gestión de evidencias

**Archivos a crear:**

- `backend/app/storage.py` (cliente MinIO/S3)
- `backend/app/routers/evidence.py`
- `backend/app/schemas/evidence.py`

**storage.py:**

- Crear cliente boto3 apuntando a MinIO con settings
- Función `ensure_bucket_exists()` que crea el bucket si no existe
- Función `upload_file(content: bytes, key: str) -> str`
- Función `get_presigned_url(key: str, expiration: int = 3600) -> str`
- Llamar `ensure_bucket_exists()` al inicio de la app (en main.py startup)

**Endpoints:**

| Método | Ruta                        | Auth       | Descripción                       |
|--------|-----------------------------|------------|-----------------------------------|
| POST   | /tests/{test_id}/evidence   | autenticado | Subir archivo de evidencia       |
| GET    | /evidence/{id}              | autenticado | Obtener URL pre-firmada de descarga |

**Lógica del upload:**

1. Leer contenido del archivo
2. Calcular SHA256
3. Generar key: `{test_id}/{uuid}_{filename}`
4. Subir a MinIO
5. Crear registro Evidence en BD con file_name, file_path, sha256_hash, uploaded_by
6. Log de auditoría

**Schema EvidenceOut:** id, test_id, file_name, sha256_hash, uploaded_at, download_url (generado)

**Validación:**

- [ ] Subir un archivo a un test existente → 201, archivo aparece en MinIO
- [ ] GET del evidence retorna URL pre-firmada que permite descargar el archivo
- [ ] El hash SHA256 en BD coincide con el hash real del archivo
- [ ] Subir a test inexistente → 404

---

## FASE 4 — Sincronización MITRE ATT&CK

### T-018: Servicio de sync MITRE vía TAXII

**Archivo a crear:** `backend/app/services/mitre_sync_service.py`

**Lógica:**

1. Conectar a `https://cti-taxii.mitre.org/taxii/` usando `taxii2client`
2. Obtener primer api_root y primera collection (Enterprise ATT&CK)
3. Iterar objetos de tipo `attack-pattern`
4. Para cada uno:
   - Extraer `mitre_id` de `external_references` donde `source_name == "mitre-attack"`
   - Extraer `name`, `description`
   - Extraer tactics de `kill_chain_phases` (campo `phase_name`)
   - Determinar si es subtécnica (mitre_id contiene ".")
   - Si la técnica no existe → crear con status `not_evaluated`
   - Si existe y hay cambios en name/description → actualizar y marcar `review_required = True`
5. Commit al final
6. Log de auditoría con resumen: técnicas nuevas, actualizadas

**Validación:**

- [ ] Llamar a `sync_mitre(db)` puebla la tabla techniques con ~200+ técnicas
- [ ] Cada técnica tiene mitre_id, name y description
- [ ] Ejecutar sync dos veces no duplica técnicas
- [ ] Si se modifica manualmente el name de una técnica y se re-sincroniza, se actualiza y review_required=True

---

### T-019: Job programado y endpoint manual de sync

**Archivos a crear/modificar:**

- `backend/app/jobs/mitre_sync_job.py`
- `backend/app/routers/system.py`
- Modificar `main.py` para iniciar scheduler

**Job:**

- Usar `BackgroundScheduler` de APScheduler
- Programar `sync_mitre` cada 24 horas
- El job crea su propia sesión de BD y la cierra en finally

**Endpoint manual:**
```
POST /api/v1/system/sync-mitre
Auth: admin only
Response: {"message": "MITRE sync completed", "new": X, "updated": Y}
```

**Inicialización en main.py:**

- Usar evento `@app.on_event("startup")` para arrancar el scheduler
- No ejecutar sync automático al arrancar (solo el job programado)

**Validación:**

- [ ] `POST /system/sync-mitre` con admin ejecuta el sync y retorna stats
- [ ] `POST /system/sync-mitre` sin admin → 403
- [ ] El scheduler se inicia al arrancar la app (visible en logs)
- [ ] Audit log registra la sincronización

---

## FASE 5 — Métricas y Dashboard API

### T-020: Endpoints de métricas

**Archivo a crear:** `backend/app/routers/metrics.py`

**Schemas** en `backend/app/schemas/metrics.py`:
```python
class CoverageSummary(BaseModel):
    total_techniques: int
    validated: int
    partial: int
    not_covered: int
    in_progress: int
    not_evaluated: int
    coverage_percentage: float  # (validated + partial) / total * 100

class TacticCoverage(BaseModel):
    tactic: str
    total: int
    validated: int
    partial: int
    not_covered: int
    not_evaluated: int
    in_progress: int
```

**Endpoints:**

| Método | Ruta               | Auth        | Descripción                          |
|--------|--------------------|-------------|--------------------------------------|
| GET    | /metrics/summary   | autenticado | Resumen global de cobertura          |
| GET    | /metrics/by-tactic | autenticado | Desglose de cobertura por táctica    |

**Implementación:**

- Summary: contar técnicas agrupadas por status_global, calcular porcentaje
- By-tactic: agrupar por campo `tactic` y contar status dentro de cada grupo
- Usar queries con `func.count` y `group_by` de SQLAlchemy

**Validación:**

- [ ] `/metrics/summary` retorna conteos que suman el total de técnicas
- [ ] `coverage_percentage` se calcula correctamente
- [ ] `/metrics/by-tactic` retorna un array con un elemento por táctica
- [ ] Los números son consistentes entre summary y by-tactic

---

## FASE 6 — Intel Automática

### T-021: Servicio de Intel scan

**Archivo a crear:** `backend/app/services/intel_service.py`

**Lógica:**

1. Obtener todas las técnicas de BD
2. Para cada técnica, buscar en fuentes RSS/web por keywords:
   - `"{mitre_id} bypass"`
   - `"{mitre_id} detection evasion"`
   - `"{technique_name} attack"`
3. Fuentes sugeridas: usar búsqueda con `requests` contra feeds RSS públicos de seguridad (ej: NIST NVD, blogs de seguridad)
4. Por cada resultado nuevo (URL no existente en intel_items):
   - Crear IntelItem asociado a la técnica
   - Marcar técnica con `review_required = True`
5. Log de auditoría

**Nota:** Este es un MVP — la búsqueda puede ser simple. No usar LLMs. Basta con hacer requests HTTP a feeds RSS y parsear con regex o xml.

**Validación:**

- [ ] Ejecutar el scan crea registros en `intel_items`
- [ ] No se duplican URLs ya existentes
- [ ] Las técnicas con nuevos items de intel quedan con review_required=True

---

### T-022: Job y endpoint de Intel scan

**Modificar:** `backend/app/jobs/` y `backend/app/routers/system.py`

**Job:** programar intel scan semanal con APScheduler

**Endpoint:**
```
POST /api/v1/system/run-intel-scan
Auth: admin only
Response: {"message": "Intel scan completed", "new_items": X}
```

**Validación:**

- [ ] Endpoint ejecuta el scan y retorna conteo
- [ ] Job semanal queda registrado en el scheduler
- [ ] Audit log registra la ejecución

---

## FASE 7 — Frontend: Scaffolding y Auth

### T-023: Inicializar proyecto React

**Objetivo:** Crear app React con Vite, instalar dependencias base.

**Pasos:**

1. Dentro de `frontend/`, ejecutar `npm create vite@latest . -- --template react-ts`
2. Instalar dependencias:
   - `react-router-dom` (routing)
   - `axios` (HTTP)
   - `@tanstack/react-query` (cache/fetching)
   - `tailwindcss` + `postcss` + `autoprefixer` (estilos)
   - `lucide-react` (iconos)
3. Configurar Tailwind CSS
4. Crear estructura de carpetas:
```
frontend/src/
├── api/          (clientes axios)
├── components/   (componentes reutilizables)
├── pages/        (páginas/vistas)
├── hooks/        (custom hooks)
├── context/      (contexts React)
├── types/        (tipos TypeScript)
├── lib/          (utilidades)
└── App.tsx
```

5. Añadir servicio `frontend` al `docker-compose.yml` o documentar cómo levantar en dev con `npm run dev`

**Validación:**

- [ ] `npm run dev` levanta el frontend en localhost:5173
- [ ] Se ve la página de bienvenida de Vite+React
- [ ] Tailwind funciona (probar una clase como `text-red-500`)

---

### T-024: Cliente API y contexto de autenticación

**Archivos a crear:**

- `frontend/src/api/client.ts` — instancia axios con baseURL `http://localhost:8000/api/v1`, interceptor que añade token del localStorage
- `frontend/src/api/auth.ts` — funciones `login(username, password)` y `getMe()`
- `frontend/src/context/AuthContext.tsx` — context que expone: user, login, logout, isAuthenticated, isLoading
- `frontend/src/types/models.ts` — tipos TypeScript para User, Technique, Test, Evidence, etc.

**Lógica del AuthContext:**

- Al montar, verificar si hay token en localStorage y llamar a `/auth/me`
- `login()`: llama al endpoint, guarda token, setea user
- `logout()`: borra token, limpia estado
- Exponer `isAuthenticated` como boolean derivado

**Validación:**

- [ ] Importar AuthContext sin errores
- [ ] Login con credenciales correctas guarda token y setea user
- [ ] Refrescar la página mantiene la sesión (token en localStorage)
- [ ] Logout limpia todo

---

### T-025: Páginas de Login y Layout principal

**Archivos a crear:**

- `frontend/src/pages/LoginPage.tsx`
- `frontend/src/components/Layout.tsx`
- `frontend/src/components/Sidebar.tsx`
- `frontend/src/components/ProtectedRoute.tsx`
- Configurar rutas en `App.tsx`

**LoginPage:**

- Formulario con username y password
- Botón de submit
- Manejo de errores (credenciales incorrectas)
- Redirige a `/dashboard` tras login exitoso

**Layout:**

- Sidebar a la izquierda con navegación: Dashboard, Técnicas, Tests, Sistema
- Área de contenido principal a la derecha
- Header con nombre de usuario y botón de logout
- Sidebar muestra/oculta items según rol del usuario

**ProtectedRoute:**

- Wrapper que redirige a `/login` si no hay sesión
- Acepta prop `roles` para restringir acceso por rol

**Rutas:**

- `/login` → LoginPage
- `/` → redirige a /dashboard
- `/dashboard` → protegida
- `/techniques` → protegida
- `/tests` → protegida
- `/system` → protegida, solo admin

**Validación:**

- [ ] Acceder a `/dashboard` sin sesión redirige a `/login`
- [ ] Login exitoso redirige a `/dashboard`
- [ ] El layout muestra sidebar y header
- [ ] Logout redirige a `/login`
- [ ] Un usuario no-admin no ve el item "Sistema" en la sidebar

---

## FASE 8 — Frontend: Vistas principales

### T-026: Dashboard de cobertura

**Archivo a crear:** `frontend/src/pages/DashboardPage.tsx`

**Componentes a crear:**

- `CoverageSummaryCard` — muestra total, validados, parciales, no cubiertos, con porcentaje
- `TacticCoverageChart` — tabla o gráfico de barras por táctica (puede ser una tabla estilizada sin librería de gráficos, o usar `recharts` si se prefiere)

**Lógica:**

- Llamar a `GET /metrics/summary` y `GET /metrics/by-tactic` al montar
- Usar `@tanstack/react-query` para fetching

**UI:**

- Cards superiores con los números principales (total, validado, parcial, etc.)
- Cada card con color acorde al estado (verde validado, amarillo parcial, rojo no cubierto, gris no evaluado, azul en progreso)
- Tabla inferior con desglose por táctica

**Validación:**

- [ ] El dashboard muestra números reales del backend
- [ ] Los números coinciden con los de la API
- [ ] Se ve responsive en distintos tamaños de pantalla

---

### T-027: Vista de Matriz ATT&CK interactiva

**Archivo a crear:** `frontend/src/pages/MatrixPage.tsx`

**Componentes:**

- `AttackMatrix` — renderiza la matriz como grid
- `TechniqueCell` — cada celda de la matriz, coloreada por status

**Lógica:**

- Llamar a `GET /techniques` para obtener todas las técnicas
- Agrupar por `tactic` para crear las columnas de la matriz
- Cada celda muestra mitre_id y name, coloreada según status_global:
  - Verde → validated
  - Amarillo → partial o review_required
  - Rojo → not_covered
  - Gris → not_evaluated
  - Azul → in_progress

**Interacciones:**

- Click en una celda → navegar a `/techniques/{mitre_id}`
- Filtros superiores: por tactic, por status, por plataforma
- Indicador visual si review_required=true (ej: badge o borde)

**Validación:**

- [ ] La matriz muestra todas las técnicas agrupadas por táctica
- [ ] Los colores corresponden al status correcto
- [ ] Los filtros funcionan y reducen las técnicas mostradas
- [ ] Click en celda navega al detalle

---

### T-028: Vista detalle de Técnica

**Archivo a crear:** `frontend/src/pages/TechniqueDetailPage.tsx`

**Secciones:**

1. **Header**: mitre_id, name, status badge, botón de marcar como revisada
2. **Info**: description, tactic, platforms, última fecha de revisión
3. **Tests asociados**: tabla con name, state, result, created_at, actions (ver/validar/rechazar)
4. **Intel items**: lista de items de inteligencia asociados (si los hay)

**Acciones:**

- Botón "Marcar revisada" → `PATCH /techniques/{mitre_id}/review` (solo leads/admin)
- Botón "Nuevo Test" → formulario o navegación a crear test
- En cada test: botones de validar/rechazar según rol y estado

**Validación:**

- [ ] Se muestran todos los datos de la técnica
- [ ] Los tests asociados aparecen en la tabla
- [ ] Marcar como revisada actualiza el badge y la fecha
- [ ] Los botones de acción respetan los roles

---

### T-029: Formulario de creación/edición de Test

**Archivos a crear:**

- `frontend/src/pages/TestCreatePage.tsx`
- `frontend/src/components/TestForm.tsx`

**Campos del formulario:**

- Técnica (selector, pre-seleccionado si se viene desde una técnica)
- Nombre
- Descripción
- Plataforma (selector: windows, linux, macos, cloud, network)
- Procedimiento (textarea)
- Herramienta utilizada
- Resultado (selector: detected, not_detected, partially_detected) — opcional al crear

**Al enviar:**

- `POST /tests` con los datos
- Redirigir al detalle de la técnica asociada
- Mostrar toast/notificación de éxito

**Validación:**

- [ ] El formulario renderiza todos los campos
- [ ] Submit con datos válidos crea el test y redirige
- [ ] Submit sin campos requeridos muestra errores
- [ ] El selector de técnica funciona y muestra mitre_id + name

---

### T-030: Upload de evidencias en detalle de Test

**Modificar:** Vista de detalle de técnica o crear `TestDetailPage.tsx`

**Componentes:**

- `EvidenceUpload` — zona de drag & drop o botón de subir archivo
- `EvidenceList` — lista de evidencias subidas con nombre, hash, fecha, botón de descarga

**Lógica:**

- Upload: `POST /tests/{test_id}/evidence` con FormData
- Descarga: `GET /evidence/{id}` obtiene URL pre-firmada, abrir en nueva pestaña

**Validación:**

- [ ] Se puede subir un archivo y aparece en la lista
- [ ] El botón de descarga abre el archivo desde MinIO
- [ ] Se muestra el hash SHA256 del archivo
- [ ] Subir a un test inexistente muestra error

---

### T-031: Panel de administración / Sistema

**Archivo a crear:** `frontend/src/pages/SystemPage.tsx`

**Secciones:**

1. **Sync MITRE**: botón para trigger manual, muestra última fecha de sync
2. **Intel Scan**: botón para trigger manual, muestra último scan
3. **Información del sistema**: versión, BD conectada, MinIO status

**Acciones:**

- Botón sync MITRE → `POST /system/sync-mitre`, mostrar resultado
- Botón intel scan → `POST /system/run-intel-scan`, mostrar resultado
- Ambos con loading state y feedback

**Validación:**

- [ ] Solo accesible por admin
- [ ] Botón de sync ejecuta y muestra resultado (nuevas/actualizadas)
- [ ] Botón de intel scan ejecuta y muestra resultado
- [ ] Loading states funcionan correctamente

---

## FASE 9 — Pulido y Cierre MVP

### T-032: Gestión de usuarios (admin)

**Archivos a crear:**

- `backend/app/routers/users.py`
- `frontend/src/pages/UsersPage.tsx`

**Endpoints backend:**

| Método | Ruta              | Auth  | Descripción                     |
|--------|-------------------|-------|---------------------------------|
| GET    | /users            | admin | Listar usuarios                 |
| POST   | /users            | admin | Crear usuario                   |
| PATCH  | /users/{id}       | admin | Editar rol, activar/desactivar  |

**Frontend:**

- Tabla de usuarios con columnas: username, email, rol, activo, acciones
- Formulario de creación: username, email, password, rol
- Botón de activar/desactivar

**Validación:**

- [ ] Admin puede crear un nuevo usuario
- [ ] Admin puede cambiar el rol de un usuario
- [ ] Admin puede desactivar un usuario
- [ ] Un usuario desactivado no puede hacer login
- [ ] No-admin no puede acceder a esta sección

---

### T-033: Audit log viewer

**Archivos a crear:**

- `backend/app/routers/audit.py` — endpoint `GET /audit-logs` con paginación y filtros (admin only)
- `frontend/src/pages/AuditLogPage.tsx`

**Filtros:** por user_id, action, entity_type, rango de fechas.

**Paginación:** offset + limit o cursor-based.

**Frontend:** tabla con timestamp, usuario, acción, entidad, con filtros superiores.

**Validación:**

- [ ] GET retorna logs paginados
- [ ] Filtrar por action funciona
- [ ] Filtrar por rango de fechas funciona
- [ ] Solo admin puede acceder

---

### T-034: Error handling global y loading states

**Objetivo:** Asegurar que toda la app maneja errores y estados de carga consistentemente.

**Backend:**

- Crear exception handlers globales en main.py para 404, 400, 500
- Formato consistente de error: `{"detail": "mensaje", "code": "ERROR_CODE"}`

**Frontend:**

- Componente `ErrorBoundary` global
- Componente `LoadingSpinner` reutilizable
- Componente `ErrorMessage` reutilizable
- Interceptor axios que maneja 401 (redirect a login) y 500 (toast de error)
- Todas las páginas existentes usan los estados de loading/error de react-query

**Validación:**

- [ ] Un 401 desde cualquier endpoint redirige al login
- [ ] Un error de servidor muestra un mensaje amigable
- [ ] Todas las vistas muestran spinner mientras cargan datos
- [ ] La app no se rompe con un error no controlado (ErrorBoundary lo captura)

---

### T-035: Tests automáticos backend (básicos)

**Archivo a crear:** `backend/tests/` con pytest

**Tests mínimos:**

- `test_health.py`: GET /health retorna 200
- `test_auth.py`: login correcto/incorrecto, acceso con/sin token
- `test_techniques.py`: CRUD básico de técnicas
- `test_tests.py`: crear test, validar, verificar recalculación de status

**Setup:**

- Usar BD de test (sqlite en memoria o Postgres de test)
- Fixtures para crear usuario de prueba y token

**Añadir a requirements.txt:** `pytest`, `httpx` (para TestClient async)

**Validación:**

- [ ] `pytest` ejecuta todos los tests y pasan
- [ ] Cobertura de los flujos principales de auth, técnicas y tests

---

### T-036: README y documentación de despliegue

**Archivos a crear:**

- `README.md` en la raíz del proyecto
- `docs/API.md` con documentación de endpoints (o referir a Swagger en /docs)

**README debe incluir:**

- Descripción del proyecto
- Requisitos (Docker, Node.js)
- Cómo levantar el entorno: `docker-compose up`
- Cómo ejecutar migraciones: `alembic upgrade head`
- Cómo crear usuario admin: `python -m app.seed`
- Cómo ejecutar el sync inicial de MITRE
- Cómo acceder: URLs del frontend, backend, MinIO, Swagger
- Variables de entorno configurables
- Estructura del proyecto

**Validación:**

- [ ] Siguiendo el README desde cero se puede levantar todo el proyecto
- [ ] Los endpoints documentados coinciden con los implementados
- [ ] Swagger UI en /docs muestra todos los endpoints

---

## Resumen de Fases

| Fase | Tareas       | Descripción                              |
|------|--------------|------------------------------------------|
| 0    | T-001 a T-003| Infraestructura y scaffolding            |
| 1    | T-004 a T-009| Modelos de datos y migraciones           |
| 2    | T-010 a T-013| Autenticación y autorización             |
| 3    | T-014 a T-017| CRUD core (techniques, tests, evidences) |
| 4    | T-018 a T-019| Sincronización MITRE ATT&CK              |
| 5    | T-020        | Métricas y dashboard API                 |
| 6    | T-021 a T-022| Intel automática                         |
| 7    | T-023 a T-025| Frontend: scaffolding y auth             |
| 8    | T-026 a T-031| Frontend: vistas principales             |
| 9    | T-032 a T-036| Pulido, admin, tests y docs              |

> **Total: 36 tareas = 36 commits mínimo**
> Cada tarea es autocontenida y verificable antes de hacer commit.