README.es.md

Una herramienta agéntica de pentesting de red con la que hablas.

English  ·  Español  ·  Deutsch  ·  日本語  ·  Türkçe

Esta es una traducción resumida de README.md. La referencia completa de comandos y configuración solo existe en inglés. Si encuentras una discrepancia, el texto en inglés es el que manda.

pwner es un agente dirigido por un LLM que planifica y ejecuta un test de penetración de red desde tu terminal. Descubre hosts, identifica servicios, los comprueba contra problemas conocidos y —cuando el objetivo lo justifica y tú lo apruebas— los explota para demostrar el impacto. Ejecuta herramientas reales (nmap, nuclei, netexec, impacket, hydra y otras) en lugar de simularlas, y reporta hallazgos confirmados con severidad, evidencia y solución.

Funciona con tu propio modelo, o sin modelo alguno.

• Hablas con ella. Sin sopa de flags: dices "escanéalo, céntrate en la base de datos" y decide qué ejecutar, te muestra su razonamiento mientras avanza, y puedes redirigirla a mitad de ejecución.
• El alcance se aplica en código. Cada llamada a una herramienta se verifica contra el objetivo que indicaste antes de ejecutarse, no se le pide al modelo en un prompt.
• Las acciones intrusivas se deniegan por defecto. La fuerza bruta, la ejecución remota de comandos, el volcado de credenciales y las reverse shell requieren tu aprobación explícita.
• Tu modelo, tu máquina. OpenAI, Anthropic, Google, DeepSeek o un servidor en tu propio hardware: Ollama, Lemonade, llama.cpp, cualquier cosa compatible con la API de OpenAI. Un endpoint local no necesita API key. Nada sale de tu máquina hasta que tú lo configures.
• Funciona sin modelo. --no-ai ejecuta todo el pipeline de descubrimiento → identificación → detección de forma determinista, sin API key y sin que nada salga de la máquina.
• Prueba de segmentación PCI DSS. pwner pci comprueba si el CDE está aislado desde un segmento fuera de alcance (11.4.5/11.4.6) y, al ser determinista, repetirlo tras una corrección es el retest que pide 11.4.4. No otorga cumplimiento por sí solo.
• 52 herramientas entre nmap, HTTP, sondas por servicio, Active Directory y trabajo con credenciales, cada una un envoltorio fino sobre el binario estándar, no una reimplementación.

Modelo de seguridad

Dos mecanismos, ambos en la capa de herramientas, ambos fuera del alcance del modelo.

Bloqueo de alcance. build_dispatch envuelve cada herramienta para que todo argumento que lleve un host se verifique contra tu objetivo antes de que se ejecute el cuerpo de la herramienta. Las herramientas están dentro del alcance por defecto: una que olvide su propia comprobación sigue estando protegida, y un nombre de herramienta no registrado falla de forma cerrada. Un argumento de red tiene que caber por completo dentro de la autorización.

Cambiar el alcance es lo único que el guardia no puede comprobar, porque el argumento de set_target es el nuevo alcance: por eso set_target tiene su propia puerta. Reducirlo es libre; moverlo fuera de lo que ya autorizaste requiere tu respuesta cada vez, y --auto-consent no lo cubre.

Puerta de consentimiento. Todo lo activo se deniega salvo que lo apruebes en esa sesión. El consentimiento se resuelve fuera del modelo —el agente no puede aprobarse a sí mismo— y una ejecución no interactiva lo deniega salvo que la hayas lanzado con --auto-consent.

Una denegación no es un error que detenga la ejecución: vuelve al modelo como resultado de la herramienta, así que el agente aprende que se excedió y continúa dentro del límite.

Esta es la parte del código con más pruebas: 77 pruebas sobre el límite de alcance en tests/test_scope.py y 13 sobre la puerta de consentimiento en tests/test_consent.py, de 785 en total. Si vas a leer una sola cosa antes de apuntar esto a una red, lee esas.

Uso previsto:

• Tests de penetración autorizados, con permiso por escrito y un alcance acordado
• Trabajo de bug bounty, dentro de las reglas declaradas del programa
• Tu propio laboratorio, tu propio hardware, CTFs
• Investigación de seguridad sobre sistemas de tu propiedad

Lo que no es el propósito de esta herramienta, y no es defendible:

• Cualquier cosa sobre un host que no sea tuyo y para el que no tengas permiso escrito
• "Solo echar un vistazo" a una red en la que te encuentras
• Cualquier cosa en la que no puedas decir quién la autorizó

Instalación

Python 3.10+. nmap es el único requisito obligatorio; todo lo demás habilita más herramientas y es opcional.

curl -fsSL https://raw.githubusercontent.com/0x45dd/pwner/main/install.sh | bash

Eso construye un virtualenv aislado en ~/.local/share/pwner, deja en paz el Python del sistema y pone pwner en tu PATH para que funcione desde cualquier directorio. Añade --with-tools para instalar también nmap y los escáneres opcionales, y --uninstall para quitarlo todo.

También está en PyPI, si prefieres usar tus propias herramientas de Python:

pipx install pwner      # aislado, y `pwner` queda en tu PATH
uv tool install pwner   # lo mismo, con uv
pip install pwner       # dentro de un virtualenv

Usa pipx o uv tool antes que un pip install a secas: te dan el mismo aislamiento que el script de instalación, y de todos modos instalar en el Python del sistema está vetado en la mayoría de las distribuciones actuales.

