Coeus CI

Inteligencia Competitiva que lo ve todo.

Nombrado en honor a Coeus (SEE-us), el Titán griego de los cien ojos de la mente inquisitiva — cuyo nombre significa literalmente "indagar". CI significa Inteligencia Competitiva.

Una herramienta OSINT de inteligencia empresarial que construye perfiles de empresas a partir de fuentes de datos públicas gratuitas. Dale un dominio — obtén un informe puntuado que cubre estabilidad, crecimiento, madurez tecnológica, salud financiera, postura de seguridad y transparencia.

Inicio rápido

# Clonar e instalar
git clone https://github.com/Opfour/coeus-ci.git
cd coeus-ci
./setup.sh          # crea venv, instala todo

# Activar el entorno
source venv/bin/activate

# Ejecutar un análisis
coeus apple.com

# Comparar empresas
coeus apple.com microsoft.com

# Exportar informe HTML
coeus apple.com --html

# Lanzar panel web
coeus --web

Uso

coeus [OPCIONES] [OBJETIVOS]...

Opciones:
  --json                 Salida como JSON
  --html                 Guardar informe HTML en ./reports/
  -m, --modules TEXTO    Lista de módulos separados por comas (ej. whois,dns,edgar)
  -t, --timeout ENTERO   Tiempo de espera por módulo en segundos (predeterminado: 30)
  --web                  Iniciar panel web interactivo
  --port ENTERO          Puerto del panel web (predeterminado: 8147)
  --help                 Mostrar este mensaje y salir

Ejemplos

# Un solo objetivo
coeus acme.com

# Salida JSON (tubería a jq, guardar en archivo, etc.)
coeus acme.com --json

# Ejecutar solo módulos específicos
coeus acme.com --modules whois,dns,ssl

# Comparación lado a lado
coeus apple.com microsoft.com

# Informe HTML guardado en ./reports/
coeus apple.com --html

# Panel web en puerto predeterminado
coeus --web

# Panel web en puerto personalizado
coeus --web --port 9090

Configuración

La configuración predeterminada está definida en un lugar para facilitar su modificación:

coeus/__init__.py

DEFAULT_WEB_PORT = 8147          # --port: puerto del panel web
DEFAULT_TIMEOUT = 30             # --timeout: tiempo de espera por módulo (segundos)
DEFAULT_HOST = "127.0.0.1"      # dirección de enlace para el panel web

Cambia estos valores para establecer nuevos valores predeterminados para tu entorno. Los indicadores de CLI (--port, --timeout) los reemplazan en cada ejecución.

Fuentes de datos (v0.1)

Todos los módulos son gratuitos y no requieren clave API.

Puntuación

Cada objetivo se puntúa en seis dimensiones (0-10):

Formatos de salida

• Terminal — Tarjeta de puntuación con formato enriquecido, barras de colores, hallazgos, detalles de módulos
• JSON (--json) — Volcado completo del modelo Pydantic para canalización o integración
• HTML (--html) — Informe autónomo con tema oscuro guardado en ./reports/
• Panel web (--web) — Interfaz de navegador interactiva con progreso de escaneo en vivo

Arquitectura

