+
+
+
+ 
+ 
+ 
+ 
+
+ 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 -git clone https://github.com/metalpunx666/MeXiCOSINT.git +**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 +- CLI instalable con el comando `mexicosint` +- Configuración local de API keys +- Soporte para reportes o salidas generadas según la versión + +--- + +## Estructura del repositorio + +```text +MeXiCOSINT/ +├── docs/ +│ ├── INSTALL.md +│ ├── USAGE.md +│ └── CONFIG.md +├── 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 +├── MIGRATION.md +├── .gitignore +├── LICENSE +└── README.md +``` + +--- + +## Instalación + +Clona el repositorio: + +```bash +git clone https://github.com/KiMiGuel/MeXiCOSINT.git cd MeXiCOSINT +``` + +Crea y activa un entorno virtual: + +```bash python3 -m venv venv source venv/bin/activate +``` + +Instala el paquete en modo editable: + +```bash +pip install -e . +``` + +También puedes instalar las dependencias explícitas para desarrollo: + +```bash pip install -r requirements.txt +``` + +--- ## Uso -python3 mexicosint_v2.2.5.py +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 +``` + +Modo IP directo: + +```bash +mexicosint --ip 8.8.8.8 +``` + +Ejecutar sin instalar el comando global: + +```bash +PYTHONPATH=src python3 -m mexicosint --number 5512345678 +``` + +Usa `-b`, `--compact-banner` o el alias heredado `--small-banner` para forzar el banner compacto. + +--- + +## 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 | +| [Migración](MIGRATION.md) | Cambios de estructura para el paquete instalable | + +--- + +## 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 +tokens.json +credentials.json +*.local.json +*.config.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. + +--- + +## 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 +- 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. diff --git a/docs/CONFIG.md b/docs/CONFIG.md index 3f0b8b8..f877ed9 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,69 +8,138 @@ 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. +Este archivo debe existir solamente en tu computadora y no debe subirse a GitHub. -No debe subirse a GitHub. +--- -Permisos recomendados +## Crear el archivo de configuración -Para proteger el archivo: +La primera ejecución puede crear un archivo base. También puedes crearlo manualmente: -chmod 600 ~/.mx_osint_config.json -Ejemplo de configuración +```bash +nano ~/.mx_osint_config.json +``` -Ejemplo básico: +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" } +``` Reemplaza cada valor con tu propia API key. -APIs opcionales +--- + +## Proteger el archivo + +```bash +chmod 600 ~/.mx_osint_config.json +``` + +Esto limita el acceso del archivo únicamente a tu usuario. + +--- + +## APIs opcionales + +MeXiCOSINT puede funcionar parcialmente sin API keys. Algunas funciones tendrán mejores resultados si configuras servicios externos. -MeXiCOSINT puede funcionar parcialmente sin algunas API keys. +| 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 | -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 +--- -Antes de subir cambios, revisa que no hayas agregado tus claves por accidente. +## Archivos que NO deben subirse -Archivos que no deben subirse: +No subas archivos que contengan claves, tokens o datos sensibles. +```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 +*.local.json +*.config.json +``` -Desde terminal puedes revisar si hay claves visibles usando: +Si una clave llega a GitHub por accidente, elimina el archivo del repositorio y rota las claves afectadas. -grep -Ri "api_key\|apikey\|token\|secret\|password" . +--- + +## Revisar antes de hacer commit + +```bash +grep -Ri "api_key\|apikey\|token\|secret\|password\|credential" . +git status +git diff +``` + +--- + +## Configuración recomendada en `.gitignore` + +```gitignore +.env +*.env +.mx_osint_config.json +config.json +secrets.json +keys.json +tokens.json +credentials.json +*.local.json +*.config.json +*.key +*.pem +``` + +--- + +## Ejecución con configuración local + +Después de instalar el paquete: + +```bash +mexicosint --number 5512345678 +``` + +Modo IP directo: + +```bash +mexicosint --ip 8.8.8.8 +``` + +--- -Si aparece una clave real, elimínala antes de subir cambios. +## Buenas prácticas -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. +* 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. diff --git a/docs/ENGLISH.md b/docs/ENGLISH.md new file mode 100644 index 0000000..36fb24c --- /dev/null +++ b/docs/ENGLISH.md @@ -0,0 +1,643 @@ +# 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 +├── docs/ +│ ├── INSTALL.md +│ ├── USAGE.md +│ ├── CONFIG.md +│ └── ENGLISH.md +├── src/ +│ └── mexicosint/ +│ ├── cli.py +│ ├── main.py +│ ├── data/ +│ ├── modules/ +│ ├── services/ +│ └── utils/ +├── pyproject.toml +├── 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 +PYTHONPATH=src python3 -m mexicosint +``` + +--- + +## 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 +PYTHONPATH=src python3 -m mexicosint --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. diff --git a/docs/INSTALL.md b/docs/INSTALL.md index e369316..2119d6e 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -6,67 +6,179 @@ 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 sudo apt install -y python3 python3-pip python3-venv git -Instalación - -Clona el repositorio: +``` -git clone https://github.com/metalpunx666/MeXiCOSINT.git +--- -Entra al directorio: +## Clonar el repositorio +```bash +git clone https://github.com/KiMiGuel/MeXiCOSINT.git cd MeXiCOSINT +``` -Crea un entorno virtual: +--- -python3 -m venv venv +## Crear entorno virtual -Activa el entorno virtual: +Se recomienda usar un entorno virtual para evitar conflictos con paquetes del sistema. +```bash +python3 -m venv venv source venv/bin/activate +``` -Instala las dependencias: +--- +## Instalar el paquete + +Instala MeXiCOSINT en modo editable desde la raíz del repositorio: + +```bash +pip install -e . +``` + +Para desarrollo, también puedes instalar desde `requirements.txt`: + +```bash pip install -r requirements.txt -Uso básico +``` + +--- + +## Ejecutar MeXiCOSINT -Ejecuta la herramienta: +La forma recomendada es usar el comando instalado: -python3 mexicosint_v2.2.5.py -Configuración de API keys +```bash +mexicosint --number 5512345678 +``` + +También puedes ejecutar el módulo del paquete sin instalar el comando global: + +```bash +PYTHONPATH=src python3 -m mexicosint --number 5512345678 +``` + +--- -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 y no debe subirse a GitHub. -Protege el archivo: +--- +## Proteger archivo de configuración + +```bash chmod 600 ~/.mx_osint_config.json -Actualizar MeXiCOSINT +``` -Para actualizar el repositorio: +--- + +## Actualizar MeXiCOSINT +```bash git pull +pip install -e . +``` -Después, actualiza dependencias si cambian: +Si las dependencias cambiaron, vuelve a ejecutar: +```bash 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. +``` + +--- + +## Salir del entorno virtual + +```bash +deactivate +``` + +--- + +## Instalación rápida + +```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 -e . +mexicosint --number 5512345678 +``` + +--- + +## 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` + +```bash +sudo apt install -y python3 +``` + +### `pip: command not found` + +```bash +sudo apt install -y python3-pip +``` + +### Error creando el entorno virtual + +```bash +sudo apt install -y python3-venv +``` + +### El comando `mexicosint` no existe + +Confirma que el entorno virtual está activo y reinstala el paquete: + +```bash +source venv/bin/activate +pip install -e . +``` + +--- + +## Estado + +Si la instalación terminó correctamente, deberías poder ejecutar: + +```bash +mexicosint --number 5512345678 +``` diff --git a/docs/USAGE.md b/docs/USAGE.md index 1bcc175..6137522 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -1,82 +1,171 @@ # 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: +Activa el entorno virtual donde instalaste el paquete: ```bash -cd MeXiCOSINT +source venv/bin/activate +``` -Activa el entorno virtual: +--- -source venv/bin/activate +## Ejecutar MeXiCOSINT + +La forma recomendada es usar el comando instalado: + +```bash +mexicosint --number 5512345678 +``` + +También puedes usar el número como argumento posicional por compatibilidad: + +```bash +mexicosint 5512345678 +``` + +Para ejecutar sin instalar el comando global: + +```bash +PYTHONPATH=src python3 -m mexicosint --number 5512345678 +``` -Ejecuta el script: +--- -python3 mexicosint_v2.2.5.py -Flujo básico +## Formato recomendado del número -La herramienta solicitará un número telefónico mexicano para analizar. +MeXiCOSINT está enfocado en números telefónicos mexicanos. -Formato recomendado: +Formato internacional: +```text +52XXXXXXXXXX +``` -También puedes probar con formato nacional: +Formato nacional de 10 dígitos: +```text XXXXXXXXXX -Resultados +``` + +Ejemplos: + +```bash +mexicosint --number +525512345678 +mexicosint --number 5512345678 +``` + +--- + +## Opciones principales + +```bash +mexicosint --number 5512345678 +mexicosint --ip 8.8.8.8 +mexicosint --dummy-test --number 5512345678 +mexicosint -b --number 5512345678 +mexicosint --version +``` + +`-b`, `--compact-banner` y `--small-banner` fuerzan el banner compacto. + +--- -MeXiCOSINT puede mostrar información como: +## Resultados posibles -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 +Dependiendo de la configuración y API keys disponibles, MeXiCOSINT puede mostrar información como: -Si la herramienta genera reportes, revisa la carpeta del proyecto después de ejecutarla. +* 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 -Ejemplos de posibles archivos generados: +--- + +## APIs y resultados limitados + +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 `docs/CONFIG.md`. + +--- + +## Reportes y archivos generados + +Los reportes generados se escriben dentro de carpetas ignoradas por Git, como: + +```text +output/ +reports/ +results/ +``` + +No publiques reportes con información sensible. + +--- + +## Actualizar antes de usar + +```bash +git pull +pip install -e . +``` + +Si cambiaron las dependencias: -reporte.json -reporte.html -reporte_mapa.html +```bash +pip install -r requirements.txt +``` -Los nombres exactos pueden variar según la versión. +--- -API keys +## Buenas prácticas -Algunas funciones dependen de servicios externos. +* 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. -Si no configuras API keys, la herramienta puede seguir funcionando parcialmente, pero los resultados serán más limitados. +--- -No subas tus API keys a GitHub. +## Solución rápida de problemas -Modo de prueba +### El comando `mexicosint` no funciona -Si la herramienta incluye un modo dummy o de prueba, úsalo solamente para desarrollo local. +Confirma que el entorno virtual está activo y que el paquete fue instalado: -Ejemplo: +```bash +source venv/bin/activate +pip install -e . +``` -python3 mexicosint_v2.2.5.py --dummy-test +### Error de dependencias -Este modo puede cambiar o desaparecer en futuras versiones. +```bash +pip install -r requirements.txt +``` -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 +### API key no detectada -Cuando termines: +```bash +ls -la ~/.mx_osint_config.json +chmod 600 ~/.mx_osint_config.json +``` -deactivate +Revisa `docs/CONFIG.md`. diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..c4a5143 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,31 @@ +[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", + "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:run" + +[tool.setuptools.packages.find] +where = ["src"] + +[tool.setuptools.package-data] +mexicosint = ["data/*"] diff --git a/requirements.txt b/requirements.txt index 6656f26..24bc7b6 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,8 +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 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..e010681 --- /dev/null +++ b/src/mexicosint/__main__.py @@ -0,0 +1,7 @@ +"""Module entry point for `python -m mexicosint`.""" + +from mexicosint.cli import run + + +if __name__ == "__main__": + raise SystemExit(run()) diff --git a/src/mexicosint/cli.py b/src/mexicosint/cli.py new file mode 100644 index 0000000..5ab9b2b --- /dev/null +++ b/src/mexicosint/cli.py @@ -0,0 +1,93 @@ +"""Command-line interface for MeXiCOSINT.""" + +from __future__ import annotations + +import argparse +from typing import List, Optional + +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. Se mantiene por compatibilidad.", + ) + parser.add_argument( + "--number", + dest="phone_number", + metavar="PHONE", + 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 _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]) + else: + number = _scan_number(args) + if number: + argv.append(number) + return argv + + +def run(argv: Optional[List[str]] = None) -> int: + parser = build_parser() + args = parser.parse_args(argv) + + 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_scanner_argv(args)) + return 0 + + +def main(argv: Optional[List[str]] = None) -> int: + """Backward-compatible wrapper for older entry-point references.""" + return run(argv) 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