Chat-Bot-Hacker - Defensive-security assistant with local knowledge

项目说明

🛡️ CyberSec AI — чат-бот этичного хакера

> CyberSec AI — учебный браузерный помощник по defensi, Linux, сетям, SOC, CTF и легальному пентесту. Он работает локально без AI API и при желании подключается к защищённому Node.js backend.

<p align="center">
<strong>💻 Терминальный UI</strong> · <strong>🧠 Local RAG</strong> · <strong>🔐 Defensi</strong> · <strong>⚡ Optional AI Backend</strong>
</p>

---

⚖️ Этическое назначение

CyberSec AI создан только для:

Он не предназначен для взлома чужих аккаунтов, фишинга, DDoS, malware, обхода авторизации, закрепления в чужих системах или сокрытия следов.

---

✨ Что умеет бот

| Возможность | Что внутри |
| --- | --- |
| 🧭 7 режимов ответа | Наставник, Эксперт, SOC-аналитик, Пентестер, Администратор, CTF-помощник, Параноик |
| 📚 Локальная база знаний | FAQ, knowledge.json, commands.json |
| 🔎 Простая RAG-логика | Ключевые слова, релевантность, выбор лучшего документа, отображение источника |
| 🧰 Разбор команд | Linux, PowerShell, CMD: назначение, риск, параметры, безопасный вариант |
| 🧾 Анализ логов | Тип логов, ошибки, IP, порты, гипотезы и безопасный план диагностики |
| ✅ Генератор чек-листов | VPS, сайт, SSH, Docker, роутер, бэкапы, расследование активности |
| 🧠 Опциональный AI backend | Express endpoint /api/chat, OpenAI API key только на сервере |
| 🛡️ Safety-first UX | Отказ от вредных запросов и перенаправление в защитный сценарий |
| 💾 История диалога | localStorage, экспорт .json/.txt, отключение сохранения |
| 🎨 Cyber dashboard UI | Тёмная/светлая тема, terminal vibe, адаптивность, анимация печати |

---

🗂️ Дерево проекта

---

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

1️⃣ Установите Node.js

Скачайте актуальную LTS-версию с < или установите через пакетный менеджер вашей ОС.

Проверьте установку:

2️⃣ Установите зависимости

3️⃣ Создайте .env

Для полностью локального режима оставьте ключ пустым:

4️⃣ Запустите сервер

5️⃣ Откройте приложение

Перейдите в браузере на:

---

🧩 Структура файлов

| Файл | Назначение |
| --- | --- |
| index.html | Разметка приложения: header, sidebar, быстрые кнопки, чат и форма ввода |
| styles.css | Современный адаптивный cybersecurity dashboard: темы, панели, терминальный эффект |
| script.js | Локальные ответы, RAG, история, экспорт, кнопки оценки, safety checks, fallback |
| faq.json | Частые вопросы; используется первым при точном совпадении |
| knowledge.json | Документы по SSH, firewall, Docker, OWASP, логам, MFA, фишингу и IR |
| commands.json | Справочник безопасных Linux/Windows/сетевых диагностических команд |
| server.js | Express backend с /api/chat, rate limit, AI-интеграцией и локальным fallback |
| .en | Шаблон конфигурации без секретов |
| package.json | Скрипты запуска и зависимости |

---

🧠 Как работает локальный режим

Локальный режим не требует OpenAI API и работает прямо в браузере по JSON-файлам.

---

🔎 Как устроен простой RAG

RAG здесь намеренно простой, прозрачный и удобный для обучения:

1. 🧹 запрос нормализуется в нижний регистр;
2. ✂️ текст разбивается на ключевые слова;
3. 📄 каждый документ из knowledge.json превращается в набор слов;
4. 📊 считается пересечение слов запроса с документом;
5. 🏆 выбирается документ с лучшей примерной релевантностью;
6. 🧾 ответ показывает источник локального знания.

> ⚠️ Ограничение: это не семантический поиск. Нет эмбеддингов, морфологии, reranking и внешней проверки фактов. Зато логику легко понять, изменить и расширить.

---

🤖 AI-режим

AI-режим включается переключателем в интерфейсе. Frontend отправляет на backend:

Backend:

Почему API-ключ нельзя хранить во frontend

Frontend-код загружается в браузер пользователя. Любой ключ внутри HTML/JS/CSS можно увидеть в De, скачать из вкладки Network или извлечь из исходников. Поэтому ключ хранится только на backend, в .env, секрет-хранилище или переменных окружения платформы.

---

🛡️ Реализованные меры безопасности

---

🧰 Как добавлять новые знания

Добавить статью в knowledge.json

Добавить команду в commands.json

---

🧪 Как протестировать fallback

| Сценарий | Ожидаемое поведение |
| --- | --- |
| OPENAI_API_KEY пустой, AI toggle включён | Backend вернёт LOCAL_FALLBACK |
| OpenAI API недоступен | Backend не раскрывает ошибку и отвечает локально |
| Сервер остановлен | Frontend показывает ошибку AI и использует локальный режим, если JSON доступен |
| Повреждён JSON | Интерфейс показывает понятную ошибку загрузки базы |
| Пустое сообщение | Бот просит ввести задачу, команду или логи |

---

🌍 Размещение на VPS

Рекомендуемый безопасный порядок:

1. 🧑‍💻 создайте отдельного пользователя без root-доступа для приложения;
2. 📦 установите Node.js LTS и Nginx;
3. 📁 разместите проект, например в /opt/cybersec-ai;
4. 🔐 создайте .env и задайте права chmod 600 .env;
5. 📥 установите зависимости через npm ci --omit=dev;
6. 🧭 запустите приложение через systemd или PM2;
7. 🔥 откройте на firewall только 80/443;
8. 🧾 включите логирование и ротацию логов;
9. 💾 настройте резервное копирование .env отдельно и безопасно.

---

🌐 Reverse proxy через Nginx

Минимальный пример:

Для production добавьте:

---

🧱 Архитектура приложения

---

🧭 FAQ vs RAG vs AI

| Источник | Когда используется | Плюсы | Ограничения |
| --- | --- | --- | --- |
| ❓ FAQ | Точное совпадение популярного вопроса | Быстро, стабильно, предсказуемо | Работает только на заранее добавленных вопросах |
| 🔎 RAG | Похожий вопрос по теме из базы знаний | Показывает источник, легко расширяется | Не понимает глубокую семантику |
| 🤖 AI | Сложный анализ, конфигурации, логи, объяснения | Гибкие ответы и контекст | Нужны backend, ключ, сеть и safety-контроль |

---

🧭 Режимы ответа

---

🛣️ Идеи для следующей версии

---

📌 Главное

CyberSec AI — это не «магический хакер», а аккуратный учебный помощник: он помогает понимать риски, защищать системы, разбирать логи и строить безопасные планы действий. Чем лучше вы пополняете faq.json, knowledge.json и commands.json, тем полезнее становится локальный режим.

项目信息

开发语言：CSS

Star 数：1

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Defensive-security assistant with local knowledge retrieval, command and log analysis, an optional OpenAI backend and rate limiting.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。