From 78b565ecfd0a4611d58eb578d055fd78c0a08fed Mon Sep 17 00:00:00 2001 From: m3t4l|unx Date: Thu, 25 Jun 2026 03:41:49 -0700 Subject: [PATCH 01/23] Update gitignore for Python and secrets --- .gitignore | 47 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index 499ed7e..c9dabf6 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,47 @@ +# Python cache +__pycache__/ +*.py[cod] +*$py.class + +# Virtual environments venv/ +.venv/ +env/ +ENV/ + +# Python build files +build/ +dist/ +*.egg-info/ +.eggs/ + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Local config / API keys .env -__pycache__/ -*.pyc +*.env +config.json +secrets.json +keys.json +.mx_osint_config.json +*.key +*.pem + +# OS junk +.DS_Store +Thumbs.db + +# Reports / generated output +reports/ output/ -data/ +results/ +*.log +*.html + +# IDE/editor files +.vscode/ +.idea/ +*.swp +*.swo From 7a7d6afd2db600a088e532737d9fef787196cf6e Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 25 Jun 2026 03:50:53 -0700 Subject: [PATCH 02/23] Add MeXiCOSINT launcher --- bin/mexicosint | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 bin/mexicosint diff --git a/bin/mexicosint b/bin/mexicosint new file mode 100644 index 0000000..e979203 --- /dev/null +++ b/bin/mexicosint @@ -0,0 +1,11 @@ +#!/usr/bin/env bash + +# MeXiCOSINT launcher +# This lets users run the tool without typing the full Python filename. + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" + +cd "$REPO_ROOT" || exit 1 + +python3 "$REPO_ROOT/mexicosint_v2.2.5.py" "$@" From 449f3343d52ba7247799fda69e0f8b7af7c70c3e Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 25 Jun 2026 03:55:28 -0700 Subject: [PATCH 03/23] Update README.md --- README.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 611b142..fa0eada 100644 --- a/README.md +++ b/README.md @@ -17,15 +17,26 @@ Herramienta de OSINT para numeros telefonicos Mexicanos. ## Instalacion -git clone https://github.com/metalpunx666/MeXiCOSINT.git +git clone https://github.com/KiMiGuel/MeXiCOSINT.git + cd MeXiCOSINT + python3 -m venv venv + source venv/bin/activate + pip install -r requirements.txt +## Ejecutar con launcher + +Después de instalar las dependencias, puedes ejecutar MeXiCOSINT con: + +```bash +bash bin/mexicosint + ## Uso -python3 mexicosint_v2.2.5.py +python3 bash bin/mexicosint ## Modulos From 845ea9d347dbb05ed3be272022edb6856fd3ed4c Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 25 Jun 2026 04:01:32 -0700 Subject: [PATCH 04/23] Update README.md --- README.md | 198 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 173 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index fa0eada..fc2c854 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,201 @@ -![MeXiCOSINT Banner](mexsint.png) +

+ MeXiCOSINT Banner +

