diff --git a/README.md b/README.md index 20d237a..10a2cb9 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,328 @@ # Attack Surface Studio -A Knowledge Graph platform for security reconnaissance and assessment. It orchestrates -external security tools (Nmap, ffuf, Nuclei, …), normalizes their heterogeneous output into -a single graph model, and turns an engagement's accumulated evidence — scans, manual -findings, screenshots, notes, reports — into one navigable, queryable body of knowledge. +**Plataforma de grafo de conocimiento para reconocimiento y evaluación de superficie de ataque.** -The Knowledge Graph is the product. Security tools are data sources only: every adapter -ultimately produces exactly three things — **Nodes**, **Edges**, and **Metadata** — and -those are what the rest of the platform (UI, reports, AI assistant) reads from. See -[`.claude/Claude.md`](.claude/Claude.md) for the full project philosophy and architecture -docs (`ARCHITECTURE.md`, `DATA_MODEL.md`, `INTEGRATION_SYSTEM.md`, `SECURITY_MODEL.md`, -`Plan.md`). +Orquesta herramientas de seguridad externas (Nmap, ffuf, Nuclei), normaliza su salida heterogénea +a un único modelo de grafo, y convierte la evidencia acumulada de un diagnóstico —escaneos, +hallazgos manuales, capturas, notas, reportes— en un cuerpo de conocimiento navegable y consultable. -## Stack +> El grafo de conocimiento es el producto. Las herramientas de seguridad son solo fuentes de datos: +> cada adaptador produce exactamente tres cosas —**Nodos**, **Aristas** y **Metadatos**— y eso es lo +> que leen la interfaz, los reportes y el asistente de IA. -| Layer | Choice | +![Landing de Attack Surface Studio](screenshots/01-landing.png) + +--- + +## Índice + +- [Cómo funciona](#cómo-funciona) +- [Capturas de pantalla](#capturas-de-pantalla) +- [Stack tecnológico](#stack-tecnológico) +- [Puesta en marcha](#puesta-en-marcha) +- [Variables de entorno](#variables-de-entorno) +- [Adaptadores y control de alcance](#adaptadores-y-control-de-alcance) +- [Estructura del proyecto](#estructura-del-proyecto) +- [Testing](#testing) +- [Limitaciones conocidas](#limitaciones-conocidas) +- [Documentación](#documentación) + +--- + +## Cómo funciona + +El flujo es deliberadamente simple y verificable de punta a punta: + +1. **Registras un proyecto** con un alcance (`scope`) explícito de objetivos autorizados. +2. **Lanzas una ejecución** eligiendo un adaptador de herramienta y un objetivo. +3. **El orquestador valida el alcance** antes de ejecutar nada. Si el objetivo no está en el + `scope`, la ejecución se rechaza con `403 SCOPE_VIOLATION`. +4. **El adaptador normaliza la salida** a nodos y aristas (`child_process` en local, Docker en modo + remoto) y un worker BullMQ la persiste en PostgreSQL. +5. **El grafo se vuelve navegable**: activos, hallazgos, relaciones y su cronología. + +El control de alcance no es decorativo: se comprueba **antes de la ejecución**, no después. + +--- + +## Capturas de pantalla + +Todas las capturas son de la aplicación en ejecución, con datos reales generados a través de la +API y de la interfaz. + +### Acceso y proyectos + + + + + + + + + +
Pantalla de inicio de sesiónPantalla de registro
Inicio de sesión y registro
+ + + + + + + + + +
Estado inicial sin proyectosLista de proyectos con un proyecto
Estado vacío y lista de proyectos
+ +### Ejecuciones de herramientas + +| Formulario y estado inicial | Detalle de la ejecución | +|---|---| +| Pestaña Runs sin ejecuciones | Detalle de la ejecución | + +La vista de Runs muestra el formulario de ejecución (adaptador + objetivo) y el historial completo +de ejecuciones con su estado y su duración. + +Pestaña Runs con historial de ejecuciones + +### Grafo de conocimiento + +Todo proyecto arranca sin descubrimientos, y se va llenando a medida que se ejecutan herramientas: + +| Proyecto recién creado | Grafo con activos y hallazgo | +|---|---| +| Proyecto recién creado sin descubrimientos | Grafo con activos y hallazgo | + +Y el detalle de un nodo concreto: + +Panel de detalle del nodo seleccionado + +> El grafo se renderiza en la vista **Timeline**, que es la que monta el motor de grafo con +> dimensiones correctas. Ver [Limitaciones conocidas](#limitaciones-conocidas). + +### Evidencia, reportes, asistente y ajustes + +| Evidencia sin archivos | Evidencia del proyecto | +|---|---| +| Pestaña Evidence vacía | Pestaña Evidence | + +| Reportes sin generar | Asistente de IA | +|---|---| +| Pestaña Reports vacía | Pestaña Assistant | + +El alcance autorizado del proyecto se gestiona desde la pestaña de ajustes: + +Pestaña Settings con el scope del proyecto + +Y el constructor de reportes permite seleccionar los nodos del grafo que se incluirán: + +Constructor de reportes + +--- + +## Stack tecnológico + +| Capa | Tecnología | |---|---| | Frontend | Next.js 16 (App Router), React 19, TypeScript strict, Tailwind v4, React Flow, Zustand, TanStack Query | -| Backend | NestJS, TypeScript, Drizzle ORM, BullMQ (Redis-backed job queue) | -| Database | PostgreSQL 16 | -| Tool execution | `child_process` (local) / `dockerode` (Docker) behind a Tool Adapter registry (`nmap`, `ffuf`, `nuclei`, …) | -| Auth | JWT (short-lived access + rotating refresh), Argon2id password hashing | -| Testing | Vitest + Supertest (integration), Playwright (E2E) | +| Backend | NestJS, TypeScript, Drizzle ORM, BullMQ (cola de trabajos con Redis) | +| Base de datos | PostgreSQL 16 | +| Ejecución de herramientas | `child_process` (local) / `dockerode` (Docker) tras un registro de adaptadores | +| Autenticación | JWT (access corto + refresh rotativo), hash de contraseña Argon2id | +| Testing | Vitest + Supertest (integración), Playwright (E2E) | -## Project layout +--- -``` -Attack Surface Studio/ -├── client/ Next.js frontend (marketing Hero + Graph Engine + authenticated Workspace) -├── server/ NestJS backend (auth, orchestrator, adapters, knowledge graph, reports) -├── db/ Postgres bootstrap scripts (docker-entrypoint-initdb.d) -├── docker-compose.yml Local Postgres + Redis -└── .claude/ Architecture and planning documentation (source of truth) -``` +## Puesta en marcha -## Prerequisites +### Requisitos previos - Node.js 20+ - [pnpm](https://pnpm.io/) 9 -- Docker (for local Postgres + Redis via `docker-compose`) +- Docker (para PostgreSQL y Redis) + +### 1. Bases de datos + +```bash +cp .env.example .env # completa los valores antes de usar nada que no sea local +docker compose up -d # PostgreSQL en :5432, Redis en :6379 +``` -## Getting started +El esquema se aplica automáticamente en el primer arranque gracias a +[`db/init`](db/init) (montado como `docker-entrypoint-initdb.d`). Si necesitas reaplicar +migraciones de forma explícita, usa `pnpm migrate` desde `server/`. -1. **Start the datastores** +### 2. Backend (`server/`) - ```bash - cp .env.example .env # fill in real values before running in anything but local dev - docker-compose up -d - ``` +```bash +cd server +pnpm install +cp .env.example .env # DATABASE_URL, JWT_*, REDIS_URL, STORAGE_ROOT... +pnpm migrate +pnpm seed # opcional: carga un proyecto de ejemplo +pnpm start:dev # API en http://localhost:3001 +``` -2. **Backend** (`server/`) +> **Aviso sobre `pnpm seed`:** el usuario demo que crea el seed (`demo@attacksurfacestudio.dev`) +> se genera con un hash de contraseña literal (`seed-placeholder`) que no es un hash Argon2id +> válido, así que **no se puede iniciar sesión con él**. El seed sí sirve para tener un proyecto con +> 26 nodos y 20 aristas que consultar. Para probar la aplicación, regístrate con una cuenta nueva +> desde la interfaz. - ```bash - cd server - pnpm install - cp .env.example .env # DATABASE_URL, JWT secrets, REDIS_URL, etc. — see file comments - pnpm migrate - pnpm start:dev # API on http://localhost:3001 - pnpm start:worker:dev # separate process: executes queued tool runs - ``` +El worker es un proceso separado y es quien ejecuta los trabajos de la cola: -3. **Frontend** (`client/`) +```bash +pnpm start:worker:dev +``` - ```bash - cd client - pnpm install - cp .env.example .env # NEXT_PUBLIC_API_URL=http://localhost:3001 - pnpm dev # App on http://localhost:3000 - ``` +> **El worker es obligatorio.** La API encola los trabajos, pero sin el worker ninguna ejecución +> avanza. Si lanzas una ejecución y se queda en `queued`, casi siempre es esto. -4. Open [http://localhost:3000](http://localhost:3000). The landing page's "Request access" / - "Sign in" buttons lead to `/register` and `/login`; once authenticated you land on `/app`. +Para ejecutar en modo producción, compila primero y usa los scripts sin watcher: + +```bash +pnpm build && pnpm start # en una terminal +pnpm build && pnpm start:worker # en otra +``` + +### 3. Frontend (`client/`) + +```bash +cd client +pnpm install +cp .env.example .env # NEXT_PUBLIC_API_URL=http://localhost:3001 +pnpm dev # http://localhost:3000 +``` + +Para un build de producción: `pnpm build && pnpm start`. + +> `client/AGENTS.md` es un archivo generado y versionado por `next dev`. Si ejecutas el frontend con +> `next start` evitas que se reescriba. + +### 4. Verificar que todo está en pie + +```bash +curl http://localhost:3001/api/v1/health +# {"success":true,"data":{"status":"ok","database":"up"}} +``` + +Después abre [http://localhost:3000](http://localhost:3000), regístrate y acabarás en `/app`. + +### Puertos + +| Servicio | Puerto | +|---|---| +| Frontend (Next.js) | 3000 | +| API (NestJS) | 3001 | +| PostgreSQL | 5432 (configurable con `POSTGRES_PORT`) | +| Redis | 6379 (configurable con `REDIS_PORT`) | + +--- + +## Variables de entorno + +| Archivo | Variables | +|---|---| +| `.env` (raíz) | `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_PORT`, `APP_DB_USER`, `APP_DB_PASSWORD` | +| `server/.env` | `PORT`, `CORS_ORIGINS`, `DATABASE_URL`, `APP_DATABASE_URL`, `JWT_ACCESS_SECRET`, `JWT_ACCESS_TTL`, `JWT_REFRESH_TTL`, `REDIS_URL`, `STORAGE_ROOT`, `THROTTLE_TTL_MS`, `THROTTLE_LIMIT`, `NVIDIA_*` | +| `client/.env` | `NEXT_PUBLIC_API_URL` | + +`server/` y `client/` son proyectos pnpm independientes: no hay workspace en la raíz, así que los +comandos se ejecutan dentro de cada directorio. + +`NVIDIA_API_KEY` es opcional. Sin ella el asistente de IA no puede responder. + +--- + +## Adaptadores y control de alcance + +Los adaptadores registrados son `stub`, `nmap`, `ffuf` y `nuclei`. El adaptador `stub` genera +salida determinista sin tocar la red, y es el recomendado para desarrollo y para las pruebas +automatizadas. + +Cada ejecución exige que el objetivo esté autorizado en el `scope` del proyecto +(`includes` / `excludes`, con entradas de tipo hostname, dominio comodín, IP o CIDR). Un proyecto +sin scope no puede ejecutar nada: + +``` +POST /api/v1/projects/:id/runs +→ 403 {"error":{"code":"SCOPE_VIOLATION", + "message":"Target \"example.com\" is outside the project's authorized scope"}} +``` + +El scope se configura en la pestaña **Settings** del proyecto. + +--- + +## Estructura del proyecto + +``` +Attack Surface Studio/ +├── client/ Frontend Next.js (Hero público + motor de grafo + workspace autenticado) +├── server/ Backend NestJS (auth, orquestador, adaptadores, grafo, reportes) +├── db/init/ Scripts de arranque de PostgreSQL +├── screenshots/ Capturas de la interfaz usadas en este README +├── docker-compose.yml PostgreSQL + Redis locales +└── .claude/ Documentación de arquitectura y planificación +``` + +--- ## Testing ```bash # Frontend -cd client && pnpm test # Vitest + Testing Library -cd client && pnpm e2e # Playwright +cd client && pnpm test +cd client && pnpm e2e # Backend -cd server && pnpm test # Vitest + Supertest +cd server && pnpm test cd server && pnpm test:coverage ``` -Both projects enforce an 80% coverage floor. Adapter tests run against recorded real tool -output fixtures rather than live scans. +Ambos proyectos exigen un piso de cobertura del 80%. Las pruebas de adaptadores se ejecutan +contra fixtures de salida real grabada, no contra escaneos en vivo. + +--- + +## Limitaciones conocidas + +Documentadas de forma explícita, con el comportamiento observado: + +- **La pestaña Graph no renderiza el lienzo.** El contenedor de React Flow colapsa a altura `0` + (`1600x0` medido), así que la vista queda vacía aunque la API devuelva correctamente los nodos y + el cliente los lea bien. El problema es de maquetación en cliente, no de datos. Curiosamente, la + vista **Timeline** monta el mismo motor con dimensiones correctas y sí dibuja el grafo, así que + sirve como workaround. El commit `148c9` (`BUG #7`) ya intentó resolver exactamente esto aplicando + `absolute inset-0` en `WorkspaceGraphView`, y el fallo persiste: parece una regresión de aquel + arreglo o un caso que no cubría. +- **`/docs` devuelve 404.** La ruta no existe aunque el navbar incluya un enlace a ella. +- **El ensamblado de reportes está bloqueado por lo anterior.** El constructor exige seleccionar al + menos un nodo del grafo, y la pestaña Graph no los dibuja, así que por la interfaz no se puede + completar un reporte. El backend sí expone el recurso. +- **El asistente de IA requiere `NVIDIA_API_KEY`.** Sin la clave responde en estado degradado. +- **`pnpm seed` genera un usuario demo inutilizable.** Su hash de contraseña es un placeholder, no + un hash Argon2id real, así que el login con `demo@attacksurfacestudio.dev` falla siempre. Los datos + del seed sí sirven como referencia. + +--- + +## Documentación + +El repositorio incluye la documentación siguiente: + +- [`.claude/New_files.md`](.claude/New_files.md) — registro de archivos previstos en la Fase 1 +- [`client/e2e/README.md`](client/e2e/README.md) — requisitos y ejecución de las pruebas E2E +- [`client/AGENTS.md`](client/AGENTS.md) — bloque de reglas de Next.js, generado y versionado +- [`docker-compose.yml`](docker-compose.yml) y [`db/init/`](db/init) — infraestructura local + +Los documentos de arquitectura (`ARCHITECTURE.md`, `DATA_MODEL.md`, `SECURITY_MODEL.md`, +`INTEGRATION_SYSTEM.md`) que se mencionaban en versiones anteriores de este README **no están +presentes en el repositorio**, así que se han retirado los enlaces en lugar de dejarlos rotos. El +código y los contratos de TypeScript son hoy la fuente de verdad: los tipos del modelo de grafo +viven en `server/src/modules/projects` y `client/src/modules/graph-engine/types`. + +--- -## Documentation +## Licencia -Everything beyond this quick-start — vision, data model, security posture, the phased -roadmap, and the development log — lives in [`.claude/`](.claude): +Proyecto de portafolio. Sin licencia pública declarada. -- [`Claude.md`](.claude/Claude.md) — vision, philosophy, stack, standards (start here) -- [`ARCHITECTURE.md`](.claude/ARCHITECTURE.md) — system decomposition -- [`DATA_MODEL.md`](.claude/DATA_MODEL.md) — PostgreSQL schema for the graph -- [`INTEGRATION_SYSTEM.md`](.claude/INTEGRATION_SYSTEM.md) — the Tool Adapter contract -- [`SECURITY_MODEL.md`](.claude/SECURITY_MODEL.md) — cross-cutting security posture -- [`Plan.md`](.claude/Plan.md) — the phased roadmap -- [`Progress.md`](.claude/Progress.md) — development log -- [`Routes.md`](.claude/Routes.md) — routing registry diff --git a/screenshots/01-landing.png b/screenshots/01-landing.png new file mode 100644 index 0000000..3c3b8bd Binary files /dev/null and b/screenshots/01-landing.png differ diff --git a/screenshots/02-login.png b/screenshots/02-login.png new file mode 100644 index 0000000..8c509a6 Binary files /dev/null and b/screenshots/02-login.png differ diff --git a/screenshots/03-register.png b/screenshots/03-register.png new file mode 100644 index 0000000..abf9ad8 Binary files /dev/null and b/screenshots/03-register.png differ diff --git a/screenshots/04-projects-vacio.png b/screenshots/04-projects-vacio.png new file mode 100644 index 0000000..fbc1b19 Binary files /dev/null and b/screenshots/04-projects-vacio.png differ diff --git a/screenshots/05-grafo-sin-datos.png b/screenshots/05-grafo-sin-datos.png new file mode 100644 index 0000000..1b06b5b Binary files /dev/null and b/screenshots/05-grafo-sin-datos.png differ diff --git a/screenshots/06-runs-vacio.png b/screenshots/06-runs-vacio.png new file mode 100644 index 0000000..f932371 Binary files /dev/null and b/screenshots/06-runs-vacio.png differ diff --git a/screenshots/07-evidencia-vacia.png b/screenshots/07-evidencia-vacia.png new file mode 100644 index 0000000..5549546 Binary files /dev/null and b/screenshots/07-evidencia-vacia.png differ diff --git a/screenshots/08-reportes-vacio.png b/screenshots/08-reportes-vacio.png new file mode 100644 index 0000000..f4c4132 Binary files /dev/null and b/screenshots/08-reportes-vacio.png differ diff --git a/screenshots/09-proyectos.png b/screenshots/09-proyectos.png new file mode 100644 index 0000000..65cfbd5 Binary files /dev/null and b/screenshots/09-proyectos.png differ diff --git a/screenshots/10-runs.png b/screenshots/10-runs.png new file mode 100644 index 0000000..5f4b9c6 Binary files /dev/null and b/screenshots/10-runs.png differ diff --git a/screenshots/11-run-detalle.png b/screenshots/11-run-detalle.png new file mode 100644 index 0000000..e8fa0a2 Binary files /dev/null and b/screenshots/11-run-detalle.png differ diff --git a/screenshots/12-grafo.png b/screenshots/12-grafo.png new file mode 100644 index 0000000..c86814e Binary files /dev/null and b/screenshots/12-grafo.png differ diff --git a/screenshots/13-grafo-nodo.png b/screenshots/13-grafo-nodo.png new file mode 100644 index 0000000..3f4206d Binary files /dev/null and b/screenshots/13-grafo-nodo.png differ diff --git a/screenshots/14-evidencia.png b/screenshots/14-evidencia.png new file mode 100644 index 0000000..fd74bf4 Binary files /dev/null and b/screenshots/14-evidencia.png differ diff --git a/screenshots/15-assistant.png b/screenshots/15-assistant.png new file mode 100644 index 0000000..81a4ca9 Binary files /dev/null and b/screenshots/15-assistant.png differ diff --git a/screenshots/16-settings-scope.png b/screenshots/16-settings-scope.png new file mode 100644 index 0000000..621b211 Binary files /dev/null and b/screenshots/16-settings-scope.png differ diff --git a/screenshots/17-report-builder.png b/screenshots/17-report-builder.png new file mode 100644 index 0000000..cb33571 Binary files /dev/null and b/screenshots/17-report-builder.png differ