Pentesting Framework

Framework modular de pentesting para auditorías de seguridad en entornos controlados.

---

Indice

1. Descripcion general
2. Caracteristicas
3. Requisitos
4. Instalacion
5. Estructura del proyecto
6. Comandos
7. Navegacion
8. Atlas - Asistente de IA
9. Configuracion
10. Sistema de prompts
11. Spotlight
12. Compatibilidad y dependencias
13. Instalador de dependencias
14. EULA y disclaimer
15. Autor
16. Aviso legal

---

Descripcion general

Este framework es una plataforma CLI modular orientada a auditorías de seguridad ofensiva. Permite navegar por un arbol de categorías y herramientas, ejecutar módulos de pentesting, consultar un asistente de IA llamado Atlas para obtener sugerencias, y personalizar completamente la experiencia del terminal.

Lo desarrolle como parte de mi TDR (Treball de Recerca) de instituto. Atlas, la entidad de inteligencia artificial integrada, forma parte del mismo proyecto de investigacion.

Inicio del framework con prompt Kali Classic

---

Caracteristicas

• Navegacion modular: Explora categorías y herramientas con comandos cd y run, como un sistema de archivos.
• Asistente de IA (Atlas): Consulta en lenguaje natural para obtener sugerencias de herramientas, categorías o respuestas técnicas.
• Sistema de prompts: 20 estilos de prompt distintos + 10 esquemas de color para el prompt Kali Classic.
• Spotlight (Ctrl+Espacio): Busqueda rápida y filtrado de herramientas/categorías en tiempo real.
• Autocompletado: Tres modos — desactivado, minimal (estilo bash) y completo (dropdown con descripciones).
• Configuracion interactiva: Menu en ncurses para ajustar preferencias, interfaz monitor, IA, dependencias y sistema.
• Instalador de dependencias: Detecta automaticamente herramientas faltantes y las instala via apt-get.
• Compatibilidad declarativa: Cada herramienta tiene un manifiesto JSON que especifica OS compatibles, requisito de root y dependencias.
• Historial de comandos: Persistente entre sesiones.
• Resaltado de comandos: Colorea comandos reconocidos (run, cd, clear, etc.) en azul y negrita.
• EULA interactivo: Aceptacion del disclaimer con opción de guardar permanentemente.

---

Requisitos

• Python 3.10+
• Kali Linux (recomendado; también compatible con otras distribuciones Linux)
• Root para ejecutar herramientas de pentesting
• Dependencias de Python:
  • colorama
  • prompt_toolkit (opcional, para autocompletado avanzado)
• Dependencias del sistema (por herramienta):
  • arp-scan, dsniff (arpspoof), tcpdump
  • mdk4, aircrack-ng (airmon-ng, airodump-ng)

---

Instalacion

# Clonar el repositorio
git clone https://github.com/samilososami/framework.git
cd framework

# Instalar dependencias de Python
pip install colorama prompt_toolkit

# Ejecutar (requiere root para herramientas de pentesting)
sudo python3 framework.py

---

Estructura del proyecto

framework/
  framework.py                # Framework principal (REPL, navegación, comandos)
  config.py                   # Configuracion interactiva (ncurses), instalador de dependencias
  eula.py                     # EULA / disclaimer
  prompts.py                  # 20 estilos de prompt
  prompt_colors.py            # 10 esquemas de color para prompt Kali Classic
  oui.py                      # Base de datos OUI (33.000+ vendors MAC)
  README.md                   # Este documento
  .gitignore                  # Archivos excluidos de git
  config/                     # Configuracion persistente (no versionada)
    config.json               # Preferencias del usuario
    eula.txt                  # Estado de aceptación del EULA
    prompt_config.txt         # Seleccion de estilo de prompt
    prompt_colors.txt         # Esquema de color actual
    prompt_selections.txt     # Selecciones multiples de prompt
    cmd_history.txt           # Historial de comandos
  modules/
    ai.py                     # Asistente Atlas (Ollama Cloud API)
    pentesting/
      red/                    # Herramientas de red
        dos/                  # Denegacion de servicio
          internetblocker.py
          internetblocker.json
        exploit/              # Explotacion (pendiente)
        mitm/                 # Man in the middle (pendiente)
        scan/                 # Escaneo de red (pendiente)
        sniff/                # Captura de tráfico (pendiente)
      wifi/                   # Herramientas inalambricas
        deauth/               # Desautenticacion WiFi
          deauther.py
          deauther.json
      web/                    # Pentesting web (pendiente)
      ad/                     # Active Directory (pendiente)
  docs/
    screenshots/              # Capturas de pantalla para documentación

