Rank CLI

CLI oficial de Rank para ejecutar pentests autónomos con agentes de IA. Diseñada como contraparte local de la plataforma cloud: te permite ejecutar el pentest completo directamente en tu máquina, usando el backend de Rank únicamente para autenticar las llamadas a los modelos y registrar las operaciones del pentest. Esto rompe la principal limitación del flujo cloud: poder traer tus propias herramientas sin esperar a que estén disponibles en el servidor.

rank pentest run <id> --local   # el pentest se ejecuta en tu máquina
rank pentest run <id>           # el pentest se ejecuta en el cloud de Rank

Tabla de contenidos

• Requisitos
• Instalación
• Quickstart en 60 segundos
• Conceptos
• Comandos
  • rank auth
  • rank config
  • rank env
  • rank models
  • rank agents
  • rank tools
  • rank mcps
  • rank pentest
  • rank chat
  • rank usage
  • rank doctor
  • rank docs
• Crear tu primera tool local
• TUI: atajos durante un pentest
• Solución de problemas
• Desarrollo

Requisitos

• Node.js >= 20.3
• (Opcional) binarios típicos de pentesting si vas a ejecutar --local: nmap, gobuster, nuclei, whatweb, nikto, dalfox, amass, httprobe, whois, pandoc, etc. Ejecuta rank doctor para detectar cuáles tienes y cuáles te faltan; recibirás el comando de instalación adecuado para tu sistema (Homebrew, apt, go install, pipx).

Instalación

npm install -g rank-cli
rank --version

Quickstart en 60 segundos

rank auth set rk_xxxxxxxxxxxxxxxxxxxx
rank pentest create -n "Demo" -u https://example.com -t web -m automatic
rank pentest run 1

Variante local (el pentest se ejecuta íntegramente en tu máquina; el backend solo se utiliza para autenticar las llamadas a los modelos):

rank pentest create -n "Demo local" -u https://example.com -m guided
rank agents list --type pentest --phase 1
rank pentest assign 2 --agents 12 18 --phase 1
rank doctor --pentest 2
rank pentest run 2 --local

Conceptos

Pentest
  └─ Fases (1..3)
       └─ Agentes (pentest, en orden)
              ├─ Tools     (binarios, scripts, MCPs remotos)
              └─ MCPs
                     └─ Modelo (LLM)

• Pentest: objetivo + assets + modo (automatic o guided) + metodología.
• Fases: el pentest recorre fases en orden. Cada fase ejecuta sus agentes.
• Agentes: pueden ser pentest (asociados a una fase) o general (chat).
• Tools: execution_mode local (creadas por ti, ejecutadas en local), cloud (catálogo oficial) o both (oficial + ejecutable también en local si trae command).
• MCPs: servidores remotos que exponen tools vía Model Context Protocol.
• Modelos: LLMs que razonan en cada agente. Cada modelo debe estar primero asignado a tu cuenta (rank models assign) y luego a un agente (rank agents set-model).

Para una explicación más detallada: rank docs concepts.

Comandos

Toda la documentación está embebida en el binario. Ejecuta rank docs <tema> para ver una guía paginada y formateada en la terminal.

rank auth

Gestiona el token (rk_...) con el que la CLI habla con la API de Rank. El token se guarda en ~/.rank-cli/credentials.

rank auth set <rk_token>
rank auth status
rank auth remove

Más detalles: rank docs auth.

rank config

Configuración persistente de la CLI en ~/.rank-cli/settings.json: URLs de API, modo por defecto, verbose.

rank config show
rank config set phpBaseUrl https://api.aleex-rank.ai/api/v2
rank config set defaultMode local

Más detalles: rank docs config.

rank env

API keys locales de herramientas (Shodan, WPScan, etc.). Se guardan en ~/.rank-cli/env (permisos 600) y se inyectan automáticamente en las tools locales que las declaren en requires_api_key.

rank env set SHODAN_API_KEY=abcdef123
rank env list
rank env unset SHODAN_API_KEY

Más detalles: rank docs env.

rank models

Modelos de IA. Para que un agente use un modelo, el modelo debe estar primero asignado a tu cuenta.

rank models list
rank models mine
rank models assign 12 18
rank models unassign 18

Más detalles: rank docs models.

rank agents

Crear y mantener agentes (pentest o general).

rank agents list
rank agents create
rank agents create -f agent.json
rank agents update 22 --instructions-file new-prompt.md
rank agents set-model 22 12
rank agents clone 22

Carga instructions desde archivo prefijando con @/ruta/al/archivo.md en el wizard. Más detalles: rank docs agents.

rank tools

Tools locales (las tuyas) y consulta de tools cloud asignadas a agentes.

rank tools list 22                    # tools disponibles para el agente #22
rank tools list 22 --assigned         # solo las que ya tiene asignadas
rank tools list 22 --local            # solo ejecutables en local
rank tools show 91
rank tools create                     # wizard interactivo
rank tools create -f tool.json        # archivo único o array
rank tools update 91 --command "..." --timeout 120
rank tools assign 91 22
rank tools example --phase 1 --write tool.json