coeus-ci/
├── coeus/
│   ├── __init__.py          # Versión + valores predeterminados configurables (puerto, tiempo de espera, host)
│   ├── __main__.py          # Punto de entrada python -m coeus
│   ├── cli.py               # CLI con Click y modo de comparación
│   ├── core.py              # Orquestador asíncrono de dos oleadas
│   ├── models.py            # Modelos de datos Pydantic
│   ├── scorer.py            # Motor de puntuación ponderada
│   ├── report.py            # Formateadores de terminal, JSON y HTML
│   ├── matching.py          # Coincidencia difusa de nombres de empresa
│   ├── web.py               # Servidor de panel web aiohttp
│   └── modules/
│       ├── base.py          # Clase base ABC para módulos
│       ├── whois_mod.py     # Consulta WHOIS
│       ├── dns_mod.py       # Análisis DNS
│       ├── headers.py       # Análisis de cabeceras HTTP
│       ├── ssl_mod.py       # Inspección de certificados TLS
│       ├── tech.py          # Detección de pila tecnológica
│       ├── edgar.py         # Declaraciones SEC EDGAR
│       ├── nonprofit.py     # 501(c)(3) / ProPublica
│       └── dba.py           # DBA / OpenCorporates
├── templates/
│   ├── dashboard.html       # SPA del panel web
│   └── report.html          # Plantilla de informe HTML Jinja2
├── setup.sh                 # Script de configuración única
├── pyproject.toml           # Empaquetado Python
├── LICENSE                  # AGPL-3.0
└── README.md

Cómo funciona

1. Oleada 1 — WHOIS y SSL se ejecutan primero para identificar el nombre de la empresa
2. Oleada 2 — Todos los demás módulos se ejecutan en paralelo usando el nombre de empresa de la Oleada 1
3. Puntuación — Cada módulo contribuye con puntuaciones ponderadas a las seis dimensiones
4. Informe — Los resultados se agregan en un único informe puntuado

Preguntas frecuentes

¿Cómo cambio el puerto predeterminado del panel web?

Edita coeus/__init__.py y cambia DEFAULT_WEB_PORT, o usa el indicador --port:

coeus --web --port 9090

¿Cómo cambio el tiempo de espera predeterminado?

Edita coeus/__init__.py y cambia DEFAULT_TIMEOUT, o usa el indicador --timeout:

coeus apple.com --timeout 60

¿Necesito claves API?

No. Todos los módulos v0.1 utilizan fuentes de datos públicas gratuitas sin necesidad de claves API.

¿Por qué EDGAR muestra 0.0 para algunas empresas?

El módulo EDGAR solo encuentra datos de empresas públicas registradas en la SEC. Las empresas privadas, organizaciones sin fines de lucro y entidades extranjeras no tendrán datos de EDGAR — esto es esperado, no un error.

¿Por qué el módulo de organizaciones sin fines de lucro a veces coincide con la organización equivocada?

Los nombres comunes de empresas (como "Apple") pueden coincidir con pequeñas organizaciones sin fines de lucro con nombres similares. La coincidencia difusa reduce falsos positivos, pero los nombres muy genéricos son inherentemente ambiguos. El indicador --modules te permite omitir módulos que no sean relevantes.

¿Puedo ejecutar solo módulos específicos?

Sí:

coeus apple.com --modules whois,dns,ssl

¿Cómo agrego un nuevo módulo?

1. Crea un nuevo archivo en coeus/modules/ que extienda BaseModule
2. Implementa el método execute(target, context)
3. Regístralo en coeus/modules/__init__.py

Hoja de ruta

v0.1 — Base (actual)

• Pipeline de inteligencia de 8 módulos (whois, dns, headers, ssl, tech, edgar, nonprofit, dba)
• Motor de puntuación de seis dimensiones
• Salida de terminal, JSON y HTML
• Panel web con progreso de escaneo en vivo
• Modo de comparación para múltiples objetivos
• Coincidencia difusa de nombres de empresa

v0.2 — Expansión

• Capa de caché (no volver a obtener datos dentro de 24h)
• Modo por lotes (coeus --file targets.txt)
• Limitación de tasa y lógica de reintento
• Integración de clave API para fuentes de datos premium
• Módulos de Hunter.io, BuiltWith, Crunchbase, GitHub, Shodan

v0.3 — Pulido

• Exportación de informes PDF
• Seguimiento histórico (comparar análisis a lo largo del tiempo)
• Sistema de complementos para módulos comunitarios
• Integración CI/CD (códigos de salida basados en umbrales de puntuación)

Licencia

AGPL-3.0 — consulta LICENSE para más detalles.