---

Comandos

Comando	Descripcion	Ejemplo
cd <ruta>	Navegar por el arbol de categorías	cd pentesting/red/dos
run <herramienta>	Ejecutar una herramienta	run internetblocker
run <herramienta> <args>	Ejecutar con argumentos	run internetblocker -ip 192.168.1.10
ls	Listar contenido del nodo actual	ls
help	Ayuda general	help
help <comando>	Ayuda de un comando	help run
help <herramienta>	Ayuda de una herramienta	help internetblocker
ai <prompt>	Consultar a Atlas (IA)	ai escanear puertos
config	Abrir menu de configuración	config
set-style	Cambiar estilo de prompt	set-style
set-prompt	Cambiar colores del prompt	set-prompt
clear	Limpiar la terminal	clear
x <comando>	Ejecutar comando del sistema	x whoami
exit / salir / Ctrl+C x2	Salir del framework	exit

Navegacion de rutas:

• Rutas absolutas: cd /pentesting/red/dos
• Rutas relativas: cd dos (desde /pentesting/red)
• Subir nivel: cd ..
• Raiz: cd (sin argumentos)

Salida del comando `help`

Salida del comando `ls` en el directorio raiz

---

Atlas - Asistente de IA

Atlas es la entidad de inteligencia artificial integrada en el framework, desarrollada como parte de mi TDR.

Uso

ai <consulta en lenguaje natural>

Ejemplos:

ai qué herramienta usar para bloquear internet a una ip
ai cómo escaneo puertos en una red
ai quién eres

Tipos de respuesta

Atlas responde en formato JSON y el framework interpreta tres tipos:

• Herramienta: sugiere run <nombre> y navega automaticamente a la categoría
• Categoria: sugiere cd <ruta> para explorar un area
• Chat: responde a preguntas generales de pentesting/seguridad

Ejemplo de consulta a Atlas sugiriendo una herramienta

Niveles de comentarios

Ajustable desde config > Inteligencia Artificial > Comentarios IA:

Nivel	Descripcion
Off	Solo muestra el comando (run / cd)
Minimos	Muestra la razon de la sugerencia + comando
Detallados	Muestra razon + ruta completa + comando

Configuracion de Atlas

1. Ve a config > Modelo IA > selecciona Cloud
2. Introduce tu API key de ollama.com
3. Ajusta el nivel de comentarios segun prefieras

Modelo utilizado: minimax-m2.7:cloud (via Ollama Cloud API)

---

Configuracion

El menu de configuración (config) permite ajustar todos los parámetros del framework mediante una interfaz ncurses.

Menu de configuración interactiva

Secciones

PREFERENCIAS

• Autocompletado: Off / Minimo / Full
  • Off: sin completado
  • Minimo: completado estilo bash (lista debajo, sin dropdown)
  • Full: completado con dropdown y descripciones
• Resaltado de comandos: Off / On — colorea run, cd, clear, etc. en azul

WIFI

• Interfaz monitor: selección de interfaz de red desde /sys/class/net/. Presiona Enter para abrir un panel vertical con todas las interfaces disponibles.

INTELIGENCIA ARTIFICIAL

• Modelo IA: Off / Cloud — presiona Enter para configurar la API key
• Comentarios IA: Off / Minimos / Detallados — controla la cantidad de explicacion que Atlas muestra

HERRAMIENTAS

• Instalar dependencias: abre el instalador con arbol de categorías. Muestra estado de cada dependencia (instaladas / totales) y permite instalar por categoría o todas.

SISTEMA Y COMPATIBILIDAD

• Ver sistema y compatibilidad: muestra información del sistema (OS, kernel, CPU, RAM, Python, root) y tabla de compatibilidad de herramientas (Compatible / Incompatible) con motivo.

Controles del menu

• Flechas / WASD: navegar entre opciones
• Izquierda / Derecha / AD: cambiar valor de opciones ciclicas
• Espacio: ciclar valor
• Enter: entrar en sub-pantallas (IA, interfaz, dependencias, sistema)
• Esc x2: guardar cambios (animacion de circulos de confirmacion)
• Ctrl+C x2: salir sin guardar

---

Sistema de prompts