-![Python](https://img.shields.io/badge/Python-3.8+-blue.svg) -![License](https://img.shields.io/badge/License-MIT-green.svg) -![OSINT](https://img.shields.io/badge/OSINT-Mexico-red.svg) +

+ Python + Licencia + OSINT México + Estado Beta +

-## Tabla de Contenidos -- [Instalación](#instalación) -- [Uso](#uso) -- [Módulos](#módulos) -- [Dependencias](#dependencias) -- [Nota](#nota) +

MeXiCOSINT

-# MeXiCOSINT +

+ Herramienta OSINT enfocada en análisis, validación, enriquecimiento y reportes de números telefónicos mexicanos. +

-Herramienta de OSINT para numeros telefonicos Mexicanos. +--- -## Instalacion +## Descripción +**MeXiCOSINT** es una herramienta de OSINT desarrollada en Python y enfocada en números telefónicos mexicanos. + +La herramienta puede validar números, analizar formatos mexicanos, consultar fuentes opcionales mediante API, procesar metadatos disponibles y generar resultados útiles para investigación autorizada. + +> Este proyecto está en fase beta. Los resultados deben tratarse como indicadores OSINT, no como evidencia absoluta. + +--- + +## Características + +- Validación de números telefónicos mexicanos +- Formato nacional e internacional +- Análisis local de números mexicanos +- Enriquecimiento opcional mediante APIs externas +- Procesamiento relacionado con IFT/SNS +- Soporte para módulo QuienHabla.mx +- Launcher para ejecutar la herramienta sin escribir el nombre completo del script +- Configuración local de API keys +- Soporte para reportes o salidas generadas según la versión + +--- + +## Estructura del repositorio + +```text +MeXiCOSINT/ +├── bin/ +│ └── mexicosint +├── data/ +├── docs/ +│ ├── INSTALL.md +│ ├── USAGE.md +│ └── CONFIG.md +├── modules/ +│ ├── ift_sns.py +│ ├── local_parser.py +│ └── quienhabla.py +├── mexicosint_v2.2.5.py +├── requirements.txt +├── .gitignore +├── LICENSE +└── README.md +``` + +--- + +## Instalación + +Clona el repositorio: + +```bash git clone https://github.com/KiMiGuel/MeXiCOSINT.git +``` +Entra a la carpeta del proyecto: + +```bash cd MeXiCOSINT +``` + +Crea un entorno virtual: +```bash python3 -m venv venv +``` + +Activa el entorno virtual: +```bash source venv/bin/activate +``` +Instala las dependencias: + +```bash pip install -r requirements.txt +``` + +--- -## Ejecutar con launcher +## Uso -Después de instalar las dependencias, puedes ejecutar MeXiCOSINT con: +Ejecuta MeXiCOSINT usando el launcher: ```bash bash bin/mexicosint +``` -## Uso +Esto evita tener que escribir manualmente el nombre completo del archivo principal de Python. + +También puedes ejecutar el script principal directamente: + +```bash +python3 mexicosint_v2.2.5.py +``` + +--- + +## Documentación + +| Guía | Descripción | +|---|---| +| [Guía de instalación](docs/INSTALL.md) | Instrucciones de instalación para Kali, Debian, Ubuntu y sistemas similares | +| [Guía de uso](docs/USAGE.md) | Uso básico y notas de ejecución | +| [Guía de configuración](docs/CONFIG.md) | Configuración local y manejo de API keys | + +--- + +## APIs opcionales + +Algunas funciones pueden depender de API keys externas. + +| Servicio | Función | +|---|---| +| AbstractAPI | Validación y enriquecimiento de números telefónicos | +| NumVerify | Validación secundaria de números | +| Shodan | Enriquecimiento opcional relacionado con servicios expuestos | +| IPInfo | Enriquecimiento de metadatos IP | +| IP2Location | Enriquecimiento de metadatos IP | +| OpenCage | Geocodificación y soporte para mapas | + +Las API keys deben mantenerse en tu entorno local. No las subas a GitHub. + +--- + +## Seguridad + +No subas archivos como: + +```text +.env +*.env +config.json +secrets.json +keys.json +.mx_osint_config.json +``` + +Ruta local recomendada para configuración: + +```text +~/.mx_osint_config.json +``` + +Permisos recomendados: + +```bash +chmod 600 ~/.mx_osint_config.json +``` + +--- + +## Advertencia + +**MeXiCOSINT** está diseñado para investigación autorizada, autoauditoría y flujos educativos de OSINT. + +No uses esta herramienta para acoso, doxxing, fraude, amenazas o actividades no autorizadas. + +La herramienta no garantiza identidad, ubicación exacta, propiedad ni atribución definitiva de un número telefónico. + +--- -python3 bash bin/mexicosint +## Estado del proyecto -## Modulos +Este proyecto está en desarrollo activo. -- local_parser.py - Validacion y parsing de numeros mexicanos -- quienhabla.py - Integracion con QuienHabla.mx -- ift_sns.py - Procesamiento de datos IFT/SNS +Funciones planeadas: -## Dependencias +- Empaquetado instalable +- Comando global `mexicosint` +- Publicación de releases en GitHub +- Paquete `.deb` para instalación local con `apt` +- Mejoras en documentación +- Más pruebas y validaciones internas -requests, beautifulsoup4, phonenumbers, python-dotenv, lxml +--- -## Nota +## Licencia -No subas tu .env al repositorio. +Este proyecto se publica bajo la licencia incluida en este repositorio. From 68ab83e94fef705562d3de3f084f736fe6018160 Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 25 Jun 2026 04:04:17 -0700 Subject: [PATCH 05/23] Update INSTALL.md --- docs/INSTALL.md | 195 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 173 insertions(+), 22 deletions(-) diff --git a/docs/INSTALL.md b/docs/INSTALL.md index e369316..97d36c4 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -6,67 +6,218 @@ Esta guía explica cómo instalar **MeXiCOSINT** en Kali Linux, Debian, Ubuntu y ## Requisitos -Antes de instalar, asegúrate de tener: +Antes de instalar MeXiCOSINT, asegúrate de tener instalados los paquetes básicos necesarios: - Python 3 - pip -- git - venv +- git -Instala los requisitos base: +Instala los requisitos base con: ```bash sudo apt update +``` + +```bash sudo apt install -y python3 python3-pip python3-venv git -Instalación +``` + +--- -Clona el repositorio: +## Clonar el repositorio -git clone https://github.com/metalpunx666/MeXiCOSINT.git +Clona el repositorio desde GitHub: -Entra al directorio: +```bash +git clone https://github.com/KiMiGuel/MeXiCOSINT.git +``` + +Entra a la carpeta del proyecto: +```bash cd MeXiCOSINT +``` + +--- + +## Crear entorno virtual -Crea un entorno virtual: +Se recomienda usar un entorno virtual para evitar conflictos con paquetes del sistema. +Crea el entorno virtual: + +```bash python3 -m venv venv +``` Activa el entorno virtual: +```bash source venv/bin/activate +``` -Instala las dependencias: +Cuando el entorno virtual esté activo, tu terminal debería mostrar algo parecido a: + +```text +(venv) usuario@equipo:~/MeXiCOSINT$ +``` + +--- +## Instalar dependencias + +Instala las dependencias del proyecto: + +```bash pip install -r requirements.txt -Uso básico +``` + +Si todo sale correctamente, MeXiCOSINT estará listo para ejecutarse. + +--- + +## Ejecutar MeXiCOSINT + +La forma recomendada es usar el launcher incluido: -Ejecuta la herramienta: +```bash +bash bin/mexicosint +``` + +También puedes ejecutar directamente el archivo principal: +```bash python3 mexicosint_v2.2.5.py -Configuración de API keys +``` -La herramienta puede crear o usar un archivo de configuración local para guardar tus claves de API. +--- + +## Configuración de API keys -El archivo de configuración local no debe subirse a GitHub. +MeXiCOSINT puede usar API keys externas para mejorar los resultados. -Ejemplo recomendado: +El archivo recomendado para configuración local es: +```text ~/.mx_osint_config.json +``` + +Este archivo debe quedarse en tu computadora. + +No debe subirse a GitHub. + +--- -Protege el archivo: +## Proteger archivo de configuración +Para proteger el archivo de configuración local: + +```bash chmod 600 ~/.mx_osint_config.json -Actualizar MeXiCOSINT +``` + +--- + +## Actualizar MeXiCOSINT Para actualizar el repositorio: +```bash git pull +``` + +Si las dependencias cambiaron, vuelve a ejecutar: + +```bash +pip install -r requirements.txt +``` + +--- + +## Salir del entorno virtual + +Cuando termines de usar la herramienta: + +```bash +deactivate +``` + +--- + +## Instalación rápida -Después, actualiza dependencias si cambian: +Resumen completo: +```bash +sudo apt update +sudo apt install -y python3 python3-pip python3-venv git +git clone https://github.com/KiMiGuel/MeXiCOSINT.git +cd MeXiCOSINT +python3 -m venv venv +source venv/bin/activate pip install -r requirements.txt -Notas -No subas API keys al repositorio. -Usa la herramienta únicamente en investigaciones autorizadas. -Los resultados deben tratarse como indicadores OSINT, no como evidencia definitiva. +bash bin/mexicosint +``` + +--- + +## Notas importantes + +- No subas API keys a GitHub. +- Usa un entorno virtual para evitar romper paquetes del sistema. +- Si estás en Kali Linux moderno, evita instalar paquetes Python globalmente con `sudo pip`. +- Los resultados OSINT deben verificarse con más de una fuente. +- La herramienta está pensada para investigación autorizada, autoauditoría y fines educativos. + +--- + +## Problemas comunes + +### `python3: command not found` + +Instala Python: + +```bash +sudo apt install -y python3 +``` + +### `pip: command not found` + +Instala pip: + +```bash +sudo apt install -y python3-pip +``` + +### Error creando el entorno virtual + +Instala venv: + +```bash +sudo apt install -y python3-venv +``` + +### Error de permisos + +Asegúrate de estar dentro de la carpeta del proyecto y de tener permisos sobre los archivos. + +```bash +pwd +``` + +```bash +ls -la +``` + +--- + +## Estado + +Si la instalación terminó correctamente, deberías poder ejecutar: + +```bash +bash bin/mexicosint +``` + +Y ver el inicio de MeXiCOSINT en la terminal. From 635d5c6c2c9f9f5c2d1fb9b7ce5dc6a3fe0c1569 Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 25 Jun 2026 04:07:06 -0700 Subject: [PATCH 06/23] Update USAGE.md --- docs/USAGE.md | 287 ++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 254 insertions(+), 33 deletions(-) diff --git a/docs/USAGE.md b/docs/USAGE.md index 1bcc175..1c7daee 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -1,82 +1,303 @@ # Guía de uso -Esta guía explica el uso básico de **MeXiCOSINT**. +Esta guía explica cómo ejecutar y usar **MeXiCOSINT** después de instalarlo. --- -## Ejecutar la herramienta +## Antes de empezar -Desde la carpeta del repositorio: +Asegúrate de estar dentro de la carpeta del proyecto: ```bash cd MeXiCOSINT +``` Activa el entorno virtual: +```bash source venv/bin/activate +``` + +Si el entorno virtual está activo, tu terminal debería mostrar algo parecido a: + +```text +(venv) usuario@equipo:~/MeXiCOSINT$ +``` + +--- + +## Ejecutar MeXiCOSINT -Ejecuta el script: +La forma recomendada es usar el launcher incluido: + +```bash +bash bin/mexicosint +``` +También puedes ejecutar directamente el archivo principal: + +```bash python3 mexicosint_v2.2.5.py -Flujo básico +``` + +--- -La herramienta solicitará un número telefónico mexicano para analizar. +## Formato recomendado del número + +MeXiCOSINT está enfocado en números telefónicos mexicanos. Formato recomendado: +```text +52XXXXXXXXXX +``` -También puedes probar con formato nacional: +También puede aceptar formato nacional de 10 dígitos: +```text XXXXXXXXXX -Resultados +``` + +Ejemplo de formato internacional: -MeXiCOSINT puede mostrar información como: +```text ++525512345678 +``` -Validez del número -Formato nacional e internacional -Región o referencia LADA -Operador o fuente asociada, si está disponible -Resultados de APIs configuradas -Consenso aproximado entre fuentes -Reporte exportable, si la opción está disponible -Reportes +Ejemplo de formato nacional: -Si la herramienta genera reportes, revisa la carpeta del proyecto después de ejecutarla. +```text +5512345678 +``` -Ejemplos de posibles archivos generados: +--- + +## Flujo básico de uso + +1. Ejecuta la herramienta: + +```bash +bash bin/mexicosint +``` + +2. Ingresa el número telefónico cuando la herramienta lo solicite. + +3. Revisa los resultados mostrados en terminal. + +4. Si la herramienta genera reportes, revisa los archivos creados dentro del proyecto. + +--- + +## Resultados posibles + +Dependiendo de la versión, configuración y API keys disponibles, MeXiCOSINT puede mostrar información como: + +* Validación del número +* Formato nacional +* Formato internacional +* Código de país +* Región o referencia LADA +* Operador o fuente asociada, si está disponible +* Información obtenida desde módulos locales +* Información obtenida desde APIs externas configuradas +* Consenso aproximado entre fuentes +* Reportes exportables + +--- +## APIs y resultados limitados + +MeXiCOSINT puede funcionar parcialmente sin API keys. + +Sin embargo, algunas funciones pueden estar limitadas si no configuraste servicios externos. + +Ejemplo: + +```text +Sin API key: validación local y parsing básico +Con API key: enriquecimiento adicional según el servicio configurado +``` + +Para configurar API keys, revisa: + +```text +docs/CONFIG.md +``` + +--- + +## Reportes y archivos generados + +Si la herramienta genera reportes, pueden aparecer archivos como: + +```text reporte.json +``` + +```text reporte.html +``` + +```text reporte_mapa.html +``` -Los nombres exactos pueden variar según la versión. +Los nombres exactos pueden cambiar según la versión. -API keys +También puede haber carpetas como: -Algunas funciones dependen de servicios externos. +```text +reports/ +``` -Si no configuras API keys, la herramienta puede seguir funcionando parcialmente, pero los resultados serán más limitados. +```text +output/ +``` -No subas tus API keys a GitHub. +```text +results/ +``` -Modo de prueba +Si no aparece ningún reporte, revisa la salida en terminal para confirmar si la función está disponible en tu versión. -Si la herramienta incluye un modo dummy o de prueba, úsalo solamente para desarrollo local. +--- + +## Modo de prueba o desarrollo + +Si la versión incluye un modo de prueba, puede ejecutarse con una bandera especial. Ejemplo: +```bash python3 mexicosint_v2.2.5.py --dummy-test +``` + +Este modo está pensado para desarrollo local. + +No debe considerarse una función principal para usuarios finales. + +--- + +## Actualizar antes de usar + +Para actualizar el repositorio: + +```bash +git pull +``` + +Después, si cambiaron las dependencias: + +```bash +pip install -r requirements.txt +``` -Este modo puede cambiar o desaparecer en futuras versiones. +--- -Buenas prácticas -Verifica resultados con más de una fuente. -No tomes resultados OSINT como prueba absoluta. -No uses la herramienta para acoso, doxxing o actividad no autorizada. -Mantén tus API keys fuera del repositorio. -Salir del entorno virtual +## Salir del entorno virtual Cuando termines: +```bash deactivate +``` + +--- + +## Buenas prácticas + +* Verifica resultados con más de una fuente. +* No trates resultados OSINT como evidencia absoluta. +* No subas API keys a GitHub. +* No publiques reportes con información sensible. +* Usa la herramienta únicamente en investigaciones autorizadas, autoauditoría o fines educativos. + +--- + +## Solución rápida de problemas + +### El comando `bash bin/mexicosint` no funciona + +Confirma que estás dentro de la carpeta del proyecto: + +```bash +pwd +``` + +Confirma que existe el launcher: + +```bash +ls -la bin +``` + +Ejecuta otra vez: + +```bash +bash bin/mexicosint +``` + +--- + +### Error de dependencias + +Vuelve a instalar los requisitos: + +```bash +pip install -r requirements.txt +``` + +--- + +### Error con el entorno virtual + +Recrea el entorno virtual: + +```bash +rm -rf venv +``` + +```bash +python3 -m venv venv +``` + +```bash +source venv/bin/activate +``` + +```bash +pip install -r requirements.txt +``` + +--- + +### API key no detectada + +Revisa que el archivo de configuración exista: + +```bash +ls -la ~/.mx_osint_config.json +``` + +Revisa permisos: + +```bash +chmod 600 ~/.mx_osint_config.json +``` + +Revisa la guía de configuración: + +```text +docs/CONFIG.md +``` + +--- + +## Estado + +Si todo está correcto, deberías poder ejecutar: + +```bash +bash bin/mexicosint +``` + +Y ver el inicio de MeXiCOSINT en terminal. From 74a55bdd8345f79cdae14f37ef4f16c741faea11 Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 25 Jun 2026 04:08:55 -0700 Subject: [PATCH 07/23] Update CONFIG.md --- docs/CONFIG.md | 255 +++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 226 insertions(+), 29 deletions(-) diff --git a/docs/CONFIG.md b/docs/CONFIG.md index 3f0b8b8..c14d408 100644 --- a/docs/CONFIG.md +++ b/docs/CONFIG.md @@ -1,4 +1,4 @@ -# Configuración +# Guía de configuración Esta guía explica cómo manejar la configuración local y las API keys de **MeXiCOSINT**. @@ -8,24 +8,31 @@ Esta guía explica cómo manejar la configuración local y las API keys de **MeX MeXiCOSINT puede usar un archivo local para guardar API keys y otros valores de configuración. -Ubicación recomendada: +La ruta recomendada es: ```text ~/.mx_osint_config.json +``` Este archivo debe existir solamente en tu computadora. No debe subirse a GitHub. -Permisos recomendados +--- -Para proteger el archivo: +## Crear el archivo de configuración -chmod 600 ~/.mx_osint_config.json -Ejemplo de configuración +Puedes crear el archivo con: + +```bash +nano ~/.mx_osint_config.json +``` + +Dentro del archivo puedes agregar tus API keys. -Ejemplo básico: +Ejemplo: +```json { "abstractapi_key": "TU_ABSTRACTAPI_KEY", "numverify_key": "TU_NUMVERIFY_KEY", @@ -34,43 +41,233 @@ Ejemplo básico: "ip2location_key": "TU_IP2LOCATION_KEY", "opencage_key": "TU_OPENCAGE_KEY" } +``` Reemplaza cada valor con tu propia API key. -APIs opcionales +--- + +## Proteger el archivo + +Para proteger el archivo de configuración local: + +```bash +chmod 600 ~/.mx_osint_config.json +``` + +Esto limita el acceso al archivo únicamente a tu usuario. + +--- + +## APIs opcionales -MeXiCOSINT puede funcionar parcialmente sin algunas API keys. +MeXiCOSINT puede funcionar parcialmente sin API keys. -Servicio Función -AbstractAPI Validación y enriquecimiento de números -NumVerify Validación secundaria -Shodan Búsqueda opcional relacionada con servicios expuestos -IPInfo Datos relacionados con IP -IP2Location Datos relacionados con IP -OpenCage Geocodificación y mapas -No subir claves a GitHub +Sin embargo, algunas funciones tendrán mejores resultados si se configuran servicios externos. -Antes de subir cambios, revisa que no hayas agregado tus claves por accidente. +| Servicio | Función | +| ----------- | ------------------------------------------------------------ | +| AbstractAPI | Validación y enriquecimiento de números telefónicos | +| NumVerify | Validación secundaria de números telefónicos | +| Shodan | Enriquecimiento opcional relacionado con servicios expuestos | +| IPInfo | Enriquecimiento de metadatos IP | +| IP2Location | Enriquecimiento de metadatos IP | +| OpenCage | Geocodificación y soporte para mapas | -Archivos que no deben subirse: +--- + +## Funcionamiento sin API keys + +Si no configuras API keys, MeXiCOSINT puede seguir funcionando parcialmente. + +Ejemplo: + +```text +Sin API keys: +- Validación local +- Parsing básico +- Formato nacional/internacional +- Resultados limitados + +Con API keys: +- Enriquecimiento adicional +- Validación secundaria +- Más fuentes de comparación +- Mejor contexto para reportes +``` +--- + +## Archivos que NO deben subirse + +No subas archivos que contengan claves, tokens o datos sensibles. + +Ejemplos: + +```text .env *.env .mx_osint_config.json config.json secrets.json keys.json -Revisión rápida antes de hacer commit +tokens.json +credentials.json +``` + +Si uno de estos archivos aparece en GitHub por accidente, elimina el archivo y rota las claves afectadas. + +Porque sí, una API key subida a GitHub se convierte en comida gratis para bots antes de que termines de pestañear. Qué civilización tan brillante. + +--- + +## Revisar antes de hacer commit + +Antes de subir cambios, puedes buscar posibles claves dentro del proyecto: + +```bash +grep -Ri "api_key\|apikey\|token\|secret\|password\|credential" . +``` + +Si aparece una clave real, elimínala antes de hacer commit. + +También puedes revisar los archivos modificados con: + +```bash +git status +``` + +Y revisar diferencias con: + +```bash +git diff +``` + +--- + +## Configuración recomendada en `.gitignore` + +El archivo `.gitignore` debe incluir entradas para evitar subir secretos por accidente: + +```gitignore +.env +*.env +.mx_osint_config.json +config.json +secrets.json +keys.json +tokens.json +credentials.json +*.key +*.pem +``` + +--- + +## Estructura recomendada + +La configuración sensible debe vivir fuera del repositorio: + +```text +/home/usuario/.mx_osint_config.json +``` + +o: + +```text +~/.mx_osint_config.json +``` + +El repositorio solo debe contener ejemplos, documentación y código. + +--- + +## Ejemplo seguro para documentación + +Si quieres mostrar un ejemplo en la documentación, usa valores falsos: + +```json +{ + "abstractapi_key": "TU_ABSTRACTAPI_KEY", + "numverify_key": "TU_NUMVERIFY_KEY" +} +``` + +Nunca uses claves reales en ejemplos públicos. + +--- + +## Permisos recomendados + +Revisa los permisos actuales: + +```bash +ls -la ~/.mx_osint_config.json +``` + +Aplica permisos seguros: + +```bash +chmod 600 ~/.mx_osint_config.json +``` + +Resultado esperado aproximado: + +```text +-rw------- 1 usuario usuario ... /home/usuario/.mx_osint_config.json +``` + +--- + +## Si subiste una API key por accidente + +1. Elimina la clave del repositorio. +2. Haz commit del cambio. +3. Entra al panel del proveedor de la API. +4. Revoca o elimina la API key expuesta. +5. Crea una API key nueva. +6. Actualiza tu archivo local `~/.mx_osint_config.json`. + +No basta con borrar la línea del README o del archivo actual. Git guarda historial. Porque Git es útil, pero también es un archivista con tendencias obsesivas. + +--- + +## Variables de entorno + +En futuras versiones, MeXiCOSINT también podría usar variables de entorno. + +Ejemplo: + +```bash +export ABSTRACTAPI_KEY="TU_ABSTRACTAPI_KEY" +``` + +Pero la forma recomendada para este proyecto es usar: + +```text +~/.mx_osint_config.json +``` + +--- + +## Buenas prácticas + +* Mantén tus API keys fuera del repositorio. +* No compartas capturas donde se vean claves. +* No hardcodees API keys dentro del código. +* Usa permisos `600` para archivos sensibles. +* Rota cualquier clave que haya sido expuesta. +* Usa ejemplos falsos en documentación pública. +* Revisa cambios antes de hacer commit. + +--- -Desde terminal puedes revisar si hay claves visibles usando: +## Estado -grep -Ri "api_key\|apikey\|token\|secret\|password" . +Si el archivo existe y tiene permisos correctos, puedes ejecutar: -Si aparece una clave real, elimínala antes de subir cambios. +```bash +bash bin/mexicosint +``` -Buenas prácticas -Usa claves personales solamente en tu entorno local. -No hardcodees API keys dentro del código. -No publiques capturas donde se vean claves. -Rota una API key si la subiste accidentalmente. -Mantén .gitignore actualizado. +Y MeXiCOSINT debería poder leer la configuración local según las funciones disponibles en la versión actual. From f7c50bcfea0765da27f5e21e476f1be8b5f91fc4 Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 25 Jun 2026 04:16:27 -0700 Subject: [PATCH 08/23] ENGLISH.md --- docs/ENGLISH.md | 640 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 640 insertions(+) create mode 100644 docs/ENGLISH.md diff --git a/docs/ENGLISH.md b/docs/ENGLISH.md new file mode 100644 index 0000000..a43bc8d --- /dev/null +++ b/docs/ENGLISH.md @@ -0,0 +1,640 @@ +# MeXiCOSINT English Documentation + +**MeXiCOSINT** is a Python-based OSINT tool focused on Mexican phone number analysis, validation, enrichment, and reporting. + +This document provides the full English documentation for installation, usage, configuration, security notes, troubleshooting, and project status. + +--- + +## Overview + +MeXiCOSINT is designed for authorized OSINT research, self-auditing, and educational workflows involving Mexican phone numbers. + +The tool can validate numbers, parse Mexican phone formats, use optional external API sources, process available metadata, and generate investigation-style output depending on the active version and configuration. + +> This project is currently in beta. Results should be treated as OSINT indicators, not absolute proof. + +--- + +## Features + +* Mexican phone number validation +* National and international number formatting +* Local parsing for Mexican numbers +* Optional API enrichment +* IFT/SNS-related processing +* QuienHabla.mx module support +* Launcher script for cleaner execution +* Local API key configuration +* Report or output support depending on version +* Development/testing support depending on version + +--- + +## Repository Structure + +```text +MeXiCOSINT/ +├── bin/ +│ └── mexicosint +├── data/ +├── docs/ +│ ├── INSTALL.md +│ ├── USAGE.md +│ ├── CONFIG.md +│ └── ENGLISH.md +├── modules/ +│ ├── ift_sns.py +│ ├── local_parser.py +│ └── quienhabla.py +├── mexicosint_v2.2.5.py +├── requirements.txt +├── .gitignore +├── LICENSE +└── README.md +``` + +--- + +## Requirements + +Before installing MeXiCOSINT, make sure your system has: + +* Python 3 +* pip +* venv +* git + +Install the basic requirements on Kali Linux, Debian, Ubuntu, or similar systems: + +```bash +sudo apt update +``` + +```bash +sudo apt install -y python3 python3-pip python3-venv git +``` + +--- + +## Installation + +Clone the repository: + +```bash +git clone https://github.com/KiMiGuel/MeXiCOSINT.git +``` + +Enter the project folder: + +```bash +cd MeXiCOSINT +``` + +Create a virtual environment: + +```bash +python3 -m venv venv +``` + +Activate the virtual environment: + +```bash +source venv/bin/activate +``` + +Install the dependencies: + +```bash +pip install -r requirements.txt +``` + +If everything completes successfully, MeXiCOSINT should be ready to run. + +--- + +## Quick Installation + +Full setup summary: + +```bash +sudo apt update +sudo apt install -y python3 python3-pip python3-venv git +git clone https://github.com/KiMiGuel/MeXiCOSINT.git +cd MeXiCOSINT +python3 -m venv venv +source venv/bin/activate +pip install -r requirements.txt +bash bin/mexicosint +``` + +--- + +## Usage + +Make sure you are inside the project folder: + +```bash +cd MeXiCOSINT +``` + +Activate the virtual environment: + +```bash +source venv/bin/activate +``` + +Run MeXiCOSINT using the included launcher: + +```bash +bash bin/mexicosint +``` + +This avoids manually typing the full Python filename. + +You can also run the main script directly: + +```bash +python3 mexicosint_v2.2.5.py +``` + +--- + +## Recommended Phone Number Format + +MeXiCOSINT is focused on Mexican phone numbers. + +Recommended international format: + +```text ++52XXXXXXXXXX +``` + +National 10-digit format may also be accepted: + +```text +XXXXXXXXXX +``` + +Example international format: + +```text ++525512345678 +``` + +Example national format: + +```text +5512345678 +``` + +--- + +## Basic Workflow + +1. Run the tool: + +```bash +bash bin/mexicosint +``` + +2. Enter the Mexican phone number when prompted. + +3. Review the terminal output. + +4. If the tool generates reports, check the files created inside the project folder. + +--- + +## Possible Results + +Depending on the version, configuration, and available API keys, MeXiCOSINT may display information such as: + +* Number validation +* National format +* International format +* Country code +* Region or LADA reference +* Carrier or source data, if available +* Local module results +* External API results, if configured +* Approximate consensus between sources +* Exportable reports + +--- + +## Optional API Sources + +Some features may depend on external API keys. + +| Service | Purpose | +| ----------- | ----------------------------------------------- | +| AbstractAPI | Phone validation and enrichment | +| NumVerify | Secondary phone validation | +| Shodan | Optional enrichment related to exposed services | +| IPInfo | IP metadata enrichment | +| IP2Location | IP metadata enrichment | +| OpenCage | Geocoding and map support | + +MeXiCOSINT can work partially without API keys, but some results may be limited. + +--- + +## Configuration File + +The recommended local configuration file is: + +```text +~/.mx_osint_config.json +``` + +This file should exist only on your local machine. + +Do not upload it to GitHub. + +--- + +## Creating the Configuration File + +Create the file with: + +```bash +nano ~/.mx_osint_config.json +``` + +Example configuration: + +```json +{ + "abstractapi_key": "YOUR_ABSTRACTAPI_KEY", + "numverify_key": "YOUR_NUMVERIFY_KEY", + "shodan_key": "YOUR_SHODAN_KEY", + "ipinfo_key": "YOUR_IPINFO_KEY", + "ip2location_key": "YOUR_IP2LOCATION_KEY", + "opencage_key": "YOUR_OPENCAGE_KEY" +} +``` + +Replace each placeholder value with your own API key. + +--- + +## Protecting the Configuration File + +Apply safer permissions: + +```bash +chmod 600 ~/.mx_osint_config.json +``` + +Check the file permissions: + +```bash +ls -la ~/.mx_osint_config.json +``` + +Expected result should look similar to: + +```text +-rw------- 1 user user ... /home/user/.mx_osint_config.json +``` + +--- + +## Running Without API Keys + +MeXiCOSINT may still work partially without API keys. + +Example: + +```text +Without API keys: +- Local validation +- Basic parsing +- National and international formatting +- Limited results + +With API keys: +- Additional enrichment +- Secondary validation +- More source comparison +- Better report context +``` + +--- + +## Reports and Generated Files + +If the tool generates reports, possible files may include: + +```text +report.json +``` + +```text +report.html +``` + +```text +report_map.html +``` + +Actual filenames may change depending on the version. + +Possible output folders may include: + +```text +reports/ +``` + +```text +output/ +``` + +```text +results/ +``` + +If no report appears, check the terminal output to confirm whether report generation is available in your current version. + +--- + +## Files That Should Not Be Uploaded + +Do not upload files containing API keys, tokens, credentials, or sensitive data. + +Examples: + +```text +.env +*.env +.mx_osint_config.json +config.json +secrets.json +keys.json +tokens.json +credentials.json +``` + +If one of these files is accidentally uploaded, remove it and rotate the exposed keys. + +An API key uploaded to GitHub is basically a free snack for bots. The internet remains a deeply embarrassing ecosystem. + +--- + +## Recommended `.gitignore` Entries + +The `.gitignore` file should include entries such as: + +```gitignore +.env +*.env +.mx_osint_config.json +config.json +secrets.json +keys.json +tokens.json +credentials.json +*.key +*.pem +``` + +--- + +## Checking for Secrets Before Committing + +Before pushing changes, search for possible exposed secrets: + +```bash +grep -Ri "api_key\|apikey\|token\|secret\|password\|credential" . +``` + +Check modified files: + +```bash +git status +``` + +Review differences: + +```bash +git diff +``` + +If a real key appears, remove it before committing. + +--- + +## If You Accidentally Uploaded an API Key + +1. Remove the key from the repository. +2. Commit the cleanup. +3. Open the API provider dashboard. +4. Revoke or delete the exposed API key. +5. Create a new API key. +6. Update your local `~/.mx_osint_config.json` file. + +Deleting the line from the current file is not always enough because Git keeps history. Git is useful, but it is also an obsessive little archivist. + +--- + +## Updating MeXiCOSINT + +To update the repository: + +```bash +git pull +``` + +If dependencies changed, run: + +```bash +pip install -r requirements.txt +``` + +--- + +## Exiting the Virtual Environment + +When you are done using the tool: + +```bash +deactivate +``` + +--- + +## Development or Test Mode + +If the current version includes a development or dummy test mode, it may be executed with a special flag. + +Example: + +```bash +python3 mexicosint_v2.2.5.py --dummy-test +``` + +This mode is intended for local development and testing. + +It should not be treated as the main user-facing workflow. + +--- + +## Troubleshooting + +### `python3: command not found` + +Install Python: + +```bash +sudo apt install -y python3 +``` + +--- + +### `pip: command not found` + +Install pip: + +```bash +sudo apt install -y python3-pip +``` + +--- + +### Error creating the virtual environment + +Install venv: + +```bash +sudo apt install -y python3-venv +``` + +Then recreate the virtual environment: + +```bash +python3 -m venv venv +``` + +--- + +### `bash bin/mexicosint` does not work + +Confirm you are inside the project folder: + +```bash +pwd +``` + +Confirm the launcher exists: + +```bash +ls -la bin +``` + +Run it again: + +```bash +bash bin/mexicosint +``` + +--- + +### Dependency error + +Reinstall the requirements: + +```bash +pip install -r requirements.txt +``` + +--- + +### Virtual environment problem + +Recreate the virtual environment: + +```bash +rm -rf venv +``` + +```bash +python3 -m venv venv +``` + +```bash +source venv/bin/activate +``` + +```bash +pip install -r requirements.txt +``` + +--- + +### API key not detected + +Check that the configuration file exists: + +```bash +ls -la ~/.mx_osint_config.json +``` + +Apply safe permissions: + +```bash +chmod 600 ~/.mx_osint_config.json +``` + +Review the configuration guide: + +```text +docs/CONFIG.md +``` + +--- + +## Security Notes + +MeXiCOSINT is intended for authorized research, self-auditing, and educational OSINT workflows. + +Do not use this tool for harassment, doxxing, fraud, threats, stalking, or unauthorized activity. + +The tool does not guarantee identity, exact location, ownership, or definitive attribution of a phone number. + +Results should be verified with more than one source. + +--- + +## Best Practices + +* Keep API keys out of the repository. +* Do not hardcode API keys into the source code. +* Do not publish screenshots containing visible keys. +* Use fake placeholder values in public documentation. +* Use `chmod 600` for sensitive local files. +* Rotate any exposed API key. +* Review changes before committing. +* Treat OSINT results as indicators, not proof. + +--- + +## Project Status + +This project is under active development. + +Planned improvements may include: + +* Installable packaging +* Global `mexicosint` command +* GitHub releases +* Local `.deb` package for apt-based installation +* Expanded documentation +* Additional validation and testing +* Improved internal structure + +--- + +## License + +This project is released under the license included in the repository. From c687c00d3a6f465d91d73e4d0994b65c3798e3c8 Mon Sep 17 00:00:00 2001 From: KiMiGuel <269183473+KiMiGuel@users.noreply.github.com> Date: Thu, 9 Jul 2026 21:06:11 -0700 Subject: [PATCH 09/23] Refactor into installable Python package --- MIGRATION.md | 55 +++++++++++++ README.md | 46 ++++++++--- bin/mexicosint | 7 +- docs/ENGLISH.md | 19 +++-- docs/INSTALL.md | 2 +- docs/USAGE.md | 4 +- pyproject.toml | 32 ++++++++ requirements.txt | 1 + src/mexicosint/__init__.py | 5 ++ src/mexicosint/__main__.py | 7 ++ src/mexicosint/cli.py | 72 ++++++++++++++++++ {data => src/mexicosint/data}/ift_pnn.db | Bin .../data}/pnn_Publico_18_06_2026.csv | 0 .../mexicosint/main.py | 38 +++++---- .../mexicosint/modules}/__init__.py | 0 .../mexicosint/modules}/ift_sns.py | 4 +- .../mexicosint/modules}/local_parser.py | 0 .../mexicosint/modules}/quienhabla.py | 0 src/mexicosint/services/__init__.py | 1 + src/mexicosint/services/ip_geo.py | 5 ++ src/mexicosint/services/scanner.py | 5 ++ src/mexicosint/utils/__init__.py | 1 + src/mexicosint/utils/validation.py | 17 +++++ 23 files changed, 274 insertions(+), 47 deletions(-) create mode 100644 MIGRATION.md mode change 100644 => 100755 bin/mexicosint create mode 100644 pyproject.toml create mode 100644 src/mexicosint/__init__.py create mode 100644 src/mexicosint/__main__.py create mode 100644 src/mexicosint/cli.py rename {data => src/mexicosint/data}/ift_pnn.db (100%) rename {data => src/mexicosint/data}/pnn_Publico_18_06_2026.csv (100%) rename mexicosint_v2.2.5.py => src/mexicosint/main.py (98%) rename {modules => src/mexicosint/modules}/__init__.py (100%) rename {modules => src/mexicosint/modules}/ift_sns.py (97%) rename {modules => src/mexicosint/modules}/local_parser.py (100%) rename {modules => src/mexicosint/modules}/quienhabla.py (100%) create mode 100644 src/mexicosint/services/__init__.py create mode 100644 src/mexicosint/services/ip_geo.py create mode 100644 src/mexicosint/services/scanner.py create mode 100644 src/mexicosint/utils/__init__.py create mode 100644 src/mexicosint/utils/validation.py diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..53fc7c8 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,55 @@ +# Migration Instructions + +MeXiCOSINT now uses a production-style `src/` package layout. + +## What changed + +- `mexicosint_v2.2.5.py` was replaced by `src/mexicosint/main.py`. +- The command-line entry point is now `src/mexicosint/cli.py`. +- Existing helper modules moved from `modules/` to `src/mexicosint/modules/`. +- Service-facing wrappers live in `src/mexicosint/services/`. +- Shared helpers live in `src/mexicosint/utils/`. +- Package metadata and the console script are defined in `pyproject.toml`. +- Local IFT data moved into `src/mexicosint/data/` so it can be packaged. + +## Install for development + +```bash +python3 -m venv venv +source venv/bin/activate +pip install -e . +``` + +## Run after migration + +Use the installed command: + +```bash +mexicosint 5512345678 +mexicosint --ip 8.8.8.8 +mexicosint --dummy-test 5512345678 +mexicosint -b 5512345678 +``` + +Run without installing: + +```bash +PYTHONPATH=src python3 -m mexicosint 5512345678 +``` + +Or use the repository launcher: + +```bash +bash bin/mexicosint 5512345678 +``` + +## Import changes + +Use absolute package imports: + +```python +from mexicosint.modules.local_parser import parse_mx_number +from mexicosint.modules.ift_sns import consultar +from mexicosint.modules.quienhabla import consultar as consultar_quienhabla +from mexicosint.services.scanner import run_phone_scan +``` diff --git a/README.md b/README.md index fc2c854..caaea95 100644 --- a/README.md +++ b/README.md @@ -47,16 +47,27 @@ La herramienta puede validar números, analizar formatos mexicanos, consultar fu MeXiCOSINT/ ├── bin/ │ └── mexicosint -├── data/ ├── docs/ │ ├── INSTALL.md │ ├── USAGE.md │ └── CONFIG.md -├── modules/ -│ ├── ift_sns.py -│ ├── local_parser.py -│ └── quienhabla.py -├── mexicosint_v2.2.5.py +├── src/ +│ └── mexicosint/ +│ ├── __init__.py +│ ├── __main__.py +│ ├── cli.py +│ ├── main.py +│ ├── data/ +│ ├── modules/ +│ │ ├── ift_sns.py +│ │ ├── local_parser.py +│ │ └── quienhabla.py +│ ├── services/ +│ │ ├── ip_geo.py +│ │ └── scanner.py +│ └── utils/ +│ └── validation.py +├── pyproject.toml ├── requirements.txt ├── .gitignore ├── LICENSE @@ -97,6 +108,12 @@ Instala las dependencias: pip install -r requirements.txt ``` +Instala el paquete en modo editable: + +```bash +pip install -e . +``` + --- ## Uso @@ -104,17 +121,24 @@ pip install -r requirements.txt Ejecuta MeXiCOSINT usando el launcher: ```bash -bash bin/mexicosint +mexicosint 5512345678 +mexicosint -b 5512345678 ``` -Esto evita tener que escribir manualmente el nombre completo del archivo principal de Python. +Tambien puedes usar el launcher del repositorio sin instalar el comando global: -También puedes ejecutar el script principal directamente: +```bash +bash bin/mexicosint 5512345678 +``` + +O ejecutar el modulo del paquete: ```bash -python3 mexicosint_v2.2.5.py +PYTHONPATH=src python3 -m mexicosint 5512345678 ``` +Use `-b`, `--compact-banner`, or the legacy `--small-banner` flag to force the compact ASCII banner. + --- ## Documentación @@ -187,8 +211,6 @@ Este proyecto está en desarrollo activo. Funciones planeadas: -- Empaquetado instalable -- Comando global `mexicosint` - Publicación de releases en GitHub - Paquete `.deb` para instalación local con `apt` - Mejoras en documentación diff --git a/bin/mexicosint b/bin/mexicosint old mode 100644 new mode 100755 index e979203..2f24c75 --- a/bin/mexicosint +++ b/bin/mexicosint @@ -8,4 +8,9 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" cd "$REPO_ROOT" || exit 1 -python3 "$REPO_ROOT/mexicosint_v2.2.5.py" "$@" +PYTHON_BIN="$REPO_ROOT/venv/bin/python" +if [[ ! -x "$PYTHON_BIN" ]]; then + PYTHON_BIN="python3" +fi + +PYTHONPATH="$REPO_ROOT/src${PYTHONPATH:+:$PYTHONPATH}" "$PYTHON_BIN" -m mexicosint "$@" diff --git a/docs/ENGLISH.md b/docs/ENGLISH.md index a43bc8d..36fb24c 100644 --- a/docs/ENGLISH.md +++ b/docs/ENGLISH.md @@ -37,17 +37,20 @@ The tool can validate numbers, parse Mexican phone formats, use optional externa MeXiCOSINT/ ├── bin/ │ └── mexicosint -├── data/ ├── docs/ │ ├── INSTALL.md │ ├── USAGE.md │ ├── CONFIG.md │ └── ENGLISH.md -├── modules/ -│ ├── ift_sns.py -│ ├── local_parser.py -│ └── quienhabla.py -├── mexicosint_v2.2.5.py +├── src/ +│ └── mexicosint/ +│ ├── cli.py +│ ├── main.py +│ ├── data/ +│ ├── modules/ +│ ├── services/ +│ └── utils/ +├── pyproject.toml ├── requirements.txt ├── .gitignore ├── LICENSE @@ -155,7 +158,7 @@ This avoids manually typing the full Python filename. You can also run the main script directly: ```bash -python3 mexicosint_v2.2.5.py +PYTHONPATH=src python3 -m mexicosint ``` --- @@ -471,7 +474,7 @@ If the current version includes a development or dummy test mode, it may be exec Example: ```bash -python3 mexicosint_v2.2.5.py --dummy-test +PYTHONPATH=src python3 -m mexicosint --dummy-test ``` This mode is intended for local development and testing. diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 97d36c4..c78ba2b 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -88,7 +88,7 @@ bash bin/mexicosint También puedes ejecutar directamente el archivo principal: ```bash -python3 mexicosint_v2.2.5.py +PYTHONPATH=src python3 -m mexicosint ``` --- diff --git a/docs/USAGE.md b/docs/USAGE.md index 1c7daee..d80fb5d 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -37,7 +37,7 @@ bash bin/mexicosint También puedes ejecutar directamente el archivo principal: ```bash -python3 mexicosint_v2.2.5.py +PYTHONPATH=src python3 -m mexicosint ``` --- @@ -169,7 +169,7 @@ Si la versión incluye un modo de prueba, puede ejecutarse con una bandera espec Ejemplo: ```bash -python3 mexicosint_v2.2.5.py --dummy-test +PYTHONPATH=src python3 -m mexicosint --dummy-test ``` Este modo está pensado para desarrollo local. diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..7b79ead --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,32 @@ +[build-system] +requires = ["setuptools>=68", "wheel"] +build-backend = "setuptools.build_meta" + +[project] +name = "mexicosint" +version = "2.2.5" +description = "OSINT para numeros telefonicos Mexicanos" +readme = "README.md" +requires-python = ">=3.8" +license = { text = "MIT" } +authors = [{ name = "KiMiGuEL" }] +dependencies = [ + "requests>=2.28.0", + "urllib3<2", + "beautifulsoup4>=4.11.0", + "python-dotenv>=0.19.0", + "lxml>=4.9.0", + "phonenumbers>=8.13.0", + "rich>=13.0.0", + "opencage>=3.0.0", + "folium>=0.14.0", +] + +[project.scripts] +mexicosint = "mexicosint.cli:main" + +[tool.setuptools.packages.find] +where = ["src"] + +[tool.setuptools.package-data] +mexicosint = ["data/*"] diff --git a/requirements.txt b/requirements.txt index 6656f26..10725b7 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,5 @@ requests>=2.28.0 +urllib3<2 beautifulsoup4>=4.11.0 python-dotenv>=0.19.0 lxml>=4.9.0 diff --git a/src/mexicosint/__init__.py b/src/mexicosint/__init__.py new file mode 100644 index 0000000..7763dab --- /dev/null +++ b/src/mexicosint/__init__.py @@ -0,0 +1,5 @@ +"""MeXiCOSINT package.""" + +__all__ = ["__version__"] + +__version__ = "2.2.5" diff --git a/src/mexicosint/__main__.py b/src/mexicosint/__main__.py new file mode 100644 index 0000000..f32ed97 --- /dev/null +++ b/src/mexicosint/__main__.py @@ -0,0 +1,7 @@ +"""Module entry point for `python -m mexicosint`.""" + +from mexicosint.cli import main + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/src/mexicosint/cli.py b/src/mexicosint/cli.py new file mode 100644 index 0000000..e804e8d --- /dev/null +++ b/src/mexicosint/cli.py @@ -0,0 +1,72 @@ +"""Command-line interface for MeXiCOSINT.""" + +from __future__ import annotations + +import argparse + +from mexicosint import __version__ + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser( + prog="mexicosint", + description="OSINT para numeros telefonicos Mexicanos.", + ) + parser.add_argument( + "number", + nargs="?", + help="Numero telefonico mexicano a escanear.", + ) + parser.add_argument( + "--ip", + dest="ip", + metavar="ADDRESS", + help="Geolocaliza directamente una direccion IP.", + ) + parser.add_argument( + "--dummy-test", + action="store_true", + help="Usa datos de prueba y evita llamadas reales a APIs.", + ) + parser.add_argument( + "-b", + "--compact-banner", + "--small-banner", + dest="small_banner", + action="store_true", + help="Fuerza el banner compacto; alias: --small-banner.", + ) + parser.add_argument( + "--version", + action="version", + version=f"%(prog)s {__version__}", + ) + return parser + + +def _to_legacy_argv(args: argparse.Namespace) -> list[str]: + """Translate argparse output to the existing scanner argument format.""" + argv: list[str] = [] + if args.dummy_test: + argv.append("--dummy-test") + if args.small_banner: + argv.append("--small-banner") + if args.ip: + argv.extend(["--ip", args.ip]) + elif args.number: + argv.append(args.number) + return argv + + +def main(argv: list[str] | None = None) -> int: + parser = build_parser() + args = parser.parse_args(argv) + + if not args.ip and not args.number: + parser.print_help() + return 1 + + from mexicosint import main as app + + app.main(_to_legacy_argv(args)) + return 0 diff --git a/data/ift_pnn.db b/src/mexicosint/data/ift_pnn.db similarity index 100% rename from data/ift_pnn.db rename to src/mexicosint/data/ift_pnn.db diff --git a/data/pnn_Publico_18_06_2026.csv b/src/mexicosint/data/pnn_Publico_18_06_2026.csv similarity index 100% rename from data/pnn_Publico_18_06_2026.csv rename to src/mexicosint/data/pnn_Publico_18_06_2026.csv diff --git a/mexicosint_v2.2.5.py b/src/mexicosint/main.py similarity index 98% rename from mexicosint_v2.2.5.py rename to src/mexicosint/main.py index 68f8215..52b64f1 100644 --- a/mexicosint_v2.2.5.py +++ b/src/mexicosint/main.py @@ -32,6 +32,8 @@ from datetime import datetime, timezone from dataclasses import dataclass, field, asdict +from mexicosint.utils.validation import is_valid_ip + try: from rich.console import Console from rich.table import Table @@ -1344,10 +1346,10 @@ def print_results(result: ScanResult): print(" NO garantiza la posicion exacta/GPS del telefono.") -def main(): +def main(argv=None): global DUMMY_MODE, SMALL_BANNER - args = sys.argv[1:] + args = list(sys.argv[1:] if argv is None else argv) if "--dummy-test" in args: DUMMY_MODE = True @@ -1355,39 +1357,33 @@ def main(): print("\n[!] MODO DUMMY ACTIVADO: No se realizaran llamadas reales a las APIs.") print(" Se usaran datos de ejemplo. No se consumiran creditos.\n") - if "--small-banner" in args: + banner_flags = {"-b", "--compact-banner", "--small-banner"} + if any(flag in args for flag in banner_flags): SMALL_BANNER = True - args.remove("--small-banner") + args = [arg for arg in args if arg not in banner_flags] print_banner() if len(args) < 1: - print("Uso: python3 mexicosint_v2.2.4.py ") - print(" python3 mexicosint_v2.2.4.py --ip ") - print(" python3 mexicosint_v2.2.4.py --dummy-test ") + print("Uso: mexicosint ") + print(" mexicosint --ip ") + print(" mexicosint --dummy-test ") print("Ejemplos:") - print(" python3 mexicosint_v2.2.4.py 5512345678") - print(" python3 mexicosint_v2.2.4.py +525512345678") - print(" python3 mexicosint_v2.2.4.py --ip 8.8.8.8") + print(" mexicosint 5512345678") + print(" mexicosint +525512345678") + print(" mexicosint --ip 8.8.8.8") sys.exit(1) raw = args[0] if raw == "--ip": if len(args) < 2: - print("[!] Uso: python3 mexicosint_v2.2.4.py --ip ") + print("[!] Uso: mexicosint --ip ") sys.exit(1) ip = args[1] - # Validate IP address - import socket - try: - socket.inet_aton(ip) - except OSError: - try: - socket.inet_pton(socket.AF_INET6, ip) - except OSError: - print(f"[!] ERROR: '{ip}' no es una direccion IP valida.") - sys.exit(1) + if not is_valid_ip(ip): + print(f"[!] ERROR: '{ip}' no es una direccion IP valida.") + sys.exit(1) print(f"[+] Modo IP directo: {ip}") print(f"[+] Fecha/Hora: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}") print("=" * 60) diff --git a/modules/__init__.py b/src/mexicosint/modules/__init__.py similarity index 100% rename from modules/__init__.py rename to src/mexicosint/modules/__init__.py diff --git a/modules/ift_sns.py b/src/mexicosint/modules/ift_sns.py similarity index 97% rename from modules/ift_sns.py rename to src/mexicosint/modules/ift_sns.py index 9a2c6fd..64a9093 100644 --- a/modules/ift_sns.py +++ b/src/mexicosint/modules/ift_sns.py @@ -1,8 +1,8 @@ #!/usr/bin/env python3 """ ift_sns.py -IFT Plan Nacional de Numeración — builds SQLite from local CSV. -Auto-detects pnn_Publico_*.csv in ~/mexicosint/data/ +IFT Plan Nacional de Numeracion - builds SQLite from local CSV. +Auto-detects pnn_Publico_*.csv in the packaged data directory. """ import os diff --git a/modules/local_parser.py b/src/mexicosint/modules/local_parser.py similarity index 100% rename from modules/local_parser.py rename to src/mexicosint/modules/local_parser.py diff --git a/modules/quienhabla.py b/src/mexicosint/modules/quienhabla.py similarity index 100% rename from modules/quienhabla.py rename to src/mexicosint/modules/quienhabla.py diff --git a/src/mexicosint/services/__init__.py b/src/mexicosint/services/__init__.py new file mode 100644 index 0000000..d2bcc1d --- /dev/null +++ b/src/mexicosint/services/__init__.py @@ -0,0 +1 @@ +"""Service layer for external lookups and scan orchestration.""" diff --git a/src/mexicosint/services/ip_geo.py b/src/mexicosint/services/ip_geo.py new file mode 100644 index 0000000..a17f4cc --- /dev/null +++ b/src/mexicosint/services/ip_geo.py @@ -0,0 +1,5 @@ +"""IP geolocation service API.""" + +from mexicosint.main import print_ip_geo + +__all__ = ["print_ip_geo"] diff --git a/src/mexicosint/services/scanner.py b/src/mexicosint/services/scanner.py new file mode 100644 index 0000000..204975e --- /dev/null +++ b/src/mexicosint/services/scanner.py @@ -0,0 +1,5 @@ +"""Phone scan service API.""" + +from mexicosint.main import print_results, run_phone_scan + +__all__ = ["print_results", "run_phone_scan"] diff --git a/src/mexicosint/utils/__init__.py b/src/mexicosint/utils/__init__.py new file mode 100644 index 0000000..e0e9d71 --- /dev/null +++ b/src/mexicosint/utils/__init__.py @@ -0,0 +1 @@ +"""Utility helpers for MeXiCOSINT.""" diff --git a/src/mexicosint/utils/validation.py b/src/mexicosint/utils/validation.py new file mode 100644 index 0000000..3f34b3b --- /dev/null +++ b/src/mexicosint/utils/validation.py @@ -0,0 +1,17 @@ +"""Validation helpers used by the command-line interface.""" + +from __future__ import annotations + +import socket + + +def is_valid_ip(value: str) -> bool: + try: + socket.inet_aton(value) + return True + except OSError: + try: + socket.inet_pton(socket.AF_INET6, value) + return True + except OSError: + return False From 483b4417b073b65b4f2b275f3caf5ec87335101f Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 9 Jul 2026 21:23:32 -0700 Subject: [PATCH 10/23] feat(cli): add argparse run entry point --- src/mexicosint/cli.py | 37 +++++++++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/src/mexicosint/cli.py b/src/mexicosint/cli.py index e804e8d..5ab9b2b 100644 --- a/src/mexicosint/cli.py +++ b/src/mexicosint/cli.py @@ -3,6 +3,7 @@ from __future__ import annotations import argparse +from typing import List, Optional from mexicosint import __version__ @@ -15,6 +16,12 @@ def build_parser() -> argparse.ArgumentParser: parser.add_argument( "number", nargs="?", + help="Numero telefonico mexicano a escanear. Se mantiene por compatibilidad.", + ) + parser.add_argument( + "--number", + dest="phone_number", + metavar="PHONE", help="Numero telefonico mexicano a escanear.", ) parser.add_argument( @@ -44,29 +51,43 @@ def build_parser() -> argparse.ArgumentParser: return parser -def _to_legacy_argv(args: argparse.Namespace) -> list[str]: - """Translate argparse output to the existing scanner argument format.""" - argv: list[str] = [] +def _scan_number(args: argparse.Namespace) -> Optional[str]: + return args.phone_number or args.number + + +def _to_scanner_argv(args: argparse.Namespace) -> List[str]: + """Translate CLI options to the scanner argument format.""" + argv = [] if args.dummy_test: argv.append("--dummy-test") if args.small_banner: argv.append("--small-banner") if args.ip: argv.extend(["--ip", args.ip]) - elif args.number: - argv.append(args.number) + else: + number = _scan_number(args) + if number: + argv.append(number) return argv -def main(argv: list[str] | None = None) -> int: +def run(argv: Optional[List[str]] = None) -> int: parser = build_parser() args = parser.parse_args(argv) - if not args.ip and not args.number: + if args.ip and _scan_number(args): + parser.error("usa --ip o --number, no ambos") + + if not args.ip and not _scan_number(args): parser.print_help() return 1 from mexicosint import main as app - app.main(_to_legacy_argv(args)) + app.main(_to_scanner_argv(args)) return 0 + + +def main(argv: Optional[List[str]] = None) -> int: + """Backward-compatible wrapper for older entry-point references.""" + return run(argv) From 0d253224c8829c6ac17acd376f5aac176dd523e5 Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 9 Jul 2026 21:24:30 -0700 Subject: [PATCH 11/23] feat(build): add package CLI entry point --- pyproject.toml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 7b79ead..c4a5143 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -14,7 +14,6 @@ dependencies = [ "requests>=2.28.0", "urllib3<2", "beautifulsoup4>=4.11.0", - "python-dotenv>=0.19.0", "lxml>=4.9.0", "phonenumbers>=8.13.0", "rich>=13.0.0", @@ -23,7 +22,7 @@ dependencies = [ ] [project.scripts] -mexicosint = "mexicosint.cli:main" +mexicosint = "mexicosint.cli:run" [tool.setuptools.packages.find] where = ["src"] From 7111a06828411d6c75b6a21130edebc2bc52eb6e Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 9 Jul 2026 21:24:39 -0700 Subject: [PATCH 12/23] chore(cli): route module execution through run --- src/mexicosint/__main__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/mexicosint/__main__.py b/src/mexicosint/__main__.py index f32ed97..e010681 100644 --- a/src/mexicosint/__main__.py +++ b/src/mexicosint/__main__.py @@ -1,7 +1,7 @@ """Module entry point for `python -m mexicosint`.""" -from mexicosint.cli import main +from mexicosint.cli import run if __name__ == "__main__": - raise SystemExit(main()) + raise SystemExit(run()) From 46fd6baee4e51f20e2b7d55088419fa55f717a09 Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 9 Jul 2026 21:25:30 -0700 Subject: [PATCH 13/23] chore(deps): define runtime requirements --- requirements.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/requirements.txt b/requirements.txt index 10725b7..24bc7b6 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,9 +1,8 @@ requests>=2.28.0 urllib3<2 beautifulsoup4>=4.11.0 -python-dotenv>=0.19.0 lxml>=4.9.0 phonenumbers>=8.13.0 rich>=13.0.0 opencage>=3.0.0 -folium>=0.14.0 +folium>=0.14.0 From c1593bd893dde1110022f71339ad73ae0ac9a2d3 Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 9 Jul 2026 21:25:36 -0700 Subject: [PATCH 14/23] refactor(modules): keep parser compatible with Python 3.8 --- src/mexicosint/modules/local_parser.py | 86 +++++++++++++------------- 1 file changed, 42 insertions(+), 44 deletions(-) diff --git a/src/mexicosint/modules/local_parser.py b/src/mexicosint/modules/local_parser.py index f95a607..b32436d 100644 --- a/src/mexicosint/modules/local_parser.py +++ b/src/mexicosint/modules/local_parser.py @@ -5,14 +5,16 @@ Uses phonenumbers lib + hardcoded MNC/LADA tables. """ +from typing import Optional + import phonenumbers from phonenumbers import geocoder, carrier, timezone, PhoneNumberType -# Mexico MNC → Carrier mapping +# Mexico MNC -> Carrier mapping MNC_CARRIERS = { - "010": "Telcel (América Móvil)", - "020": "Telcel (América Móvil)", - "030": "Movistar (Telefónica)", + "010": "Telcel (America Movil)", + "020": "Telcel (America Movil)", + "030": "Movistar (Telefonica)", "040": "Unefon (AT&T)", "050": "Unefon (AT&T)", "060": "Unefon (AT&T)", @@ -20,7 +22,7 @@ "080": "Unefon (AT&T)", "090": "AT&T Mexico", "100": "AT&T Mexico", - "140": "Altán Redes (Red Compartida)", + "140": "Altan Redes (Red Compartida)", "150": "Ultra Wey (MVNO)", "160": "Maz Tiempo (MVNO)", } @@ -40,15 +42,15 @@ PhoneNumberType.UNKNOWN: "UNKNOWN", } -# Major LADA → State/City mapping +# Major LADA -> State/City mapping LADA_MAP = { - "55": ("Ciudad de México", "CDMX"), - "56": ("Ciudad de México", "CDMX"), - "81": ("Monterrey", "Nuevo León"), - "33": ("Guadalajara", "Jalisco"), + "55": ("Ciudad de Mexico", "CDMX"), + "56": ("Ciudad de Mexico", "CDMX"), + "81": ("Monterrey", "Nuevo Leon"), + "33": ("Guadalajara", "Jalisco"), "222": ("Puebla", "Puebla"), - "999": ("Mérida", "Yucatán"), - "442": ("Querétaro", "Querétaro"), + "999": ("Merida", "Yucatan"), + "442": ("Queretaro", "Queretaro"), "686": ("Mexicali", "Baja California"), "663": ("Tijuana", "Baja California"), "664": ("Tijuana", "Baja California"), @@ -57,36 +59,37 @@ "229": ("Veracruz", "Veracruz"), "938": ("Villahermosa", "Tabasco"), "983": ("Chetumal", "Quintana Roo"), - "871": ("Torreón", "Coahuila"), + "871": ("Torreon", "Coahuila"), "844": ("Saltillo", "Coahuila"), - "477": ("León", "Guanajuato"), - "722": ("Toluca", "México"), + "477": ("Leon", "Guanajuato"), + "722": ("Toluca", "Mexico"), "246": ("Tlaxcala", "Tlaxcala"), "312": ("Colima", "Colima"), "322": ("Puerto Vallarta", "Jalisco"), - "667": ("Culiacán", "Sinaloa"), - "668": ("Mazatlán", "Sinaloa"), + "667": ("Culiacan", "Sinaloa"), + "668": ("Mazatlan", "Sinaloa"), "631": ("Nogales", "Sonora"), "662": ("Hermosillo", "Sonora"), - "961": ("Tuxtla Gutiérrez", "Chiapas"), + "961": ("Tuxtla Gutierrez", "Chiapas"), "962": ("Tapachula", "Chiapas"), "735": ("Cuernavaca", "Morelos"), "771": ("Pachuca", "Hidalgo"), "773": ("Tulancingo", "Hidalgo"), "747": ("Chilpancingo", "Guerrero"), - "753": ("Lázaro Cárdenas", "Michoacán"), - "443": ("Morelia", "Michoacán"), - "341": ("Ciudad Guzmán", "Jalisco"), + "753": ("Lazaro Cardenas", "Michoacan"), + "443": ("Morelia", "Michoacan"), + "341": ("Ciudad Guzman", "Jalisco"), "834": ("Tampico", "Tamaulipas"), "899": ("Reynosa", "Tamaulipas"), "867": ("Nuevo Laredo", "Tamaulipas"), } + def parse_mx_number(raw: str) -> dict: """ Normalize and parse a Mexican phone number. Input: raw string (e.g., '+52 1 55 1234 5678', '5512345678', '55-1234-5678') - Returns: dict with normalized 10-digit number, E164, LADA, state, city, + Returns: dict with normalized 10-digit number, E164, LADA, state, city, carrier hint, timezone, is_valid, number_type, is_mobile """ result = { @@ -103,20 +106,16 @@ def parse_mx_number(raw: str) -> dict: "is_mobile": False, } - # Strip common noise cleaned = raw.strip().replace("-", "").replace(" ", "").replace("(", "").replace(")", "") - - # Handle numbers that already include +52 or 52 prefix + if cleaned.startswith("+52"): cleaned = cleaned[3:] elif cleaned.startswith("52"): cleaned = cleaned[2:] - - # Handle the '1' mobile prefix (post-2019 reform: +52 1 AA XXXX XXXX) + if len(cleaned) == 11 and cleaned.startswith("1"): cleaned = cleaned[1:] - - # Must be exactly 10 digits now + if not cleaned.isdigit() or len(cleaned) != 10: result["error"] = f"Invalid length or characters after cleaning: {cleaned}" return result @@ -125,10 +124,9 @@ def parse_mx_number(raw: str) -> dict: result["e164"] = f"+52{cleaned}" result["is_valid"] = True - # Extract LADA (first 2 or 3 digits) lada_3 = cleaned[:3] lada_2 = cleaned[:2] - + if lada_3 in LADA_MAP: result["lada"] = lada_3 result["city"], result["state"] = LADA_MAP[lada_3] @@ -136,44 +134,44 @@ def parse_mx_number(raw: str) -> dict: result["lada"] = lada_2 result["city"], result["state"] = LADA_MAP[lada_2] else: - result["lada"] = lada_2 # fallback + result["lada"] = lada_2 - # Use phonenumbers library for deeper parsing try: parsed = phonenumbers.parse(result["e164"], None) result["is_valid"] = phonenumbers.is_valid_number(parsed) - + num_type = phonenumbers.number_type(parsed) result["number_type"] = TYPE_MAP.get(num_type, f"UNKNOWN_ENUM({num_type})") - - # In Mexico, FIXED_LINE_OR_MOBILE means "could be either" but in practice - # nearly all 10-digit numbers are mobile. We flag it as likely mobile. + if num_type == PhoneNumberType.MOBILE: result["is_mobile"] = True elif num_type == PhoneNumberType.FIXED_LINE_OR_MOBILE: - result["is_mobile"] = True # Mexico reality: almost certainly mobile + result["is_mobile"] = True elif num_type == PhoneNumberType.FIXED_LINE: result["is_mobile"] = False else: result["is_mobile"] = False - - # Timezone + tz = timezone.time_zones_for_number(parsed) result["timezone"] = list(tz) if tz else [] - - # Carrier from phonenumbers (best-effort, often generic for MX) + carrier_name = carrier.name_for_number(parsed, "es") if carrier_name: result["carrier_hint"] = carrier_name - + except Exception as e: result["phonenumbers_error"] = str(e) return result +def _extract_label_value(*_args, **_kwargs) -> Optional[str]: + return None + + if __name__ == "__main__": + import json import sys + test = sys.argv[1] if len(sys.argv) > 1 else "5512345678" - import json print(json.dumps(parse_mx_number(test), indent=2, ensure_ascii=False)) From aaa1e2942983cb60f0ca9b0f935403682b1ec69e Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 9 Jul 2026 21:26:31 -0700 Subject: [PATCH 15/23] refactor(modules): preserve local parser behavior --- src/mexicosint/modules/local_parser.py | 86 +++++++++++++------------- 1 file changed, 44 insertions(+), 42 deletions(-) diff --git a/src/mexicosint/modules/local_parser.py b/src/mexicosint/modules/local_parser.py index b32436d..f95a607 100644 --- a/src/mexicosint/modules/local_parser.py +++ b/src/mexicosint/modules/local_parser.py @@ -5,16 +5,14 @@ Uses phonenumbers lib + hardcoded MNC/LADA tables. """ -from typing import Optional - import phonenumbers from phonenumbers import geocoder, carrier, timezone, PhoneNumberType -# Mexico MNC -> Carrier mapping +# Mexico MNC → Carrier mapping MNC_CARRIERS = { - "010": "Telcel (America Movil)", - "020": "Telcel (America Movil)", - "030": "Movistar (Telefonica)", + "010": "Telcel (América Móvil)", + "020": "Telcel (América Móvil)", + "030": "Movistar (Telefónica)", "040": "Unefon (AT&T)", "050": "Unefon (AT&T)", "060": "Unefon (AT&T)", @@ -22,7 +20,7 @@ "080": "Unefon (AT&T)", "090": "AT&T Mexico", "100": "AT&T Mexico", - "140": "Altan Redes (Red Compartida)", + "140": "Altán Redes (Red Compartida)", "150": "Ultra Wey (MVNO)", "160": "Maz Tiempo (MVNO)", } @@ -42,15 +40,15 @@ PhoneNumberType.UNKNOWN: "UNKNOWN", } -# Major LADA -> State/City mapping +# Major LADA → State/City mapping LADA_MAP = { - "55": ("Ciudad de Mexico", "CDMX"), - "56": ("Ciudad de Mexico", "CDMX"), - "81": ("Monterrey", "Nuevo Leon"), - "33": ("Guadalajara", "Jalisco"), + "55": ("Ciudad de México", "CDMX"), + "56": ("Ciudad de México", "CDMX"), + "81": ("Monterrey", "Nuevo León"), + "33": ("Guadalajara", "Jalisco"), "222": ("Puebla", "Puebla"), - "999": ("Merida", "Yucatan"), - "442": ("Queretaro", "Queretaro"), + "999": ("Mérida", "Yucatán"), + "442": ("Querétaro", "Querétaro"), "686": ("Mexicali", "Baja California"), "663": ("Tijuana", "Baja California"), "664": ("Tijuana", "Baja California"), @@ -59,37 +57,36 @@ "229": ("Veracruz", "Veracruz"), "938": ("Villahermosa", "Tabasco"), "983": ("Chetumal", "Quintana Roo"), - "871": ("Torreon", "Coahuila"), + "871": ("Torreón", "Coahuila"), "844": ("Saltillo", "Coahuila"), - "477": ("Leon", "Guanajuato"), - "722": ("Toluca", "Mexico"), + "477": ("León", "Guanajuato"), + "722": ("Toluca", "México"), "246": ("Tlaxcala", "Tlaxcala"), "312": ("Colima", "Colima"), "322": ("Puerto Vallarta", "Jalisco"), - "667": ("Culiacan", "Sinaloa"), - "668": ("Mazatlan", "Sinaloa"), + "667": ("Culiacán", "Sinaloa"), + "668": ("Mazatlán", "Sinaloa"), "631": ("Nogales", "Sonora"), "662": ("Hermosillo", "Sonora"), - "961": ("Tuxtla Gutierrez", "Chiapas"), + "961": ("Tuxtla Gutiérrez", "Chiapas"), "962": ("Tapachula", "Chiapas"), "735": ("Cuernavaca", "Morelos"), "771": ("Pachuca", "Hidalgo"), "773": ("Tulancingo", "Hidalgo"), "747": ("Chilpancingo", "Guerrero"), - "753": ("Lazaro Cardenas", "Michoacan"), - "443": ("Morelia", "Michoacan"), - "341": ("Ciudad Guzman", "Jalisco"), + "753": ("Lázaro Cárdenas", "Michoacán"), + "443": ("Morelia", "Michoacán"), + "341": ("Ciudad Guzmán", "Jalisco"), "834": ("Tampico", "Tamaulipas"), "899": ("Reynosa", "Tamaulipas"), "867": ("Nuevo Laredo", "Tamaulipas"), } - def parse_mx_number(raw: str) -> dict: """ Normalize and parse a Mexican phone number. Input: raw string (e.g., '+52 1 55 1234 5678', '5512345678', '55-1234-5678') - Returns: dict with normalized 10-digit number, E164, LADA, state, city, + Returns: dict with normalized 10-digit number, E164, LADA, state, city, carrier hint, timezone, is_valid, number_type, is_mobile """ result = { @@ -106,16 +103,20 @@ def parse_mx_number(raw: str) -> dict: "is_mobile": False, } + # Strip common noise cleaned = raw.strip().replace("-", "").replace(" ", "").replace("(", "").replace(")", "") - + + # Handle numbers that already include +52 or 52 prefix if cleaned.startswith("+52"): cleaned = cleaned[3:] elif cleaned.startswith("52"): cleaned = cleaned[2:] - + + # Handle the '1' mobile prefix (post-2019 reform: +52 1 AA XXXX XXXX) if len(cleaned) == 11 and cleaned.startswith("1"): cleaned = cleaned[1:] - + + # Must be exactly 10 digits now if not cleaned.isdigit() or len(cleaned) != 10: result["error"] = f"Invalid length or characters after cleaning: {cleaned}" return result @@ -124,9 +125,10 @@ def parse_mx_number(raw: str) -> dict: result["e164"] = f"+52{cleaned}" result["is_valid"] = True + # Extract LADA (first 2 or 3 digits) lada_3 = cleaned[:3] lada_2 = cleaned[:2] - + if lada_3 in LADA_MAP: result["lada"] = lada_3 result["city"], result["state"] = LADA_MAP[lada_3] @@ -134,44 +136,44 @@ def parse_mx_number(raw: str) -> dict: result["lada"] = lada_2 result["city"], result["state"] = LADA_MAP[lada_2] else: - result["lada"] = lada_2 + result["lada"] = lada_2 # fallback + # Use phonenumbers library for deeper parsing try: parsed = phonenumbers.parse(result["e164"], None) result["is_valid"] = phonenumbers.is_valid_number(parsed) - + num_type = phonenumbers.number_type(parsed) result["number_type"] = TYPE_MAP.get(num_type, f"UNKNOWN_ENUM({num_type})") - + + # In Mexico, FIXED_LINE_OR_MOBILE means "could be either" but in practice + # nearly all 10-digit numbers are mobile. We flag it as likely mobile. if num_type == PhoneNumberType.MOBILE: result["is_mobile"] = True elif num_type == PhoneNumberType.FIXED_LINE_OR_MOBILE: - result["is_mobile"] = True + result["is_mobile"] = True # Mexico reality: almost certainly mobile elif num_type == PhoneNumberType.FIXED_LINE: result["is_mobile"] = False else: result["is_mobile"] = False - + + # Timezone tz = timezone.time_zones_for_number(parsed) result["timezone"] = list(tz) if tz else [] - + + # Carrier from phonenumbers (best-effort, often generic for MX) carrier_name = carrier.name_for_number(parsed, "es") if carrier_name: result["carrier_hint"] = carrier_name - + except Exception as e: result["phonenumbers_error"] = str(e) return result -def _extract_label_value(*_args, **_kwargs) -> Optional[str]: - return None - - if __name__ == "__main__": - import json import sys - test = sys.argv[1] if len(sys.argv) > 1 else "5512345678" + import json print(json.dumps(parse_mx_number(test), indent=2, ensure_ascii=False)) From 6d6be83c287f3ee0b3dcb2f97428085e2c1fd0f4 Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 9 Jul 2026 21:26:55 -0700 Subject: [PATCH 16/23] chore(cli): remove legacy shell launcher --- bin/mexicosint | 16 ---------------- 1 file changed, 16 deletions(-) delete mode 100755 bin/mexicosint diff --git a/bin/mexicosint b/bin/mexicosint deleted file mode 100755 index 2f24c75..0000000 --- a/bin/mexicosint +++ /dev/null @@ -1,16 +0,0 @@ -#!/usr/bin/env bash - -# MeXiCOSINT launcher -# This lets users run the tool without typing the full Python filename. - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" - -cd "$REPO_ROOT" || exit 1 - -PYTHON_BIN="$REPO_ROOT/venv/bin/python" -if [[ ! -x "$PYTHON_BIN" ]]; then - PYTHON_BIN="python3" -fi - -PYTHONPATH="$REPO_ROOT/src${PYTHONPATH:+:$PYTHONPATH}" "$PYTHON_BIN" -m mexicosint "$@" From 27b7d2687190a92727adcc2f430dcd87dc031c30 Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 9 Jul 2026 21:27:06 -0700 Subject: [PATCH 17/23] chore(git): ignore local secrets and generated files --- .gitignore | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index c9dabf6..b2ffe5f 100644 --- a/.gitignore +++ b/.gitignore @@ -22,14 +22,18 @@ pip-delete-this-directory.txt # Local config / API keys .env *.env +.mx_osint_config.json config.json secrets.json keys.json -.mx_osint_config.json +tokens.json +credentials.json +*.local.json +*.config.json *.key *.pem -# OS junk +# OS files .DS_Store Thumbs.db From 4801e5f65668a24e675d9d5a95db0a20620daba2 Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 9 Jul 2026 21:35:26 -0700 Subject: [PATCH 18/23] docs(readme): document package install and CLI usage --- README.md | 51 ++++++++++++++++++++++++++------------------------- 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index caaea95..e010bd4 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ La herramienta puede validar números, analizar formatos mexicanos, consultar fu - Enriquecimiento opcional mediante APIs externas - Procesamiento relacionado con IFT/SNS - Soporte para módulo QuienHabla.mx -- Launcher para ejecutar la herramienta sin escribir el nombre completo del script +- CLI instalable con el comando `mexicosint` - Configuración local de API keys - Soporte para reportes o salidas generadas según la versión @@ -45,8 +45,6 @@ La herramienta puede validar números, analizar formatos mexicanos, consultar fu ```text MeXiCOSINT/ -├── bin/ -│ └── mexicosint ├── docs/ │ ├── INSTALL.md │ ├── USAGE.md @@ -69,6 +67,7 @@ MeXiCOSINT/ │ └── validation.py ├── pyproject.toml ├── requirements.txt +├── MIGRATION.md ├── .gitignore ├── LICENSE └── README.md @@ -82,62 +81,59 @@ Clona el repositorio: ```bash git clone https://github.com/KiMiGuel/MeXiCOSINT.git -``` - -Entra a la carpeta del proyecto: - -```bash cd MeXiCOSINT ``` -Crea un entorno virtual: +Crea y activa un entorno virtual: ```bash python3 -m venv venv -``` - -Activa el entorno virtual: - -```bash source venv/bin/activate ``` -Instala las dependencias: +Instala el paquete en modo editable: ```bash -pip install -r requirements.txt +pip install -e . ``` -Instala el paquete en modo editable: +También puedes instalar las dependencias explícitas para desarrollo: ```bash -pip install -e . +pip install -r requirements.txt ``` --- ## Uso -Ejecuta MeXiCOSINT usando el launcher: +Ejecuta MeXiCOSINT con el comando instalado: + +```bash +mexicosint --number 5512345678 +mexicosint --number +525512345678 +mexicosint -b --number 5512345678 +``` + +El número posicional se mantiene por compatibilidad: ```bash mexicosint 5512345678 -mexicosint -b 5512345678 ``` -Tambien puedes usar el launcher del repositorio sin instalar el comando global: +Modo IP directo: ```bash -bash bin/mexicosint 5512345678 +mexicosint --ip 8.8.8.8 ``` -O ejecutar el modulo del paquete: +Ejecutar sin instalar el comando global: ```bash -PYTHONPATH=src python3 -m mexicosint 5512345678 +PYTHONPATH=src python3 -m mexicosint --number 5512345678 ``` -Use `-b`, `--compact-banner`, or the legacy `--small-banner` flag to force the compact ASCII banner. +Usa `-b`, `--compact-banner` o el alias heredado `--small-banner` para forzar el banner compacto. --- @@ -148,6 +144,7 @@ Use `-b`, `--compact-banner`, or the legacy `--small-banner` flag to force the c | [Guía de instalación](docs/INSTALL.md) | Instrucciones de instalación para Kali, Debian, Ubuntu y sistemas similares | | [Guía de uso](docs/USAGE.md) | Uso básico y notas de ejecución | | [Guía de configuración](docs/CONFIG.md) | Configuración local y manejo de API keys | +| [Migración](MIGRATION.md) | Cambios de estructura para el paquete instalable | --- @@ -178,6 +175,10 @@ No subas archivos como: config.json secrets.json keys.json +tokens.json +credentials.json +*.local.json +*.config.json .mx_osint_config.json ``` From fe929170f518b23330855bf9661fd34433dddbdf Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 9 Jul 2026 21:37:25 -0700 Subject: [PATCH 19/23] docs(migration): explain package structure changes --- MIGRATION.md | 44 +++++++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 53fc7c8..24dc4dc 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -1,16 +1,17 @@ # Migration Instructions -MeXiCOSINT now uses a production-style `src/` package layout. +MeXiCOSINT now uses a production-style `src/` package layout and an installable console command. ## What changed -- `mexicosint_v2.2.5.py` was replaced by `src/mexicosint/main.py`. -- The command-line entry point is now `src/mexicosint/cli.py`. -- Existing helper modules moved from `modules/` to `src/mexicosint/modules/`. +- The versioned script was replaced by `src/mexicosint/main.py`. +- The command-line interface lives in `src/mexicosint/cli.py`. +- The package entry point is `mexicosint = mexicosint.cli:run` in `pyproject.toml`. +- Existing helper modules live in `src/mexicosint/modules/`. - Service-facing wrappers live in `src/mexicosint/services/`. - Shared helpers live in `src/mexicosint/utils/`. -- Package metadata and the console script are defined in `pyproject.toml`. -- Local IFT data moved into `src/mexicosint/data/` so it can be packaged. +- Local IFT data lives in `src/mexicosint/data/` so it can be packaged. +- The legacy `bin/mexicosint` shell launcher was removed; use the installed `mexicosint` command instead. ## Install for development @@ -20,27 +21,34 @@ source venv/bin/activate pip install -e . ``` +Optional explicit dependency install for development: + +```bash +pip install -r requirements.txt +``` + ## Run after migration Use the installed command: ```bash -mexicosint 5512345678 +mexicosint --number 5512345678 +mexicosint --number +525512345678 mexicosint --ip 8.8.8.8 -mexicosint --dummy-test 5512345678 -mexicosint -b 5512345678 +mexicosint --dummy-test --number 5512345678 +mexicosint -b --number 5512345678 ``` -Run without installing: +The positional number form remains available for compatibility: ```bash -PYTHONPATH=src python3 -m mexicosint 5512345678 +mexicosint 5512345678 ``` -Or use the repository launcher: +Run without installing: ```bash -bash bin/mexicosint 5512345678 +PYTHONPATH=src python3 -m mexicosint --number 5512345678 ``` ## Import changes @@ -53,3 +61,13 @@ from mexicosint.modules.ift_sns import consultar from mexicosint.modules.quienhabla import consultar as consultar_quienhabla from mexicosint.services.scanner import run_phone_scan ``` + +## Safe migration steps + +1. Create a branch before changing structure. +2. Move source files under `src/mexicosint/`. +3. Convert script execution to `src/mexicosint/cli.py` and `src/mexicosint/main.py`. +4. Configure `pyproject.toml` with the `mexicosint` console script. +5. Install with `pip install -e .` in a virtual environment. +6. Run `mexicosint --number 5512345678` and `PYTHONPATH=src python3 -m mexicosint --number 5512345678`. +7. Remove references to legacy shell launchers from docs and scripts. From 185c035a981d8638b13a22adeb58dd5aecde37ca Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 9 Jul 2026 21:37:28 -0700 Subject: [PATCH 20/23] docs(install): use editable package install --- docs/INSTALL.md | 79 +++++++++++++------------------------------------ 1 file changed, 20 insertions(+), 59 deletions(-) diff --git a/docs/INSTALL.md b/docs/INSTALL.md index c78ba2b..2119d6e 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -17,9 +17,6 @@ Instala los requisitos base con: ```bash sudo apt update -``` - -```bash sudo apt install -y python3 python3-pip python3-venv git ``` @@ -27,15 +24,8 @@ sudo apt install -y python3 python3-pip python3-venv git ## Clonar el repositorio -Clona el repositorio desde GitHub: - ```bash git clone https://github.com/KiMiGuel/MeXiCOSINT.git -``` - -Entra a la carpeta del proyecto: - -```bash cd MeXiCOSINT ``` @@ -45,50 +35,41 @@ cd MeXiCOSINT Se recomienda usar un entorno virtual para evitar conflictos con paquetes del sistema. -Crea el entorno virtual: - ```bash python3 -m venv venv -``` - -Activa el entorno virtual: - -```bash source venv/bin/activate ``` -Cuando el entorno virtual esté activo, tu terminal debería mostrar algo parecido a: +--- -```text -(venv) usuario@equipo:~/MeXiCOSINT$ -``` +## Instalar el paquete ---- +Instala MeXiCOSINT en modo editable desde la raíz del repositorio: -## Instalar dependencias +```bash +pip install -e . +``` -Instala las dependencias del proyecto: +Para desarrollo, también puedes instalar desde `requirements.txt`: ```bash pip install -r requirements.txt ``` -Si todo sale correctamente, MeXiCOSINT estará listo para ejecutarse. - --- ## Ejecutar MeXiCOSINT -La forma recomendada es usar el launcher incluido: +La forma recomendada es usar el comando instalado: ```bash -bash bin/mexicosint +mexicosint --number 5512345678 ``` -También puedes ejecutar directamente el archivo principal: +También puedes ejecutar el módulo del paquete sin instalar el comando global: ```bash -PYTHONPATH=src python3 -m mexicosint +PYTHONPATH=src python3 -m mexicosint --number 5512345678 ``` --- @@ -103,16 +84,12 @@ El archivo recomendado para configuración local es: ~/.mx_osint_config.json ``` -Este archivo debe quedarse en tu computadora. - -No debe subirse a GitHub. +Este archivo debe quedarse en tu computadora y no debe subirse a GitHub. --- ## Proteger archivo de configuración -Para proteger el archivo de configuración local: - ```bash chmod 600 ~/.mx_osint_config.json ``` @@ -121,10 +98,9 @@ chmod 600 ~/.mx_osint_config.json ## Actualizar MeXiCOSINT -Para actualizar el repositorio: - ```bash git pull +pip install -e . ``` Si las dependencias cambiaron, vuelve a ejecutar: @@ -137,8 +113,6 @@ pip install -r requirements.txt ## Salir del entorno virtual -Cuando termines de usar la herramienta: - ```bash deactivate ``` @@ -147,8 +121,6 @@ deactivate ## Instalación rápida -Resumen completo: - ```bash sudo apt update sudo apt install -y python3 python3-pip python3-venv git @@ -156,8 +128,8 @@ git clone https://github.com/KiMiGuel/MeXiCOSINT.git cd MeXiCOSINT python3 -m venv venv source venv/bin/activate -pip install -r requirements.txt -bash bin/mexicosint +pip install -e . +mexicosint --number 5512345678 ``` --- @@ -176,38 +148,29 @@ bash bin/mexicosint ### `python3: command not found` -Instala Python: - ```bash sudo apt install -y python3 ``` ### `pip: command not found` -Instala pip: - ```bash sudo apt install -y python3-pip ``` ### Error creando el entorno virtual -Instala venv: - ```bash sudo apt install -y python3-venv ``` -### Error de permisos - -Asegúrate de estar dentro de la carpeta del proyecto y de tener permisos sobre los archivos. +### El comando `mexicosint` no existe -```bash -pwd -``` +Confirma que el entorno virtual está activo y reinstala el paquete: ```bash -ls -la +source venv/bin/activate +pip install -e . ``` --- @@ -217,7 +180,5 @@ ls -la Si la instalación terminó correctamente, deberías poder ejecutar: ```bash -bash bin/mexicosint +mexicosint --number 5512345678 ``` - -Y ver el inicio de MeXiCOSINT en la terminal. From 07dacbbe7ad36671152379ef4bdb9d5cdca1cfd3 Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 9 Jul 2026 21:37:31 -0700 Subject: [PATCH 21/23] docs(usage): document mexicosint command --- docs/USAGE.md | 206 +++++++++----------------------------------------- 1 file changed, 37 insertions(+), 169 deletions(-) diff --git a/docs/USAGE.md b/docs/USAGE.md index d80fb5d..6137522 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -6,38 +6,32 @@ Esta guía explica cómo ejecutar y usar **MeXiCOSINT** después de instalarlo. ## Antes de empezar -Asegúrate de estar dentro de la carpeta del proyecto: - -```bash -cd MeXiCOSINT -``` - -Activa el entorno virtual: +Activa el entorno virtual donde instalaste el paquete: ```bash source venv/bin/activate ``` -Si el entorno virtual está activo, tu terminal debería mostrar algo parecido a: - -```text -(venv) usuario@equipo:~/MeXiCOSINT$ -``` - --- ## Ejecutar MeXiCOSINT -La forma recomendada es usar el launcher incluido: +La forma recomendada es usar el comando instalado: ```bash -bash bin/mexicosint +mexicosint --number 5512345678 ``` -También puedes ejecutar directamente el archivo principal: +También puedes usar el número como argumento posicional por compatibilidad: ```bash -PYTHONPATH=src python3 -m mexicosint +mexicosint 5512345678 +``` + +Para ejecutar sin instalar el comando global: + +```bash +PYTHONPATH=src python3 -m mexicosint --number 5512345678 ``` --- @@ -46,51 +40,44 @@ PYTHONPATH=src python3 -m mexicosint MeXiCOSINT está enfocado en números telefónicos mexicanos. -Formato recomendado: +Formato internacional: ```text +52XXXXXXXXXX ``` -También puede aceptar formato nacional de 10 dígitos: +Formato nacional de 10 dígitos: ```text XXXXXXXXXX ``` -Ejemplo de formato internacional: - -```text -+525512345678 -``` - -Ejemplo de formato nacional: +Ejemplos: -```text -5512345678 +```bash +mexicosint --number +525512345678 +mexicosint --number 5512345678 ``` --- -## Flujo básico de uso - -1. Ejecuta la herramienta: +## Opciones principales ```bash -bash bin/mexicosint +mexicosint --number 5512345678 +mexicosint --ip 8.8.8.8 +mexicosint --dummy-test --number 5512345678 +mexicosint -b --number 5512345678 +mexicosint --version ``` -2. Ingresa el número telefónico cuando la herramienta lo solicite. - -3. Revisa los resultados mostrados en terminal. - -4. Si la herramienta genera reportes, revisa los archivos creados dentro del proyecto. +`-b`, `--compact-banner` y `--small-banner` fuerzan el banner compacto. --- ## Resultados posibles -Dependiendo de la versión, configuración y API keys disponibles, MeXiCOSINT puede mostrar información como: +Dependiendo de la configuración y API keys disponibles, MeXiCOSINT puede mostrar información como: * Validación del número * Formato nacional @@ -107,86 +94,39 @@ Dependiendo de la versión, configuración y API keys disponibles, MeXiCOSINT pu ## APIs y resultados limitados -MeXiCOSINT puede funcionar parcialmente sin API keys. - -Sin embargo, algunas funciones pueden estar limitadas si no configuraste servicios externos. - -Ejemplo: +MeXiCOSINT puede funcionar parcialmente sin API keys. Algunas funciones estarán limitadas si no configuraste servicios externos. ```text Sin API key: validación local y parsing básico Con API key: enriquecimiento adicional según el servicio configurado ``` -Para configurar API keys, revisa: - -```text -docs/CONFIG.md -``` +Para configurar API keys, revisa `docs/CONFIG.md`. --- ## Reportes y archivos generados -Si la herramienta genera reportes, pueden aparecer archivos como: - -```text -reporte.json -``` - -```text -reporte.html -``` - -```text -reporte_mapa.html -``` - -Los nombres exactos pueden cambiar según la versión. - -También puede haber carpetas como: - -```text -reports/ -``` +Los reportes generados se escriben dentro de carpetas ignoradas por Git, como: ```text output/ -``` - -```text +reports/ results/ ``` -Si no aparece ningún reporte, revisa la salida en terminal para confirmar si la función está disponible en tu versión. - ---- - -## Modo de prueba o desarrollo - -Si la versión incluye un modo de prueba, puede ejecutarse con una bandera especial. - -Ejemplo: - -```bash -PYTHONPATH=src python3 -m mexicosint --dummy-test -``` - -Este modo está pensado para desarrollo local. - -No debe considerarse una función principal para usuarios finales. +No publiques reportes con información sensible. --- ## Actualizar antes de usar -Para actualizar el repositorio: - ```bash git pull +pip install -e . ``` -Después, si cambiaron las dependencias: +Si cambiaron las dependencias: ```bash pip install -r requirements.txt @@ -194,16 +134,6 @@ pip install -r requirements.txt --- -## Salir del entorno virtual - -Cuando termines: - -```bash -deactivate -``` - ---- - ## Buenas prácticas * Verifica resultados con más de una fuente. @@ -216,88 +146,26 @@ deactivate ## Solución rápida de problemas -### El comando `bash bin/mexicosint` no funciona - -Confirma que estás dentro de la carpeta del proyecto: - -```bash -pwd -``` - -Confirma que existe el launcher: - -```bash -ls -la bin -``` +### El comando `mexicosint` no funciona -Ejecuta otra vez: +Confirma que el entorno virtual está activo y que el paquete fue instalado: ```bash -bash bin/mexicosint +source venv/bin/activate +pip install -e . ``` ---- - ### Error de dependencias -Vuelve a instalar los requisitos: - ```bash pip install -r requirements.txt ``` ---- - -### Error con el entorno virtual - -Recrea el entorno virtual: - -```bash -rm -rf venv -``` - -```bash -python3 -m venv venv -``` - -```bash -source venv/bin/activate -``` - -```bash -pip install -r requirements.txt -``` - ---- - ### API key no detectada -Revisa que el archivo de configuración exista: - ```bash ls -la ~/.mx_osint_config.json -``` - -Revisa permisos: - -```bash chmod 600 ~/.mx_osint_config.json ``` -Revisa la guía de configuración: - -```text -docs/CONFIG.md -``` - ---- - -## Estado - -Si todo está correcto, deberías poder ejecutar: - -```bash -bash bin/mexicosint -``` - -Y ver el inicio de MeXiCOSINT en terminal. +Revisa `docs/CONFIG.md`. From 062a34782014cdd9abf482fca5edf320e8fc3cd2 Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 9 Jul 2026 21:37:36 -0700 Subject: [PATCH 22/23] docs(config): align config keys with package CLI --- docs/CONFIG.md | 168 ++++++------------------------------------------- 1 file changed, 20 insertions(+), 148 deletions(-) diff --git a/docs/CONFIG.md b/docs/CONFIG.md index c14d408..f877ed9 100644 --- a/docs/CONFIG.md +++ b/docs/CONFIG.md @@ -14,32 +14,28 @@ La ruta recomendada es: ~/.mx_osint_config.json ``` -Este archivo debe existir solamente en tu computadora. - -No debe subirse a GitHub. +Este archivo debe existir solamente en tu computadora y no debe subirse a GitHub. --- ## Crear el archivo de configuración -Puedes crear el archivo con: +La primera ejecución puede crear un archivo base. También puedes crearlo manualmente: ```bash nano ~/.mx_osint_config.json ``` -Dentro del archivo puedes agregar tus API keys. - Ejemplo: ```json { - "abstractapi_key": "TU_ABSTRACTAPI_KEY", - "numverify_key": "TU_NUMVERIFY_KEY", - "shodan_key": "TU_SHODAN_KEY", - "ipinfo_key": "TU_IPINFO_KEY", - "ip2location_key": "TU_IP2LOCATION_KEY", - "opencage_key": "TU_OPENCAGE_KEY" + "abstract_phone_intelligence": "TU_ABSTRACTAPI_KEY", + "numverify": "TU_NUMVERIFY_KEY", + "shodan": "TU_SHODAN_KEY", + "ipinfo": "TU_IPINFO_KEY", + "ip2location": "TU_IP2LOCATION_KEY", + "opencage": "TU_OPENCAGE_KEY" } ``` @@ -49,21 +45,17 @@ Reemplaza cada valor con tu propia API key. ## Proteger el archivo -Para proteger el archivo de configuración local: - ```bash chmod 600 ~/.mx_osint_config.json ``` -Esto limita el acceso al archivo únicamente a tu usuario. +Esto limita el acceso del archivo únicamente a tu usuario. --- ## APIs opcionales -MeXiCOSINT puede funcionar parcialmente sin API keys. - -Sin embargo, algunas funciones tendrán mejores resultados si se configuran servicios externos. +MeXiCOSINT puede funcionar parcialmente sin API keys. Algunas funciones tendrán mejores resultados si configuras servicios externos. | Servicio | Función | | ----------- | ------------------------------------------------------------ | @@ -76,34 +68,10 @@ Sin embargo, algunas funciones tendrán mejores resultados si se configuran serv --- -## Funcionamiento sin API keys - -Si no configuras API keys, MeXiCOSINT puede seguir funcionando parcialmente. - -Ejemplo: - -```text -Sin API keys: -- Validación local -- Parsing básico -- Formato nacional/internacional -- Resultados limitados - -Con API keys: -- Enriquecimiento adicional -- Validación secundaria -- Más fuentes de comparación -- Mejor contexto para reportes -``` - ---- - ## Archivos que NO deben subirse No subas archivos que contengan claves, tokens o datos sensibles. -Ejemplos: - ```text .env *.env @@ -113,33 +81,19 @@ secrets.json keys.json tokens.json credentials.json +*.local.json +*.config.json ``` -Si uno de estos archivos aparece en GitHub por accidente, elimina el archivo y rota las claves afectadas. - -Porque sí, una API key subida a GitHub se convierte en comida gratis para bots antes de que termines de pestañear. Qué civilización tan brillante. +Si una clave llega a GitHub por accidente, elimina el archivo del repositorio y rota las claves afectadas. --- ## Revisar antes de hacer commit -Antes de subir cambios, puedes buscar posibles claves dentro del proyecto: - ```bash grep -Ri "api_key\|apikey\|token\|secret\|password\|credential" . -``` - -Si aparece una clave real, elimínala antes de hacer commit. - -También puedes revisar los archivos modificados con: - -```bash git status -``` - -Y revisar diferencias con: - -```bash git diff ``` @@ -147,8 +101,6 @@ git diff ## Configuración recomendada en `.gitignore` -El archivo `.gitignore` debe incluir entradas para evitar subir secretos por accidente: - ```gitignore .env *.env @@ -158,94 +110,26 @@ secrets.json keys.json tokens.json credentials.json +*.local.json +*.config.json *.key *.pem ``` --- -## Estructura recomendada - -La configuración sensible debe vivir fuera del repositorio: - -```text -/home/usuario/.mx_osint_config.json -``` - -o: - -```text -~/.mx_osint_config.json -``` - -El repositorio solo debe contener ejemplos, documentación y código. - ---- - -## Ejemplo seguro para documentación +## Ejecución con configuración local -Si quieres mostrar un ejemplo en la documentación, usa valores falsos: - -```json -{ - "abstractapi_key": "TU_ABSTRACTAPI_KEY", - "numverify_key": "TU_NUMVERIFY_KEY" -} -``` - -Nunca uses claves reales en ejemplos públicos. - ---- - -## Permisos recomendados - -Revisa los permisos actuales: - -```bash -ls -la ~/.mx_osint_config.json -``` - -Aplica permisos seguros: +Después de instalar el paquete: ```bash -chmod 600 ~/.mx_osint_config.json -``` - -Resultado esperado aproximado: - -```text --rw------- 1 usuario usuario ... /home/usuario/.mx_osint_config.json +mexicosint --number 5512345678 ``` ---- - -## Si subiste una API key por accidente - -1. Elimina la clave del repositorio. -2. Haz commit del cambio. -3. Entra al panel del proveedor de la API. -4. Revoca o elimina la API key expuesta. -5. Crea una API key nueva. -6. Actualiza tu archivo local `~/.mx_osint_config.json`. - -No basta con borrar la línea del README o del archivo actual. Git guarda historial. Porque Git es útil, pero también es un archivista con tendencias obsesivas. - ---- - -## Variables de entorno - -En futuras versiones, MeXiCOSINT también podría usar variables de entorno. - -Ejemplo: +Modo IP directo: ```bash -export ABSTRACTAPI_KEY="TU_ABSTRACTAPI_KEY" -``` - -Pero la forma recomendada para este proyecto es usar: - -```text -~/.mx_osint_config.json +mexicosint --ip 8.8.8.8 ``` --- @@ -259,15 +143,3 @@ Pero la forma recomendada para este proyecto es usar: * Rota cualquier clave que haya sido expuesta. * Usa ejemplos falsos en documentación pública. * Revisa cambios antes de hacer commit. - ---- - -## Estado - -Si el archivo existe y tiene permisos correctos, puedes ejecutar: - -```bash -bash bin/mexicosint -``` - -Y MeXiCOSINT debería poder leer la configuración local según las funciones disponibles en la versión actual. From 70a46c23ee6b8580a9e8fd870d5d4553714eb8eb Mon Sep 17 00:00:00 2001 From: KiMiGuel Date: Thu, 9 Jul 2026 21:45:25 -0700 Subject: [PATCH 23/23] ci(publish): add PyPI release workflow --- .github/workflows/publish.yml | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 .github/workflows/publish.yml diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..33473bf --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,33 @@ +name: Publish to PyPI + +on: + push: + tags: + - "v*" + +jobs: + build-and-publish: + runs-on: ubuntu-latest + + steps: + - name: Checkout repo + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.10" + + - name: Install build tools + run: | + python -m pip install --upgrade pip + pip install build twine + + - name: Build package + run: python -m build + + - name: Publish to PyPI + env: + TWINE_USERNAME: __token__ + TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} + run: twine upload dist/*