Ejemplo de definición JSON:

{
  "name": "shodan_search",
  "description": "Search host information on Shodan by IP.",
  "command": "shodan host {ip_address}",
  "execution_mode": "local",
  "requires_api_key": "SHODAN_API_KEY",
  "bootstrap": "shodan init {SHODAN_API_KEY}",
  "parameters": {
    "type": "object",
    "required": ["ip_address"],
    "properties": {
      "ip_address": { "type": "string", "description": "IP a consultar." }
    }
  }
}

rank tools example te materializa los catálogos completos (--phase 1, --phase 2 o all) o una entrada concreta (--name nmap_scan). Úsalo como plantilla. Más detalles: rank docs tools, rank docs tools-create, rank docs tools-assign.

rank mcps

Servidores MCP. Soporta streamable_http y sse, con auth none/bearer/api_key.

rank mcps list
rank mcps create
rank mcps assign 7 22

Más detalles: rank docs mcps.

rank pentest

Ciclo de vida completo de un pentest: crear, asignar agentes, ejecutar (cloud o local), monitorizar y revisar vulnerabilidades.

rank pentest list
rank pentest create -n "ACME" -u https://acme.test -t web -m guided
rank pentest assets 42 add domain:api.acme.test --primary
rank pentest assign 42 --agents 12 18 --phase 1
rank pentest agents 42
rank pentest run 42                   # cloud + TUI
rank pentest run 42 --local           # local + TUI
rank pentest run 42 --no-tui          # salida plana (CI)
rank pentest status 42
rank pentest vulns 42
rank pentest cancel 42

Tipos de asset válidos: domain, url, ip, endpoint. Formato -a tipo:valor; el primero se marca como is_primary. Más detalles: rank docs pentests.

rank chat

Conversación puntual con un agente general. Sin --agent y con TTY abre un selector interactivo.

rank chat -p "Resumen de la última CVE en F5 BIG-IP"
rank chat --agent recon_master -p "Genera subdominios candidatos para acme.test" --local

Más detalles: rank docs chat.

rank usage

Consumo y on-demand.

rank usage summary
rank usage summary --month 2026-05
rank usage daily --period 7d
rank usage daily --date 2026-05-20
rank usage history --page 2
rank usage on-demand enable --limit 50

Más detalles: rank docs usage.

rank doctor

Diagnóstico del entorno local. Sin --pentest valida los binarios del catálogo embebido; con --pentest <id> solo los que invocan las tools asignadas al pentest.

rank doctor
rank doctor --pentest 42
rank doctor --verbose

Más detalles: rank docs doctor.

rank docs

Documentación embebida renderizada como markdown en la terminal.

rank docs                       # índice
rank docs getting-started
rank docs tools-create
rank docs --list                # listar slugs disponibles
rank docs tools --raw           # markdown sin formatear (para pipelines)
RANK_NO_PAGER=1 rank docs tools # forzar salida sin pager

Crear tu primera tool local

rank tools example --phase 1 --write my-tool.json
$EDITOR my-tool.json
rank tools create -f my-tool.json
rank tools assign <toolId> <agentId>
rank pentest assign <pentestId> --agents <agentId> --phase <n>
rank doctor --pentest <pentestId>
rank pentest run <pentestId> --local

rank tools create -f acepta tanto un objeto único como un array, así que puedes registrar varias tools de una sola llamada usando el catálogo de ejemplos como plantilla.

Si tu tool necesita una API key:

rank env set MY_TOOL_API_KEY=...

Declárala en el JSON como requires_api_key. Si la tool necesita un paso de inicialización único (estilo shodan init), añade bootstrap.

TUI: atajos durante un pentest

• En la revisión previa: m para cambiar el modelo de cualquier agente.
• Entre fases locales: el menú incluye "Cambiar modelo de un agente".
• Durante la ejecución: escribe /global para alternar entre el feed de streaming y la vista esquemática global (fases, agentes, modelos, tools, findings).

Para forzar salida plana (CI, contenedores sin TTY): --no-tui en pentest run y chat.

Solución de problemas

• Token caducado o no configurado: rank auth status.
• Tools que fallan en local por binario ausente: rank doctor --pentest <id>.
• API keys faltantes: rank env list y rank env set KEY=VALUE.
• Modo local rechazado: solo está disponible con mode=guided. Crea con rank pentest create --mode guided ....
• Más trazas: RANK_DEBUG=1 rank ... activa logs adicionales en chat local y doctor.
• Desactivar el pager de rank docs: RANK_NO_PAGER=1.

Desarrollo

Este apartado es para contribuidores del repo (no para usuarios del paquete instalado vía npm).

git clone <repo>
cd Rank-CLI
npm install
npm run dev          # tsup --watch
npm run build        # build a dist/
npm run typecheck
npm run lint

Los catálogos de ejemplo viven en src/assets/tools-local.json y src/assets/tools-local-phase2.json y se embeben en el bundle. La documentación en español vive en src/docs/*.md y es consumida por el comando rank docs.

Para publicar:

npm pack --dry-run   # verificar que solo dist/ + README + LICENSE viajen
npm publish