El framework incluye 20 estilos de prompt distintos, accessibles via set-style.

Estilos disponibles

#	Nombre	Imagen
1	Kali Classic
2	Operator
3	Bash
4	Metasploit
5	Red Ops
6	Tactical
7	Ghost
8	Stealth
9	Netinfo
10	Root Access
11	Professional
12	Hacker
13	System
14	Bracket Stack
15	Compact
16	Simple
17	Status
18	Operations
19	Dual
20	Framework

Esquemas de color (sólo Kali Classic)

Via set-prompt:

#	Nombre
1	Kali Root
2	Cyberpunk
3	Red Team
4	Phantom
5	Militar
6	Neon
7	Sombra
8	Medusa
9	Cobalto
10	Monocromo

---

Spotlight

Busqueda rápida de herramientas y categorías con Ctrl+Espacio.

Controles

• Escribir: filtra resultados en tiempo real
• Flechas arriba/abajo / Tab: navegar entre resultados
• Enter: navegar a la categoría o pre-ejecutar la herramienta
• Alt+Enter: ejecutar directamente (bypass de confirmacion)
• Esc: cerrar spotlight

Caracteristicas

• Sobreescritura de pantalla alternativa (preserva el contenido anterior)
• Sugerencia automatica en color tenue despues del cursor
• Modo modifyOtherKeys para detectar combinaciones extendidas

---

Compatibilidad y dependencias

Cada herramienta incluye un manifiesto JSON declarativo junto a su módulo .py:

{
  "name": "internetblocker",
  "desc": "Bloquea el acceso a internet de uno o más objetivos",
  "compat": ["Linux"],
  "root": true,
  "tools": [
    {"check": "arp-scan", "package": "arp-scan"},
    {"check": "arpspoof", "package": "dsniff"},
    {"check": "tcpdump", "package": "tcpdump"}
  ]
}

Campos del manifiesto

Campo	Descripcion
name	Nombre exacto de la herramienta
desc	Descripcion corta en espanol
compat	Sistemas operativos compatibles (Linux, Windows, macOS)
root	true sí requiere privilegios de root
tools	Lista de dependencias: {check: "binario", package: "apt-package"}

La pantalla Sistema y compatibilidad verifica automaticamente:

• Compatibilidad de OS
• Requisito de root
• Disponibilidad de cada dependencia via which

---

Instalador de dependencias

Desde config > Instalar dependencias.

Funcionamiento

1. Selecciona una categoría o [ALL] para instalar todo
2. El instalador estima el tamano de descarga via apt-cache show
3. Confirma con Si/No
4. Ejecuta apt-get install -y para cada paquete faltante
5. Muestra progreso en tiempo real con contador de herramientas instaladas
6. Ctrl+C x2 cancela la instalación

Requisitos

• Debes ejecutar el framework como root para instalar dependencias

---

EULA y disclaimer

Al primer inicio, el framework muestra un EULA interactivo en ncurses:

Este framework esta diseñado EXCLUSIVAMENTE para auditorías de seguridad autorizadas y fines educativos.

Debes tener autorización explicita por escrito antes de usar esta herramienta en cualquier sistema o red.

Sami NO asume responsabilidad alguna por uso indebido o actividad no autorizada. El usuario es el único responsable de garantizar el cumplimiento de las leyes aplicables.

Opciones

• Aceptar: continua al framework
• Aceptar permanentemente (P o Shift+Enter): guarda aceptación en config/eula.txt, no vuelve a mostrar
• Denegar: el framework se cierra

---

Autor

Sami Gonzalez Kamel — @samilososami

Lo desarrolle como parte de mi TDR (Treball de Recerca) de instituto.

• Portfolio: samilososami.com
• GitHub: github.com/samilososami
• Instagram: @samilososami
• YouTube: @samilososami
• TikTok: @samilososam1

Donaciones

Si te resulta util el proyecto, puedes apoyar el desarrollo:

• PayPal: paypal.me/samilososami
• Bitcoin: bc1qa8r8ll0m0e58f3ngrauh08nnzdn0alm825nc3r

---

Aviso legal

Este framework es exclusivamente para uso educativo y auditorías de seguridad autorizadas.

El usuario es el único responsable de garantizar el cumplimiento de las leyes aplicables. No asumo responsabilidad alguna por uso indebido o actividad no autorizada.

NO utilices este framework en sistemas o redes sin autorización explicita por escrito.