En macOS también hay un tap:

brew install 0x45dd/tap/pwner

Eso trae nmap consigo. Desde el código fuente:

git clone https://github.com/0x45dd/pwner.git
cd pwner
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
./scripts/install-deps.sh   # brew/apt/kali/pacman/dnf
pwner doctor                # qué falta

En Kali no hay casi nada que instalar. Una imagen de Kali por defecto ya trae 8 de las 11 herramientas externas que pwner usa. sudo apt install nuclei bloodhound.py añade dos más, y la única sin empaquetar es kerbrute. pwner detecta Kali como su propio ecosistema en lugar de como Debian, así que pwner doctor te da comandos de apt en vez de las compilaciones desde fuente que necesita un Debian normal. Si estás eligiendo dónde ejecutar esto, ejecútalo ahí.

Primera ejecución

pwner

La primera ejecución pide un proveedor y una API key una sola vez, y los guarda en ~/.config/pwner/config.json (solo lectura para el propietario). Cada ejecución posterior te deja directamente en una sesión. Cámbialo después con pwner --pick (menú de proveedor/modelo), con pwner setup (todas las preguntas) o con /model y /provider dentro de una sesión en marcha.

pwner chat 10.0.0.5          # sesión, objetivo fijado
pwner 10.0.0.0/24 --no-ai    # barrido, sin modelo
pwner doctor                 # estado de las herramientas

Dentro de una sesión hablas con el agente y lo guías mientras trabaja: /help lista los comandos, /findings y /topology muestran lo que ha construido hasta ahora, y /dump escribe la transcripción en ~/.local/share/pwner/sessions/ (solo para el propietario: contiene en texto claro todas las credenciales que haya encontrado el trabajo).

Tu modelo

Apúntalo a un proveedor y dale una key. Los presets cubren OpenAI, Anthropic, Google y DeepSeek; cualquier otra cosa que hable la API de OpenAI funciona con --base-url.

export PWNER_API_KEY=...
pwner chat 10.0.0.5 --provider anthropic

El modelo tiene que soportar tool calling. pwner chat --help lista los presets y todas las opciones de sobrescritura.

En tu propio hardware

ollama y lemonade también son presets, y un endpoint local no necesita API key: si se le da una, se envía igualmente, ya que Lemonade separa las keys de inferencia de las de administración.

pwner chat 10.0.0.5 --provider ollama
pwner chat 10.0.0.5 --provider lemonade

Los servidores locales se nombran según lo que esa máquina haya descargado, así que no hay un modelo por defecto razonable. Cuando no se fija ninguno, pwner consulta el endpoint /models del servidor y usa lo que encuentra; pwner setup los lista y te deja elegir uno para guardarlo. Cualquier otro servidor compatible con OpenAI —llama.cpp, LM Studio, vLLM— funciona igual con --base-url, y se trata como sin key siempre que la URL apunte a loopback o a una red privada.

pwner chat 10.0.0.5 --base-url http://192.168.1.50:13305/api/v1 --model Qwen3-Coder-30B

Ejecutar sin modelo

--no-ai ejecuta la suite determinista: descubrimiento de hosts, escaneo de puertos, detección de servicios, identificación del SO y detección de problemas conocidos, y después el mismo informe de hallazgos. Sin API key, sin llamadas de red más allá del propio escaneo, y reproducible, lo que lo convierte en el modo a usar en CI, en un trabajo air-gapped o cuando los datos no pueden salir del edificio.

Las herramientas activas son las del agente: necesitan tanto un modelo como tu consentimiento.

Documentación

La referencia completa de comandos y configuración, el bucle del agente, el catálogo de módulos y las reglas están en pwner.si, solo en inglés:

• Docs — instalación, primera sesión, cada comando y flag
• Agent — cómo funciona el bucle y qué puede y no puede hacer
• Modules — las 52 herramientas y qué usa cada una
• Rules — alcance, consentimiento, uso responsable
• Contributing — entorno de desarrollo, el paquete tools, añadir una herramienta
• Security — reportar una vulnerabilidad en pwner mismo

Contacto

Para cualquier cosa que no encaje en un issue público —preguntas, comentarios privados o simplemente ponerse en contacto directamente— escribe a berk@planckproof.ai.

Los bugs y las peticiones de funcionalidad funcionan mejor como issues, y las vulnerabilidades de seguridad deberían ir por SECURITY.md para que sigan siendo privadas hasta que haya una corrección.

Licencia

GNU AGPL-3.0-or-later. Copyright (C) 2026 Berk D.

Copyleft fuerte, con cláusula de red: si modificas pwner y dejas que otras personas lo usen a través de una red, también les debes el código fuente modificado.

Warning

Solo uso autorizado. pwner envía tráfico real a los hosts que indiques y, con tu aprobación, entra activamente en ellos. Ejecútalo únicamente contra sistemas de tu propiedad o para los que tengas permiso explícito y por escrito, y mantente dentro del alcance acordado. El testing no autorizado es ilegal en la mayoría de las jurisdicciones. Obtener esa autorización es tu responsabilidad, no la de la herramienta. pwner se proporciona tal cual, sin garantía y sin responsabilidad por mal uso. El bloqueo de alcance y la puerta de consentimiento son ingeniería, no una defensa legal.