Coeus CI

Intelligence competitiva che vede tutto.

Chiamato così in onore di Coeus (si pronuncia SEE-us), il Titano greco dai cento occhi dalla mente indagatrice — il cui nome significa letteralmente "interrogare". CI sta per Competitive Intelligence.

Uno strumento OSINT di business intelligence che costruisce profili aziendali da fonti di dati pubbliche e gratuite. Fornisci un dominio — ottieni un report con punteggi che copre stabilità, crescita, maturità tecnologica, salute finanziaria, postura di sicurezza e trasparenza.

Avvio rapido

# Clone and install
git clone https://github.com/Opfour/coeus-ci.git
cd coeus-ci
./setup.sh          # creates venv, installs everything

# Activate the environment
source venv/bin/activate

# Run a scan
coeus apple.com

# Compare companies
coeus apple.com microsoft.com

# Export HTML report
coeus apple.com --html

# Launch web dashboard
coeus --web

Utilizzo

coeus [OPTIONS] [TARGETS]...

Options:
  --json                 Output as JSON
  --html                 Save HTML report to ./reports/
  -m, --modules TEXT     Comma-separated module list (e.g., whois,dns,edgar)
  -t, --timeout INTEGER  Per-module timeout in seconds (default: 30)
  --web                  Launch interactive web dashboard
  --port INTEGER         Web dashboard port (default: 8147)
  --help                 Show this message and exit

Esempi

# Single target
coeus acme.com

# JSON output (pipe to jq, save to file, etc.)
coeus acme.com --json

# Run only specific modules
coeus acme.com --modules whois,dns,ssl

# Side-by-side comparison
coeus apple.com microsoft.com

# HTML report saved to ./reports/
coeus apple.com --html

# Web dashboard on default port
coeus --web

# Web dashboard on custom port
coeus --web --port 9090

Configurazione

Le impostazioni predefinite sono definite in un unico punto per una facile modifica:

coeus/__init__.py

DEFAULT_WEB_PORT = 8147          # --port: web dashboard port
DEFAULT_TIMEOUT = 30             # --timeout: per-module timeout (seconds)
DEFAULT_HOST = "127.0.0.1"      # bind address for web dashboard

Modifica questi valori per impostare nuovi default per il tuo ambiente. I flag della CLI (--port, --timeout) hanno la precedenza a ogni esecuzione.

Fonti di dati (v0.1)

Tutti i moduli sono gratuiti e non richiedono chiavi API.

Punteggio

Ogni obiettivo viene valutato su sei dimensioni (0-10):

Formati di output

• Terminale — Scheda di valutazione formattata con barre colorate, risultati e dettagli dei moduli
• JSON (--json) — Dump completo del modello Pydantic per piping o integrazione
• HTML (--html) — Report autonomo a tema scuro salvato in ./reports/
• Dashboard Web (--web) — Interfaccia browser interattiva con avanzamento della scansione in tempo reale

Architettura

coeus-ci/
├── coeus/
│   ├── __init__.py          # Version + configurable defaults (port, timeout, host)
│   ├── __main__.py          # python -m coeus entry
│   ├── cli.py               # Click CLI with comparison mode
│   ├── core.py              # Two-wave async orchestrator
│   ├── models.py            # Pydantic data models
│   ├── scorer.py            # Weighted scoring engine
│   ├── report.py            # Terminal, JSON, HTML formatters
│   ├── matching.py          # Fuzzy company name matching
│   ├── web.py               # aiohttp web dashboard server
│   └── modules/
│       ├── base.py          # ABC base class for modules
│       ├── whois_mod.py     # WHOIS lookup
│       ├── dns_mod.py       # DNS analysis
│       ├── headers.py       # HTTP header analysis
│       ├── ssl_mod.py       # TLS certificate inspection
│       ├── tech.py          # Tech stack detection
│       ├── edgar.py         # SEC EDGAR filings
│       ├── nonprofit.py     # 501(c)(3) / ProPublica
│       └── dba.py           # DBA / OpenCorporates
├── templates/
│   ├── dashboard.html       # Web dashboard SPA
│   └── report.html          # Jinja2 HTML report template
├── setup.sh                 # One-time setup script
├── pyproject.toml           # Python packaging
├── LICENSE                  # AGPL-3.0
└── README.md

Come funziona

1. Onda 1 — WHOIS e SSL vengono eseguiti per primi per identificare il nome dell'azienda
2. Onda 2 — Tutti gli altri moduli vengono eseguiti in parallelo usando il nome dell'azienda dell'Onda 1
3. Punteggio — Ogni modulo contribuisce con punteggi ponderati alle sei dimensioni
4. Report — I risultati vengono aggregati in un unico report con punteggio

FAQ

Come cambio la porta predefinita della dashboard web?

Modifica coeus/__init__.py e cambia DEFAULT_WEB_PORT, oppure usa il flag --port:

coeus --web --port 9090

Come cambio il timeout predefinito?

Modifica coeus/__init__.py e cambia DEFAULT_TIMEOUT, oppure usa il flag --timeout:

coeus apple.com --timeout 60

Servono chiavi API?

No. Tutti i moduli v0.1 utilizzano fonti di dati pubbliche e gratuite senza bisogno di chiavi API.

Perché EDGAR mostra 0.0 per alcune aziende?

Il modulo EDGAR trova dati solo per le società pubbliche registrate presso la SEC. Società private, organizzazioni no-profit ed entità estere non avranno dati EDGAR — è previsto, non è un errore.

Perché il modulo nonprofit a volte trova un'organizzazione sbagliata?

Nomi aziendali comuni (come "Apple") possono corrispondere a piccole organizzazioni no-profit con nomi simili. Il fuzzy matching riduce i falsi positivi, ma i nomi molto generici sono intrinsecamente ambigui. Il flag --modules consente di saltare i moduli non pertinenti.

Posso eseguire solo moduli specifici?

Sì:

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

Come aggiungo un nuovo modulo?

1. Crea un nuovo file in coeus/modules/ che estende BaseModule
2. Implementa il metodo execute(target, context)
3. Registralo in coeus/modules/__init__.py

Roadmap

v0.1 — Fondamenta (attuale)

• Pipeline di intelligence a 8 moduli (whois, dns, headers, ssl, tech, edgar, nonprofit, dba)
• Motore di punteggio a sei dimensioni
• Output terminale, JSON e HTML
• Dashboard web con avanzamento della scansione in tempo reale
• Modalità di confronto per più obiettivi
• Corrispondenza fuzzy dei nomi aziendali

v0.2 — Espansione

• Livello di caching (non ri-richiedere entro 24 ore)
• Modalità batch (coeus --file targets.txt)
• Limitazione della frequenza e logica di retry
• Integrazione di chiavi API per fonti di dati premium
• Moduli Hunter.io, BuiltWith, Crunchbase, GitHub, Shodan

v0.3 — Rifinitura

• Esportazione del report in PDF
• Tracciamento storico (confronto delle scansioni nel tempo)
• Sistema di plugin per moduli della community
• Integrazione CI/CD (codici di uscita basati su soglie di punteggio)

Licenza

AGPL-3.0 — consulta LICENSE per i dettagli.