Arquitectura

Demo

🇬🇧 Read this in English

PassiveSubEnum 🔍

Enumeración pasiva de subdominios cruzando crt.sh, RapidDNS y Wayback Machine — sin enviar un solo paquete al objetivo.

---

Índice

1. Descripción
2. Motivación
3. Arquitectura
4. Fuentes de datos
5. Instalación
6. Uso
7. Ejemplos reales
8. Formato de salida
9. OSINT & MITRE ATT&CK
10. Tests
11. Consideraciones éticas
12. Contribuir
13. Licencia

---

Descripción

PassiveSubEnum es una herramienta CLI open-source de reconocimiento pasivo que automatiza la enumeración de subdominios combinando tres fuentes públicas complementarias:

• crt.sh — registros de transparencia de certificados TLS/SSL
• RapidDNS — base de datos de resoluciones DNS históricas
• Wayback Machine CDX API — URLs archivadas por Internet Archive

Al cruzar y deduplicar las tres fuentes, PassiveSubEnum maximiza la cobertura de subdominios conocidos sin generar ningún tráfico directo hacia el objetivo, respetando por completo los límites del reconocimiento pasivo.

---

Motivación

Durante trabajos de auditoría y fases de reconocimiento en Bug Bounty, la primera pregunta siempre es: ¿cuál es la superficie de ataque real de este dominio? Las herramientas activas como nmap o amass en modo activo son ruidosas y pueden alertar los IDS del objetivo. La alternativa pasiva, consultando fuentes abiertas, ofrece una imagen sorprendentemente completa con riesgo legal y operativo mínimo.

PassiveSubEnum nació para resolver ese problema de forma rápida, combinada y reproducible.

---

Arquitectura

graph TD
  A[Dominio objetivo] --> B[Orquestador async]
  B --> C[crt.sh API]
  B --> D[RapidDNS scraper]
  B --> E[Wayback CDX API]
  C --> F[Parser & dedup]
  D --> F
  E --> F
  F --> G[Validador DNS pasivo]
  G --> H[Reporter]
  H --> I[Tabla Rich / JSON / TXT]

Loading

Todos los módulos se ejecutan en paralelo con asyncio + httpx. El flujo es:

1. El orquestador lanza las tres consultas simultáneamente.
2. Cada módulo parsea su respuesta y devuelve un set de subdominios normalizados.
3. El deduplicador cruza los tres sets y etiqueta el origen de cada resultado.
4. El validador DNS consulta únicamente registros públicos en caché (sin tocar el objetivo).
5. El reporter genera la salida en consola (tabla Rich) y, opcionalmente, JSON o TXT.

---

Fuentes de datos

Fuente	Endpoint	Tipo	Límite gratuito
crt.sh	https://crt.sh/?q=%25.DOMINIO&output=json	API JSON	Sin clave
RapidDNS	https://rapiddns.io/subdomain/DOMINIO?full=1	HTML scraping	Sin clave
Wayback CDX	http://web.archive.org/cdx/search/cdx?...	API JSON	Sin clave

Ninguna fuente requiere API key. Todas son de acceso público.

---

Instalación

Requisitos previos

• Python 3.11 o superior
• pip o pipenv

Pasos

# 1. Clonar el repositorio
git clone https://github.com/javier-garrido-ortiz/passive-subdomain-enum.git
cd passive-subdomain-enum

# 2. Crear entorno virtual (recomendado)
python -m venv .venv
source .venv/bin/activate        # Linux/macOS
# .venv\Scripts\activate          # Windows

# 3. Instalar dependencias
pip install -r requirements.txt

Verificar instalación

python src/main.py --help

---

Uso

uso: main.py [-h] -d DOMINIO [-o SALIDA] [-f {json,txt,ambos}] [--no-dns] [--timeout SEG] [-v]

Argumentos obligatorios:
  -d, --domain DOMINIO     Dominio objetivo (ej: example.com)

Argumentos opcionales:
  -o, --output FICHERO     Ruta del fichero de salida (sin extensión)
  -f, --format {json,txt}  Formato de exportación (defecto: json)
  --no-dns                 Omitir resolución DNS pasiva
  --timeout SEG            Timeout por fuente en segundos (defecto: 15)
  -v, --verbose            Mostrar logs detallados
  -h, --help               Mostrar esta ayuda

---

Ejemplos reales

Escaneo básico con salida en consola

python src/main.py -d example.com

Exportar a JSON

python src/main.py -d example.com -o resultados -f json

Exportar a TXT (lista limpia para usar con otras herramientas)

python src/main.py -d example.com -o subdominios -f txt

Solo enumerar, sin resolución DNS

python src/main.py -d example.com --no-dns

Encadenar con otras herramientas

# Pasar la lista a httpx para comprobar servicios web activos
python src/main.py -d example.com -o subs -f txt && cat subs.txt | httpx -silent

---

Formato de salida

JSON (resultados.json)

{
  "meta": {
    "dominio": "example.com",
    "fecha": "2026-05-24T10:32:11",
    "total": 47,
    "resuelven": 41
  },
  "subdominios": [
    {
      "subdominio": "api.example.com",
      "ip": "93.184.216.34",
      "fuentes": ["crt.sh", "RapidDNS", "Wayback"],
      "resuelve": true
    }
  ]
}

TXT (subdominios.txt)

api.example.com
auth.example.com
cdn.example.com
...

---

OSINT & MITRE ATT&CK

Esta herramienta implementa técnicas descritas en el framework MITRE ATT&CK for Enterprise:

Técnica	ID	Descripción
Gather Victim Network Information	T1590	Recopilación de información de red del objetivo
DNS / Passive DNS	T1590.002	Uso de registros DNS históricos y pasivos
Search Open Technical Databases	T1596	Consulta de bases de datos técnicas abiertas
Digital Certificates	T1596.003	Explotación de logs de transparencia de certificados

Referencia: https://attack.mitre.org/techniques/T1590/

---

Tests

# Ejecutar toda la suite
pytest tests/ -v

# Con cobertura
pytest tests/ -v --cov=src --cov-report=term-missing

Los tests usan respuestas mockeadas para no depender de conectividad externa.

---

Consideraciones éticas

⚠️ AVISO IMPORTANTE

PassiveSubEnum está diseñado exclusivamente para:

• Auditorías de seguridad sobre sistemas propios o con permiso escrito del propietario.
• Programas de Bug Bounty donde el dominio está en scope.
• Fines educativos y de investigación en entornos controlados.

El uso de esta herramienta sobre sistemas sin autorización expresa puede constituir un delito según la legislación vigente (art. 197 bis y ss. del Código Penal español, CFAA en EE.UU., etc.). El autor no se responsabiliza del uso indebido.

---

Contribuir

1. Haz un fork del repositorio.
2. Crea una rama: git checkout -b feat/nueva-fuente
3. Haz tus cambios y añade tests.
4. Abre un Pull Request describiendo los cambios.

Sugerencias bienvenidas: nuevas fuentes (VirusTotal, SecurityTrails, AlienVault OTX), exportación a CSV, integración con Shodan...

---

Licencia

Distribuido bajo licencia MIT. Consulta el fichero LICENSE para más detalles.

---

Desarrollado por Javier Garrido Ortiz — Técnico DAM · Máster en Ciberseguridad