Reportar un issue
·
Contribuir
Etiquetas:
osint
argentina
latam
open-source-intelligence
react
nodejs
# OSINTArgy
OSINTArgy es una plataforma open source para investigaciones OSINT éticas, con foco en Argentina y Latinoamérica. Reúne herramientas, dorks, recursos categorizados y módulos de automatización en una interfaz visual pensada para analistas, periodistas, investigadores, equipos de seguridad y personas que necesitan trabajar con fuentes abiertas de forma ordenada.
La descripción corta del proyecto es: **Plataforma OSINT open source para investigaciones éticas en Argentina y Latinoamérica.**
## Características
- Catálogo curado de herramientas OSINT con categorías, tags, dificultad, región e indicadores de uso.
- Interfaz visual tipo galaxia, vistas alternativas y navegación por categorías.
- Generador de dorks para Google, Yandex, Bing y DuckDuckGo.
- Búsqueda de usernames en múltiples plataformas.
- Módulos para OSINT de emails, análisis de archivos y reconocimiento de infraestructura.
- API REST con Express, MongoDB, autenticación JWT, rate limiting, CORS y logging estructurado.
- Frontend React + Vite con rutas SPA, servicios API y componentes modulares.
## Uso Responsable
OSINTArgy está pensado para investigación sobre fuentes públicas, auditoría defensiva, aprendizaje y documentación. Usalo solo con autorización, respetando leyes aplicables, términos de servicio y privacidad de terceros. El proyecto no promueve intrusión, abuso, acoso, doxxing ni acceso no autorizado.
## Stack
| Capa | Tecnología |
| --- | --- |
| Frontend | React 18, Vite, React Router, D3, Framer Motion, Lucide React |
| Backend | Node.js, Express, Mongoose, JWT, Helmet, Winston |
| Base de datos | MongoDB |
| DevOps | Docker Compose, Nginx, npm scripts |
## Requisitos
- Node.js 20 o superior.
- npm 10 o superior.
- MongoDB 5 o superior para desarrollo local.
- Docker y Docker Compose si preferís levantar el entorno containerizado.
## Instalación Local
git clone https://github.com/IAZARA/OSINTArgy_v01.git
cd OSINTArgy_v01
npm run install:all
Configurá variables de entorno desde los ejemplos:
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
Levantá frontend y backend con el script local:
npm start
URLs por defecto:
| Servicio | URL |
| --- | --- |
| Frontend | http://localhost:5173 |
| Backend API | http://localhost:3001/api |
| Health check | http://localhost:3001/api/health |
También podés correr cada servicio por separado:
cd backend
npm run dev
cd frontend
npm run dev
## Docker
Entorno de desarrollo:
docker compose up --build
Entorno de producción:
cp .env.production.example .env.production
docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build
En producción, reemplazá `MONGO_PASSWORD` y `JWT_SECRET` por valores fuertes antes de levantar los servicios.
También configurá `FRONTEND_URL` con el origen real autorizado para CORS.
## Scripts
| Comando | Descripción |
| --- | --- |
| `npm start` | Inicia frontend y backend con gestión local de puertos. |
| `npm run dev` | Inicia frontend y backend en paralelo. |
| `npm run build` | Genera el build del frontend. |
| `npm run install:all` | Instala dependencias de raíz, frontend y backend. |
| `npm run sync:data` | Regenera `frontend/src/data/tools.json` desde los JSON por categoría. |
| `npm run validate:data` | Valida estructura, IDs, categorías y fallback del catálogo. |
| `npm run check:links` | Revisa URLs externas del catálogo y puede generar reportes JSON/Markdown. |
| `npm run test` | Ejecuta smoke tests de scripts, frontend y backend. |
| `cd frontend && npm run lint` | Ejecuta ESLint sobre el frontend. |
| `npm run clean` | Detiene procesos locales de Vite, Nodemon y Node asociados al proyecto. |
## Estructura
OSINTArgy/
├── backend/ # API Express, modelos, rutas, controladores y scripts de datos
├── frontend/ # Aplicación React + Vite
├── .github/ # CI, CodeQL, Dependabot y plantillas
├── docs/ # Documentación técnica y catálogo
├── docs/assets/ # Branding y recursos visuales del repositorio
├── scripts/ # Scripts auxiliares versionados
├── docker-compose.yml # Entorno Docker de desarrollo
├── docker-compose.prod.yml # Entorno Docker de producción
└── README.md
No se versionan builds, logs, bases locales, `.env`, carpetas MCP ni configuraciones personales. Esos artefactos están cubiertos por `.gitignore` para mantener el historial limpio y reproducible.
## Módulos Principales
| Módulo | Descripción |
| --- | --- |
| Galaxy View | Exploración visual de categorías y herramientas OSINT. |
| Dork Generator | Plantillas y generación de búsquedas avanzadas. |
| Email OSINT | Validación y enriquecimiento inicial de correos. |
| Username OSINT | Búsqueda de presencia de usuarios en plataformas públicas. |
| File Analysis | Extracción de metadatos y análisis de archivos. |
| Infrastructure Scanner | Reconocimiento defensivo de dominios, IPs y servicios. |
| OSINT Academy | Material educativo, lecciones, audio y simuladores. |
## API
Endpoints principales:
GET /api/health
GET /api/tools
GET /api/tools/:id
GET /api/tools/search
POST /api/tools/:id/use
POST /api/auth/register
POST /api/auth/login
GET /api/users/favorites
POST /api/users/favorites/:toolId
DELETE /api/users/favorites/:toolId
GET /api/search/tools
GET /api/search/suggestions
POST /api/dorks/generate
## Datos y Herramientas
Las herramientas se mantienen como JSON en `frontend/src/data/tools/` y datos backend en `backend/src/data/`. Para agregar una herramienta, usá una estructura consistente:
{
"id": "herramienta-unica",
"name": "Nombre de la herramienta",
"description": "Descripción breve",
"url": "https://ejemplo.com",
"category": "categoria-id",
"tags": ["osint", "argentina"],
"type": "web",
"region": "argentina",
"language": "es",
"difficulty_level": "beginner",
"is_free": true,
"requires_registration": false
}
## Calidad del Repositorio
- Mantener secretos y configuraciones locales fuera de Git.
- No commitear `frontend/dist/`, `logs/`, `data/*.db`, `node_modules/`, `.claude/` ni `mcp-*`.
- Validar el catálogo con `npm run validate:data` antes de publicar cambios.
- Sincronizar el fallback con `npm run sync:data` cuando cambie el catálogo.
- Revisar links externos con `npm run check:links -- --report-only --markdown link-check-report.md`.
- Documentar cambios funcionales en el README o en archivos dentro de `docs/`.
- Agregar tests cuando el cambio toque API, autenticación, parsing, carga de datos o flujos de usuario.
- Validar con `npm run build` antes de abrir un PR cuando se modifique frontend.
- La documentación de arquitectura está en [docs/arquitectura.md](docs/arquitectura.md).
## Seguridad
- `JWT_SECRET`, `MONGODB_URI` y `FRONTEND_URL` son obligatorios en producción.
- CORS solo permite orígenes configurados por entorno; localhost queda reservado para desarrollo.
- Las subidas de archivos validan MIME, firma binaria y tamaño máximo.
- El scanner de infraestructura valida dominios, bloquea entradas locales/IP y limita redirecciones.
- El contenido HTML del frontend se sanitiza antes de renderizarse.
- Ejecutar `npm audit --omit=dev` en raíz, `backend/` y `frontend/` antes de publicar cambios.
- Ver [SECURITY.md](SECURITY.md) para reporte responsable y alcance.
## Catálogo
El formato editorial del catálogo está documentado en [docs/catalogo.md](docs/catalogo.md). Usá `npm run sync:data` para actualizar el fallback del frontend y `npm run validate:data` para verificar estructura, IDs únicos, categorías, subcategorías, tipos, indicadores, campos obligatorios y sincronización.
## Automatización
- CI valida catálogo, fallback, tests, build y audits en cada push o PR a `main`.
- CodeQL analiza JavaScript/TypeScript de forma automática.
- Dependabot revisa npm, GitHub Actions y Docker semanalmente.
- Link Check corre semanalmente o manualmente en modo reporte para detectar URLs caídas sin bloquear cambios por fallos transitorios externos.
## Roadmap
- Mejorar cobertura de tests en API y componentes críticos.
- Normalizar datos de herramientas y categorías.
- Agregar documentación técnica de endpoints.
- Incorporar guías de contribución y plantillas de issues.
- Ampliar recursos OSINT específicos para Argentina y LATAM.
## Contribuir
1. Hacé un fork del repositorio.
2. Creá una rama descriptiva: `git checkout -b feature/nombre-del-cambio`.
3. Realizá cambios chicos y revisables.
4. Revisá [CONTRIBUTING.md](CONTRIBUTING.md).
5. Ejecutá build o tests según corresponda.
6. Abrí un Pull Request con contexto, capturas si aplica y pasos de verificación.
## Licencia
Este proyecto se distribuye bajo licencia MIT. Ver [LICENSE](LICENSE).
## Autor
**Ivan Agustin Zarate**
- GitHub: [IAZARA](https://github.com/IAZARA)
- LinkedIn: [ivan-agustin-zarate](https://www.linkedin.com/in/ivan-agustin-zarate/)
- Email: [osintargy@gmail.com](mailto:osintargy@gmail.com)
OSINTArgy busca aportar herramientas abiertas, trazables y útiles para la comunidad OSINT hispanohablante.