Инструкции по Kali Factory

Более безопасная локальная плоскость управления для ИИ-агентов, которым необходим доступ к инструментам OSINT в Kali Linux.

Этот пакет повторяет структуру GPU Factory — типизированная отправка заданий с аутентификацией по токену, выполнение в очереди, запуск Docker-образов из белого списка — но применяется к другой задаче: предоставление доступа к инструментам разведки и анализа трафика Kali без предоставления агентам неаутентифицированной оболочки (shell).

• API управления на FastAPI

• Очередь Redis

• Воркер RQ

• Выполнение в Docker-контейнерах на базе защищенного образа Kali

• Типизированные задания (osint, захват трафика, анализ JS, поиск утечек) вместо прямого доступа к shell

• Аутентификация по токену (Bearer token)

• Локальный MCP-сервер для агентов с поддержкой MCP

• Опциональный сайдкар ChromaDB для сохранения результатов разведки между запусками

Зачем это нужно

В состав Kali входят сотни инструментов, многие из которых полезны для легитимной конкурентной разведки и исследований безопасности, а некоторые не подходят для автоматизации агентами. Наивный подход — поместить агента в оболочку Kali и позволить ему самому во всем разобраться — порождает три проблемы:

1. Агент получает доступ ко всем инструментам, включая фреймворки для эксплуатации (metasploit, sqlmap, hashcat, john, aircrack-ng, exploitdb), которые никогда не должны быть доступны в контексте автоматизации.

2. Вызовы инструментов представляют собой неструктурированные строки оболочки, что подвержено ошибкам внедрения аргументов и невозможно для чистого аудита.

3. Отсутствуют ограничения по скорости, времени или объему вывода для действий агента — один некорректно работающий агент может перегрузить цель или заполнить диск.

Этот пакет решает все три проблемы, предоставляя доступ к Kali через API типизированных заданий, где каждый вызываемый инструмент объявлен в манифесте, каждый аргумент проверяется с помощью Pydantic, каждый запуск контейнера ограничен префиксом образа, а для каждого вызова требуется токен.

Основные свойства безопасности

• Нет shell=True

• Нет эндпоинта для «запуска любой команды»

• Задания проверяются по явным схемам

• Выполнение в контейнерах ограничено префиксом образа

• Выполнение инструментов внутри контейнера ограничено по имени бинарного файла

• API требует токен

• Воркер и API — это отдельные процессы

• Инструменты для эксплуатации/взлома учетных данных/беспроводных сетей явно удалены при сборке образа

• Логирование исходящего трафика для каждого инструмента, который обращается к сети

Типы заданий

• kali_probe

  • проверяет доступность контейнера Kali и целостность белого списка инструментов

• osint_run

  • выполняет типизированный инструмент OSINT из белого списка (amass, whatweb, gobuster, dnsenum и т.д.) со структурированными аргументами

• traffic_capture

  • запускает mitmdump на ограниченное время, возвращает файл захвата

• js_analysis

  • запускает linkfinder / secretfinder / arjun для URL-адреса JavaScript

• leak_scan

  • запускает trufflehog для организации/репозитория GitHub для поиска закоммиченных учетных данных

• subdomain_enum

  • запускает amass enum (только пассивные источники) для целевого домена

• web_fingerprint

  • запускает whatweb для идентификации технологического стека цели

• nuclei_exposures

  • запускает nuclei для цели только с подмножеством шаблонов exposures/

  • директории шаблонов cves/, vulnerabilities/, default-logins/, fuzzing/ явно заблокированы

Быстрый старт

1. Скопируйте переменные окружения:

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

2. Токен API хранится в:

.secrets/api_token

и .env указывает на него через KALI_FACTORY_API_TOKEN_FILE.

3. Запустите Redis:

docker compose up -d redis

4. Соберите образ среды выполнения Kali:

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

5. Создайте среду Python:

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

6. Запустите API:

./scripts/start-api.sh

7. Запустите воркер:

./scripts/start-worker.sh

8. Запустите MCP-сервер:

./scripts/start-mcp.sh

Примеры запросов

Проверка состояния:

curl http://localhost:8081/health

Проверка Kali:

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

Перечисление поддоменов:

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
  }'

Веб-фингерпринт:

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"
  }'

Сканирование утечек на 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"
  }'

Файлы

• START_HERE_FOR_AGENTS.md — руководство с единой точкой входа для агентов, использующих эту плоскость управления

• runtimes/kali/Dockerfile — образ контейнера Kali с установленными инструментами из белого списка

• runtimes/kali/tools.json — декларативный манифест инструментов (белый список + шаблоны аргументов)

• scripts/bootstrap-secrets.sh — создание и настройка прав доступа к файлу токена API

• scripts/start-api.sh — обертка для запуска API

• scripts/start-worker.sh — обертка для запуска воркера

• scripts/start-mcp.sh — обертка для запуска локального MCP-сервера

• scripts/install-user-services.sh — установка пользовательских юнитов systemd

• src/kali_factory/api/ — API-сервер (FastAPI)

• src/kali_factory/worker/ — выполнение заданий на базе RQ

• src/kali_factory/models/ — схемы заданий Pydantic

• src/kali_factory/jobs/ — обработчики для каждого типа заданий

• src/kali_factory/policy/ — аутентификация, соблюдение белого списка, ограничение скорости

• src/kali_factory/mcp/server.py — адаптер stdio MCP поверх локального API Kali Factory

• compose.yaml — сайдкары Redis (и опционально ChromaDB)

• Dockerfile — контейнер приложения для API/воркера

• .env.example — необходимые настройки

• DEPLOYMENT.md — руководство по запуску и обслуживанию на конкретном хосте

Рекомендуемое дальнейшее усиление защиты

• Разместите API за Tailscale, Caddy или другим внутренним шлюзом

• Ротируйте токены API

• Добавьте логирование аудита в файл или SQLite

• Добавьте явные квоты на задания и ограничения скорости для каждого инструмента

• Добавьте белый список целей (разрешайте агентам проводить разведку только тех доменов, которыми вы владеете или на тестирование которых у вас есть разрешение)

• Настройте логирование исходящего трафика в контейнере Kali, чтобы фиксировать каждый исходящий запрос

Модель обслуживания

• kali-factory-api.service должен работать постоянно

• kali-factory-worker.service должен работать постоянно

• MCP-сервер не должен работать как постоянная служба

• MCP-клиенты должны запускать scripts/start-mcp.sh по требованию через stdio

Связь с другими пакетами Factory

Оба пакета имеют одинаковую архитектурную форму (FastAPI + Redis + RQ + аутентификация по токену + типизированные задания + выполнение Docker из белого списка) и предназначены для сосуществования на одном хосте с непересекающимися портами (8080 для GPU Factory, 8081 для Kali Factory).

Будущий оркестратор parallel-OS сможет направлять запросы агентов в ту Factory, которая соответствует необходимой им среде выполнения.

Чем Kali Factory НЕ является

• Не сканер уязвимостей. nuclei включен, но ограничен шаблонами exposures/. Шаблоны CVE / эксплойтов / стандартных логинов / фаззинга явно заблокированы.

• Не фреймворк для эксплуатации. Metasploit, sqlmap, hashcat, john, aircrack-ng, exploitdb, hydra, medusa, ncrack, nikto, wpscan, responder, impacket, crackmapexec — все они удаляются из образа среды выполнения при сборке.

• Не инструмент для несанкционированного тестирования. Используйте только против целей, которыми вы владеете или на тестирование которых у вас есть явное разрешение. API логирует каждое задание; ответственность за злоупотребление лежит на вас.

Лицензия

Apache 2.0 (см. LICENSE).