---
title: SecurityChatbot
emoji: 📚
colorFrom: gray
colorTo: pink
sdk: docker
pinned: false
---

# Security Awareness Chatbot 🔐🤖

A modular, AI-powered backend that simulates social engineering attacks and provides interactive quizzes to train users on cybersecurity best practices—all in a friendly **Egyptian Arabic** persona!

## 🌟 What Does This Bot Offer?

1. **🛡️ Interactive Security Assistant**
   Talk to a cybersecurity expert AI. Ask any question about digital safety, and get answers in simple, casual Egyptian Arabic.

2. **🕵️‍♂️ Social Engineering Simulation (Roleplay)**
   Users can type `/train` to enter a simulated attack scenario. 
   - **Scenarios:** Bank employee, Delivery Courier, IT Support, WhatsApp Support, Lottery.
   - **Difficulty Levels:** Easy, Medium, Hard (ranging from obvious to highly manipulative).
   - **Mechanism:** The AI plays the attacker, trying to extract sensitive info. A separate AI (Evaluator) acts as a referee to catch if the user leaks data or successfully defends themselves for 4 turns.

3. **📝 Dynamic Cybersecurity Quizzes**
   Users can choose the Quiz mode to get a dynamically generated Multiple Choice Question (MCQ) about cybersecurity topics. The bot evaluates their answer and provides a friendly explanation.

4. **⚡ High Reliability (Fallback Logic)**
   Powered by OpenAI (GPT-4o-mini) and Groq (Llama-3), with built-in automatic fallback to Google Gemini (1.5-flash) if the primary models experience downtime.

---

## 📁 Project Structure

```
securityChatbot/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── core/
│   │   ├── __init__.py
│   │   ├── config.py
│   │   └── prompts.py
│   ├── models/
│   │   ├── __init__.py
│   │   └── schemas.py
│   ├── routers/
│   │   ├── __init__.py
│   │   └── webhook.py
│   └── services/
│       ├── __init__.py
│       ├── llm_service.py
│       └── state_manager.py
├── Dockerfile
├── .dockerignore
├── pyproject.toml
└── README.md
```

## Setup & Run Locally

```bash
uv sync
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

## API Endpoints

| Method | Path       | Description                  |
|--------|------------|------------------------------|
| GET    | `/`        | Health check                 |
| POST   | `/webhook` | Main chat endpoint           |

### Webhook Payload

```json
{
  "user_id": "user123",
  "message": "Hello"
}
```

### Commands

- `/train` — Start the social engineering simulation