# 🛡️ Penlab
**Penlab** es una herramienta de línea de comandos desarrollada en **Python** para gestionar y documentar proyectos de **pentesting** de forma organizada, rápida y personalizable.
Automatiza la creación de estructuras de directorios, archivos, notas y configuraciones específicas para cada tipo de proyecto, utilizando **templates YAML** completamente adaptables.
---
## 🚀 Características principales
- ⚙️ **Automatización completa** de la estructura inicial de un proyecto de pentesting.
- 🧩 **Templates YAML personalizables**, que definen directorios, archivos, contenido predefinido y variables dinámicas.
- 🗂️ **Gestión visual y ordenada** en consola mediante la librería [`Rich`](https://github.com/Textualize/rich).
- 🧠 **Enfoque en la documentación**: fomenta mantener registros claros y estructurados de cada evaluación.
- 🔄 **Configuración persistente**, que guarda tus preferencias y rutas de trabajo.
- 🐍 **CLI simple y modular**, desarrollada con [`Click`](https://click.palletsprojects.com/).
---
## 🔽 Instalación
> Requisitos previos:
> - Python 3.9 o superior
> - pip instalado
> - Git (opcional, si clonas el repositorio)
### Opción 1 — Instalar desde PyPI (recomendada)
```bash
pip install penlab
```
### Opción 2 — Instalar localmente
```bash
git clone https://github.com/h3lls1nk1/penlab.git
cd penlab
pip install -r requirements.txt
pip install .
```
## 🧩 Cómo funcionan las Templates en Penlab
Las **templates** son el corazón de Penlab.
Definen **cómo se crea la estructura de un proyecto de pentesting**: carpetas, archivos, contenido y variables dinámicas.
Cada template está escrita en **YAML**, lo que la hace fácil de leer, editar y compartir.
Cuando ejecutas un comando como:
```bash
penlab init htb-Blue --template htb --target 10.10.10.40
```
Penlab busca el archivo htb.yaml (dentro de tu carpeta de plantillas), lo interpreta, sustituye las variables ({{target}}, {{project_name}}, etc.) y genera automáticamente todo el árbol de directorios con sus archivos.
## 📄 Estructura básica de una template
Una template YAML se divide en metadatos y una estructura (structure) que define carpetas y archivos.
```bash
# htb.yaml
name: htb
version: 1.0
author: Penlab
description: >
Template optimizada para maquinas de tipo Hack The Box (HTB).
tags:
- htb
- ctf
- pentest
- web
- network
# Variables que pueden usarse en nombres y contenidos ({project-name}, {target}, etc.)
variables:
project-name: "Nombre del proyecto (usado en archivos y rutas)"
target: "IP o hostname del objetivo (ej: 10.10.10.10)"
your-ip: "Tu IP atacante / VPN (ej: 10.10.14.2)"
date: "Fecha de creación (se sustituye automáticamente)"
author: "Autor del proyecto"
# Estructura del proyecto (dirs, subdirs y archivos)
structure:
- dir: reconnaissance
files:
- name: README.md
content: |
# Recon - {project-name}
**Target:** {target}
**Fecha:** {date}
**Autor:** {author}
## Notas de recon
- Puertos abiertos:
- Servicios detectados:
- Observaciones iniciales:
- name: notes.md
content: |
# Notes - {project-name}
- Objetivo: {target}
- Estado inicial: pendiente
subdirs:
- dir: scans
files:
- name: "{target}_nmap_initial.txt"
content: |
# Nmap inicial - {target}
# Ejecutado: {date}
# Escaneo por defecto (tcp)
- name: "{target}_nmap_full.xml"
content: ""
- dir: enum
files:
- name: web_enum.md
content: |
# Web enumeration
- fuzzer:
- endpoints:
- dir: exploitation
files:
- name: payloads
content: ""
- name: notes_exploit.md
content: |
# Exploit notes - {project-name}
- Vector:
- POC:
subdirs:
- dir: scripts
files:
- name: scan_http.sh
content: |
#!/usr/bin/env bash
# Scan básico HTTP para {target}
echo "Escaneando {target}..."
nmap -sV -p- --min-rate 1000 {target} -oA scans/{target}_http
executable: true
- dir: post-exploitation
files:
- name: priv-esc.md
content: |
# Privilege Escalation - {project-name}
- Técnicas probadas:
- Resultado:
- name: persistence.md
content: |
# Persistence notes
- dir: reports
files:
- name: README.md
content: |
# Reportes - {project-name}
Genera aquí resúmenes y entregables.
- name: draft_report.md
content: |
# Borrador de informe - {project-name}
## Resumen ejecutivo
## Hallazgos
- dir: tools
files:
- name: README.md
content: |
# Tools
Guarda scripts y herramientas útiles aquí.
- dir: misc
files:
- name: journal.md
content: |
# Diario de pentesting - {project-name}
Fecha | Acción | Resultado
# Archivos globales que se copian al root del proyecto
global_files:
- name: README.md
content: |
# {project-name}
Proyecto HTB generado con Penlab.
- Target: {target}
- Autor: {author}
- Fecha: {date}
- name: .gitignore
content: |
# Node / Python / general
__pycache__/
*.pyc
*.log
scans/
*.xml
*.nmap
.env
- name: LICENSE
content: |
MIT License
Copyright (c) {author}
- name: notes.md
content: |
# Central notes
Usa este archivo para apuntes rápidos.
# Fin del template
```
Raw data
{
"_id": null,
"home_page": "https://github.com/h3lls1nk1/penlab",
"name": "penlab",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "pentesting cli cybersecurity automation yaml templates",
"author": "h3lls1nk1",
"author_email": "h3lls1nk1@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1a/04/b111a62b76268b9ff1d8c9e1d6c4d519a2b9044115329cea6ffcfb8da50d/penlab-1.0.0.tar.gz",
"platform": null,
"description": "# \ud83d\udee1\ufe0f Penlab\r\n\r\n**Penlab** es una herramienta de l\u00ednea de comandos desarrollada en **Python** para gestionar y documentar proyectos de **pentesting** de forma organizada, r\u00e1pida y personalizable.\r\n\r\nAutomatiza la creaci\u00f3n de estructuras de directorios, archivos, notas y configuraciones espec\u00edficas para cada tipo de proyecto, utilizando **templates YAML** completamente adaptables.\r\n\r\n---\r\n\r\n## \ud83d\ude80 Caracter\u00edsticas principales\r\n\r\n- \u2699\ufe0f **Automatizaci\u00f3n completa** de la estructura inicial de un proyecto de pentesting.\r\n- \ud83e\udde9 **Templates YAML personalizables**, que definen directorios, archivos, contenido predefinido y variables din\u00e1micas.\r\n- \ud83d\uddc2\ufe0f **Gesti\u00f3n visual y ordenada** en consola mediante la librer\u00eda [`Rich`](https://github.com/Textualize/rich).\r\n- \ud83e\udde0 **Enfoque en la documentaci\u00f3n**: fomenta mantener registros claros y estructurados de cada evaluaci\u00f3n.\r\n- \ud83d\udd04 **Configuraci\u00f3n persistente**, que guarda tus preferencias y rutas de trabajo.\r\n- \ud83d\udc0d **CLI simple y modular**, desarrollada con [`Click`](https://click.palletsprojects.com/).\r\n\r\n---\r\n\r\n## \ud83d\udd3d Instalaci\u00f3n\r\n\r\n> Requisitos previos:\r\n> - Python 3.9 o superior \r\n> - pip instalado \r\n> - Git (opcional, si clonas el repositorio)\r\n\r\n\r\n### Opci\u00f3n 1 \u2014 Instalar desde PyPI (recomendada)\r\n\r\n```bash\r\npip install penlab\r\n```\r\n\r\n### Opci\u00f3n 2 \u2014 Instalar localmente\r\n\r\n```bash\r\ngit clone https://github.com/h3lls1nk1/penlab.git\r\ncd penlab\r\npip install -r requirements.txt\r\npip install .\r\n```\r\n\r\n## \ud83e\udde9 C\u00f3mo funcionan las Templates en Penlab\r\n\r\nLas **templates** son el coraz\u00f3n de Penlab. \r\nDefinen **c\u00f3mo se crea la estructura de un proyecto de pentesting**: carpetas, archivos, contenido y variables din\u00e1micas.\r\n\r\nCada template est\u00e1 escrita en **YAML**, lo que la hace f\u00e1cil de leer, editar y compartir. \r\nCuando ejecutas un comando como:\r\n\r\n```bash\r\npenlab init htb-Blue --template htb --target 10.10.10.40\r\n```\r\n\r\nPenlab busca el archivo htb.yaml (dentro de tu carpeta de plantillas), lo interpreta, sustituye las variables ({{target}}, {{project_name}}, etc.) y genera autom\u00e1ticamente todo el \u00e1rbol de directorios con sus archivos.\r\n\r\n## \ud83d\udcc4 Estructura b\u00e1sica de una template\r\n\r\nUna template YAML se divide en metadatos y una estructura (structure) que define carpetas y archivos.\r\n\r\n```bash\r\n# htb.yaml\r\nname: htb\r\nversion: 1.0\r\nauthor: Penlab\r\ndescription: >\r\n Template optimizada para maquinas de tipo Hack The Box (HTB).\r\ntags:\r\n - htb\r\n - ctf\r\n - pentest\r\n - web\r\n - network\r\n\r\n# Variables que pueden usarse en nombres y contenidos ({project-name}, {target}, etc.)\r\nvariables:\r\n project-name: \"Nombre del proyecto (usado en archivos y rutas)\"\r\n target: \"IP o hostname del objetivo (ej: 10.10.10.10)\"\r\n your-ip: \"Tu IP atacante / VPN (ej: 10.10.14.2)\"\r\n date: \"Fecha de creaci\u00f3n (se sustituye autom\u00e1ticamente)\"\r\n author: \"Autor del proyecto\"\r\n\r\n# Estructura del proyecto (dirs, subdirs y archivos)\r\nstructure:\r\n - dir: reconnaissance\r\n files:\r\n - name: README.md\r\n content: |\r\n # Recon - {project-name}\r\n **Target:** {target}\r\n **Fecha:** {date}\r\n **Autor:** {author}\r\n\r\n ## Notas de recon\r\n - Puertos abiertos:\r\n - Servicios detectados:\r\n - Observaciones iniciales:\r\n - name: notes.md\r\n content: |\r\n # Notes - {project-name}\r\n - Objetivo: {target}\r\n - Estado inicial: pendiente\r\n subdirs:\r\n - dir: scans\r\n files:\r\n - name: \"{target}_nmap_initial.txt\"\r\n content: |\r\n # Nmap inicial - {target}\r\n # Ejecutado: {date}\r\n # Escaneo por defecto (tcp)\r\n - name: \"{target}_nmap_full.xml\"\r\n content: \"\"\r\n - dir: enum\r\n files:\r\n - name: web_enum.md\r\n content: |\r\n # Web enumeration\r\n - fuzzer:\r\n - endpoints:\r\n - dir: exploitation\r\n files:\r\n - name: payloads\r\n content: \"\"\r\n - name: notes_exploit.md\r\n content: |\r\n # Exploit notes - {project-name}\r\n - Vector:\r\n - POC:\r\n subdirs:\r\n - dir: scripts\r\n files:\r\n - name: scan_http.sh\r\n content: |\r\n #!/usr/bin/env bash\r\n # Scan b\u00e1sico HTTP para {target}\r\n echo \"Escaneando {target}...\"\r\n nmap -sV -p- --min-rate 1000 {target} -oA scans/{target}_http\r\n executable: true\r\n - dir: post-exploitation\r\n files:\r\n - name: priv-esc.md\r\n content: |\r\n # Privilege Escalation - {project-name}\r\n - T\u00e9cnicas probadas:\r\n - Resultado:\r\n - name: persistence.md\r\n content: |\r\n # Persistence notes\r\n - dir: reports\r\n files:\r\n - name: README.md\r\n content: |\r\n # Reportes - {project-name}\r\n Genera aqu\u00ed res\u00famenes y entregables.\r\n - name: draft_report.md\r\n content: |\r\n # Borrador de informe - {project-name}\r\n ## Resumen ejecutivo\r\n ## Hallazgos\r\n - dir: tools\r\n files:\r\n - name: README.md\r\n content: |\r\n # Tools\r\n Guarda scripts y herramientas \u00fatiles aqu\u00ed.\r\n - dir: misc\r\n files:\r\n - name: journal.md\r\n content: |\r\n # Diario de pentesting - {project-name}\r\n Fecha | Acci\u00f3n | Resultado\r\n\r\n# Archivos globales que se copian al root del proyecto\r\nglobal_files:\r\n - name: README.md\r\n content: |\r\n # {project-name}\r\n Proyecto HTB generado con Penlab.\r\n - Target: {target}\r\n - Autor: {author}\r\n - Fecha: {date}\r\n\r\n - name: .gitignore\r\n content: |\r\n # Node / Python / general\r\n __pycache__/\r\n *.pyc\r\n *.log\r\n scans/\r\n *.xml\r\n *.nmap\r\n .env\r\n\r\n - name: LICENSE\r\n content: |\r\n MIT License\r\n Copyright (c) {author}\r\n\r\n - name: notes.md\r\n content: |\r\n # Central notes\r\n Usa este archivo para apuntes r\u00e1pidos.\r\n\r\n# Fin del template\r\n\r\n```\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CLI tool para gesti\u00f3n de proyectos de pentesting y ciberseguridad",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/h3lls1nk1/penlab"
},
"split_keywords": [
"pentesting",
"cli",
"cybersecurity",
"automation",
"yaml",
"templates"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a798b1c3554ad02d51bc3b18dc6fb88ca3f47a5c740427d0c51ffaf54a2a90a7",
"md5": "a1a1d8c4f6c9f3f751a5d79446d38754",
"sha256": "84f44a37e1a3b80207f3c898577ad28228b8426b271316a05c63429a9061f090"
},
"downloads": -1,
"filename": "penlab-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a1a1d8c4f6c9f3f751a5d79446d38754",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 39790,
"upload_time": "2025-11-02T11:18:44",
"upload_time_iso_8601": "2025-11-02T11:18:44.201910Z",
"url": "https://files.pythonhosted.org/packages/a7/98/b1c3554ad02d51bc3b18dc6fb88ca3f47a5c740427d0c51ffaf54a2a90a7/penlab-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1a04b111a62b76268b9ff1d8c9e1d6c4d519a2b9044115329cea6ffcfb8da50d",
"md5": "d061ba7e7bf1357ef6573ee54fe779f0",
"sha256": "c01592966895b741e7642e4bd3e12bac51e825133de98f435c6c94c6c331eb00"
},
"downloads": -1,
"filename": "penlab-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "d061ba7e7bf1357ef6573ee54fe779f0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 35929,
"upload_time": "2025-11-02T11:18:45",
"upload_time_iso_8601": "2025-11-02T11:18:45.548998Z",
"url": "https://files.pythonhosted.org/packages/1a/04/b111a62b76268b9ff1d8c9e1d6c4d519a2b9044115329cea6ffcfb8da50d/penlab-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-02 11:18:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "h3lls1nk1",
"github_project": "penlab",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
},
{
"name": "PyYAML",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "jinja2",
"specs": [
[
">=",
"3.0.0"
]
]
}
],
"lcname": "penlab"
}
JSON
