SocEng Lab is an open-source adaptive social engineering simulation platform that brings academic rigor to security awareness training. This AI-driven tool adapts attacks in real-time based on user responses like a "choose-your-own-adventure" experience powered by Cialdini's six principles of influence and threat actor playbooks. By mapping attack scenarios to Cialdini's principles and implementing persona-based adaptive branching, teams can measure and improve human resilience against social engineering at scale.

THIS TOOL IS FOR AUTHORIZED SECURITY TESTING AND TRAINING ONLY

• ✅ Use only with explicit written consent from all participants
• ✅ All simulations run locally - NO external messages sent
• ✅ Designed for controlled training environments
• ❌ DO NOT use against real targets without authorization
• ❌ Unauthorized use may violate laws (e.g., CFAA, GDPR, local anti-fraud laws)

By using this tool, you agree to use it ethically and legally. The developers assume no liability for misuse.

• AI Challenge Generator: Dynamic LLM-powered challenges with real-time AI evaluation and chatbot-style interaction
• Adaptive Challenge Engine: Node-based branching scenarios with dynamic escalation
• Quiz Mode: Multiple-choice assessments with instant feedback
• Bilingual: English and Indonesian (i18n ready)
• Offline-First: Works without network by default
• Single User: Seeded authentication, no registration
• Scoring Engine: 0-100 susceptibility score with Cialdini category breakdown
• Similarity-Based Essay Scoring: Dynamic evaluation of open-ended answers using Levenshtein distance algorithm

# Clone
git clone https://github.com/dalpan/SocengLab.git
cd SocengLab

# Start
make build
make up
make seed

# Done! 
# Frontend: http://localhost:3000
# Backend: http://localhost:8001
# Login: soceng / Cialdini@2025!

The AI Challenge feature requires an API key from the LLM provider you choose. Example providers and quick steps to obtain an API key:

• Google AI Studio:

  1. Open https://aistudio.google.com/api-keys
  2. Sign in with your Google account
  3. Create a new API key and copy its value

• OpenAI:

  1. Open https://platform.openai.com/account/api-keys
  2. Sign in, create a new API key, and copy it

• Anthropic / Gemini / Other providers: follow the provider's documentation to create an API key

After obtaining the API key, add it to the application via Settings → LLM Configuration

Security note: do not commit API keys to public repositories. Store keys securely and restrict access where possible.

# Backend
cd backend
pip install -r requirements.txt
uvicorn server:app --reload --port 8001

# Frontend  
cd frontend
yarn install
yarn start

# Import samples
python bin/import_yaml.py data/sample/

Use the AI Challenge Generator interface:

1. Go to AI Challenge page
2. Select challenge type: Comprehensive, Email Analysis, Interactive, or Real-World Scenarios
3. Configure:
   • Category (Phishing, Pretexting, Baiting, Tailgating, Vishing, Spear Phishing)
   • Difficulty (Beginner, Intermediate, Advanced)
   • Language (Indonesian, English)
   • Number of Questions (3-20)
4. Click "Generate Challenge"
5. Answer questions in chatbot-style interface with real-time AI evaluation
6. Review detailed results with AI feedback and similarity scores

Features:

• Multiple question formats: Multiple Choice, Scenario Analysis, Red Flag Identification, Email Analysis
• AI-powered real-time evaluation and adaptive question sequencing
• Dynamic essay scoring based on semantic similarity (≥70% similarity = correct)
• Instant feedback with learning insights for each answer

Make file data/sample/your-challenge.yaml:

type: challenge
title: "Challenge Title"
difficulty: medium
cialdini_categories: [authority, urgency]
nodes:
  - id: start
    type: message
    channel: email_inbox
    content_en:
      subject: "..."
      body: "..."
    next: choice_1

Detail template

type: quiz
title: "Quiz Title"
difficulty: easy
questions:
  - id: q1
    content_en:
      text: "Question?"
    options:
      - text: "Answer A"
        correct: true

Detail template

python bin/validate_yaml.py your-file.yaml
# Submit PR to GitHub

Readmore for detail Contribution

This project is licensed under the MIT License - see the LICENSE file for details.

• Dr. Robert Cialdini for foundational research on influence and persuasion
• The security research community for continuous innovation
• All contributors and testers