Instrucciones de Kali Factory

Plano de control local al host más seguro para agentes de IA que necesitan acceso a herramientas de OSINT de Kali Linux.

Este paquete refleja la forma de GPU Factory: envío de trabajos tipados con autenticación bearer, ejecución de trabajadores en cola, ejecución de imágenes Docker con lista de permitidos, pero aplicado a un problema diferente: distribuir el acceso a las herramientas de reconocimiento y análisis de tráfico de Kali sin dar a los agentes un shell sin autenticar.

• API de control FastAPI

• Cola Redis

• Trabajador RQ

• Ejecución de contenedores centrada en Docker contra una imagen de Kali endurecida

• Trabajos tipados (osint, captura de tráfico, análisis JS, búsqueda de fugas) en lugar de shell sin procesar

• Autenticación con token bearer

• Servidor MCP local para agentes compatibles con MCP

• Sidecar opcional de ChromaDB para retener los hallazgos de reconocimiento entre ejecuciones

Por qué existe esto

Kali incluye cientos de herramientas, muchas de las cuales son útiles para la inteligencia competitiva legítima y la investigación de seguridad, y algunas de las cuales no son apropiadas para la automatización impulsada por agentes. El enfoque ingenuo (soltar un agente en un shell de Kali y dejar que resuelva las cosas) produce tres problemas:

1. El agente tiene acceso a todas las herramientas, incluidos los marcos de explotación (metasploit, sqlmap, hashcat, john, aircrack-ng, exploitdb) que nunca deberían ser accesibles desde un contexto de automatización.

2. Las invocaciones de herramientas son cadenas de shell no estructuradas, lo cual es propenso a errores de inyección de argumentos e imposible de auditar limpiamente.

3. No hay límite de tasa, límite de tiempo ni presupuesto de salida en lo que el agente puede hacer: un solo agente que se comporte mal puede atacar un objetivo o llenar el disco.

Este paquete resuelve los tres problemas exponiendo Kali a través de una API de trabajos tipados donde cada herramienta invocable se declara en un manifiesto, cada argumento es validado por Pydantic, cada ejecución de contenedor está en una lista de permitidos por prefijo de imagen y cada llamada requiere un token bearer.

Propiedades de seguridad principales

• Sin shell=True

• Sin punto final genérico de "ejecutar cualquier comando"

• Los trabajos se validan con esquemas explícitos

• La ejecución del contenedor está en una lista de permitidos por prefijo de imagen

• La ejecución de herramientas dentro del contenedor está en una lista de permitidos por nombre de binario

• La API requiere un token bearer

• El trabajador y la API son procesos separados

• Las herramientas de explotación/descifrado de credenciales/inalámbricas se eliminan explícitamente en la compilación de la imagen

• Registro de salida (egress) en cada herramienta que toca la red

Tipos de trabajo

• kali_probe

  • valida que el contenedor de Kali sea accesible y que la lista de permitidos de herramientas esté intacta

• osint_run

  • ejecuta una herramienta OSINT tipada de la lista de permitidos (amass, whatweb, gobuster, dnsenum, etc.) con argumentos estructurados

• traffic_capture

  • ejecuta mitmdump durante una duración limitada, devuelve un archivo de captura

• js_analysis

  • ejecuta linkfinder / secretfinder / arjun contra una URL de JavaScript

• leak_scan

  • ejecuta trufflehog contra una organización / repositorio de GitHub para buscar credenciales confirmadas

• subdomain_enum

  • ejecuta amass enum (solo fuentes pasivas) contra un dominio objetivo

• web_fingerprint

  • ejecuta whatweb para identificar la pila tecnológica de un objetivo

• nuclei_exposures

  • ejecuta nuclei contra un objetivo solo con el subconjunto de plantillas exposures/

  • los directorios de plantillas cves/, vulnerabilities/, default-logins/, fuzzing/ están bloqueados explícitamente

Inicio rápido

1. Copie las variables de entorno:

cp .env.example .env
./scripts/bootstrap-secrets.sh

2. El token de la API se almacena en:

.secrets/api_token

y .env apunta a él a través de KALI_FACTORY_API_TOKEN_FILE.

3. Inicie Redis:

docker compose up -d redis

4. Construya la imagen de tiempo de ejecución de Kali:

docker build -t kali-factory/recon:latest runtimes/kali/

5. Cree el entorno de Python:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

6. Ejecute la API:

./scripts/start-api.sh

7. Ejecute el trabajador:

./scripts/start-worker.sh

8. Ejecute el servidor MCP:

./scripts/start-mcp.sh

Solicitudes de ejemplo

Salud:

curl http://localhost:8081/health

Sonda Kali:

curl -X POST http://localhost:8081/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"kali_probe"}'

Enumeración de subdominios:

curl -X POST http://localhost:8081/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type":"subdomain_enum",
    "domain":"example.com",
    "max_runtime_sec": 300
  }'

Huella digital web:

curl -X POST http://localhost:8081/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type":"web_fingerprint",
    "url":"https://example.com"
  }'

Escaneo de fugas en GitHub:

curl -X POST http://localhost:8081/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type":"leak_scan",
    "github_org":"example-org"
  }'

Archivos

• START_HERE_FOR_AGENTS.md — guía de punto de entrada único para agentes que utilizan este plano de control

• runtimes/kali/Dockerfile — imagen de contenedor de Kali con las herramientas permitidas instaladas

• runtimes/kali/tools.json — manifiesto de herramientas declarativo (lista de permitidos + plantillas de argumentos)

• scripts/bootstrap-secrets.sh — crear y bloquear permisos del archivo de token de API

• scripts/start-api.sh — contenedor de lanzamiento para la API

• scripts/start-worker.sh — contenedor de lanzamiento para el trabajador

• scripts/start-mcp.sh — contenedor de lanzamiento para el servidor MCP local

• scripts/install-user-services.sh — instalar unidades de systemd a nivel de usuario

• src/kali_factory/api/ — servidor API (FastAPI)

• src/kali_factory/worker/ — ejecución de trabajos basada en RQ

• src/kali_factory/models/ — esquemas de trabajo de Pydantic

• src/kali_factory/jobs/ — controladores por tipo de trabajo

• src/kali_factory/policy/ — autenticación, aplicación de lista de permitidos, limitación de tasa

• src/kali_factory/mcp/server.py — adaptador MCP stdio sobre la API local de Kali Factory

• compose.yaml — sidecars de Redis (y ChromaDB opcional)

• Dockerfile — contenedor de aplicación para API/trabajador

• .env.example — configuraciones requeridas

• DEPLOYMENT.md — guía de ejecución y servicio específica del host

Siguiente endurecimiento recomendado

• Ponga la API detrás de Tailscale, Caddy u otra puerta de enlace solo interna

• Rote los tokens de API

• Agregue registro de auditoría a un archivo o SQLite

• Agregue cuotas de trabajo explícitas y límites de tasa por herramienta

• Agregue una lista de permitidos por objetivo (solo permita que los agentes reconozcan dominios que usted posee o tiene autorización para probar)

• Conecte el registro de salida en el contenedor de Kali para que se capture cada solicitud saliente

Modelo de servicio

• kali-factory-api.service debe ejecutarse de forma persistente

• kali-factory-worker.service debe ejecutarse de forma persistente

• el servidor MCP no debe ejecutarse como un servicio persistente

• los clientes MCP deben generar scripts/start-mcp.sh bajo demanda a través de stdio

Relación con otros paquetes de Factory

Los dos paquetes comparten la misma forma arquitectónica (FastAPI + Redis + RQ + autenticación bearer + trabajos tipados + ejecución Docker con lista de permitidos) y están diseñados para coexistir en el mismo host con puertos que no se superponen (8080 para GPU Factory, 8081 para Kali Factory).

Un futuro orquestador parallel-OS puede enrutar las solicitudes de los agentes a la Factory que coincida con el tiempo de ejecución que necesitan.

Lo que Kali Factory no es

• No es un escáner de vulnerabilidades. nuclei está incluido pero limitado a plantillas exposures/. Las plantillas de CVE / exploit / inicio de sesión predeterminado / fuzzing están bloqueadas explícitamente.

• No es un marco de explotación. Metasploit, sqlmap, hashcat, john, aircrack-ng, exploitdb, hydra, medusa, ncrack, nikto, wpscan, responder, impacket, crackmapexec se eliminan de la imagen de tiempo de ejecución en el momento de la compilación.

• No es una herramienta de prueba no autorizada. Úselo solo contra objetivos que usted posee o tiene autorización explícita para probar. La API registra cada trabajo; el mal uso es su responsabilidad.

Licencia

Apache 2.0 (ver LICENSE).