SocEngLab is an interactive social engineering simulation platform focused on the human layer of security. Instead of exploiting software bugs, this lab models how attackers manipulate trust, authority, urgency, and emotion during real conversations.

Unlike traditional phishing simulators or offensive toolkits, SocEngLab places participants in the role of the target, not the attacker. The goal is not to win, but to experience manipulation, recognize influence, and reflect on failure.

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