Skip to content
Public template

About

Surprise Gift for you

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

iTP CyberServer - Facebook Messenger CTF Bot

A Facebook Messenger bot framework designed for Capture The Flag (CTF) competitions, built with Node.js and Express.

📋 Table of Contents

🎯 Overview

iTP CyberServer is a specialized Facebook Messenger bot framework designed for running CTF (Capture The Flag) competitions. It provides automated challenge management, flag validation, team scoring, and real-time communication through Facebook Messenger.

Key Components

  • Facebook Page Bot Framework: Core messaging and webhook handling
  • CTF Challenge System: Flag validation and progression management
  • GitHub Gist Integration: Data persistence for challenges and user scores
  • Utility Functions: Date handling, markdown formatting, and more

🎓 Educational Purpose & Legal Notice

⚠️ IMPORTANT: EDUCATIONAL USE ONLY ⚠️

This platform is designed exclusively for educational purposes in the field of cybersecurity. By using this platform, you agree to:

  • Use all knowledge for educational and defensive purposes only
  • Never engage in illegal hacking activities
  • Respect privacy and security of others
  • Comply with all applicable laws and regulations
  • Report any misuse or violations immediately

iT Paradigm does not condone, support, or provide tools for any illegal activities. All users are responsible for their actions and must use cybersecurity knowledge ethically and legally.

For complete legal and policy information, see our Policy Documentation.

✨ Features

  • 🤖 Facebook Messenger Integration: Full webhook support for real-time messaging
  • 🏁 CTF Flag Management: Automated flag validation and challenge progression
  • 👥 Team Management: Multi-player team support with individual scoring
  • 📊 Data Persistence: GitHub Gist integration for storing challenges and scores
  • ⏰ Time-based Challenges: Due date validation for time-sensitive challenges
  • 🎨 Rich Text Formatting: Unicode character conversion for enhanced messaging
  • 🔧 Extensible Command System: Easy-to-add custom commands and handlers
  • 📁 Static File Serving: Support for assets and temporary files

🏗️ Architecture

flowchart TD
    A[Facebook Messenger] -->|Webhook| B[Express Server]
    B --> C[FacebookPage Class]
    C --> D[Command Router]
    D --> E[Answer Handler]
    D --> F[Alias Handler]
    E --> G[GitHub Gist API]
    G --> H[Challenges Data]
    G --> I[User Scores]
    C --> J[Utility Functions]
    J --> K[Date Utils]
    J --> L[Markdown Utils]
    J --> M[Gist Utils]
Loading

Core Components

  1. FacebookPage Class (facebook-page/index.js)

    • Main bot framework
    • Webhook handling
    • Message routing
    • Command management
  2. Answer Handler (src/answer.js)

    • Flag validation logic
    • Challenge progression
    • Score management
  3. Utility Modules (utils/)

    • Date/timezone handling
    • GitHub Gist integration
    • Text formatting

🚀 Installation

Prerequisites

  • Node.js (v14 or higher)
  • npm or yarn
  • Facebook Developer Account
  • GitHub Account (for Gist integration)

Setup

  1. Clone the repository

    git clone https://github.com/RyannKim327/iTP-Cybersec.git
    cd iTP-Cybersec
  2. Install dependencies

    npm install
  3. Configure environment variables

    cp .env.sample .env
  4. Set up Facebook App

    • Create a Facebook App at Facebook Developers
    • Set up Messenger webhook
    • Get your Page Access Token
  5. Set up GitHub Gist

    • Create a GitHub Personal Access Token
    • Create a new Gist for data storage

⚙️ Configuration

Environment Variables

Create a .env file with the following variables:

# Facebook Page Access Token
FB_TOKEN=your_facebook_page_access_token

# Webhook verification token
KEY_TOKEN=your_webhook_verification_token

# GitHub Gist integration
GIST_TOKEN=your_github_personal_access_token
GIST_ID=your_gist_id

# Optional: Server port (default: 3000)
PORT=3000

Facebook Webhook Setup

  1. Webhook URL: https://your-domain.com/webhook
  2. Verify Token: Use the same value as KEY_TOKEN
  3. Subscription Fields: messages, messaging_postbacks

Data Structure

The bot expects two JSON files in your GitHub Gist:

challenges.json

[
  {
    "flag": "flag_sample",
    "next": {
      "title": "Sample Title",
      "description": "Sample Description",
      "hints": ["sample hint"]
    },
    "due_date": "12-31-2025"
  }
]

matches.json

[
  {
    "id": "user1_user2",
    "players": {
      "user1": 1,
      "user2": 1
    },
    "failed": 0
  }
]

🎮 Usage

Starting the Server

node index.js

The server will start on the configured port (default: 3000).

Bot Commands

The bot supports the following commands:

Built-in Commands

  • Help: :help - Display available commands
  • Flag Submission: iTP{flag_content} - Submit CTF flags
  • Nickname: nickname [name] - Set user nickname

Command Configuration

Commands are configured in index.js:

api.addCommand("answer", {
  title: "Flag for CTF",
  command: "iTP{([\\w\\W]+)}",
  hidden: true,
  unprefix: true,
  any: true,
  ci: false,
});

Command Properties

  • title: Display name for the command
  • command: Regex pattern to match
  • hidden: Hide from help menu
  • unprefix: Don't require command prefix
  • any: Match anywhere in message
  • ci: Case insensitive matching

📚 API Reference

FacebookPage Class

Constructor

const FacebookPage = require("./facebook-page");
const bot = new FacebookPage();

Methods

addCommand(script, command)

Add a new command handler.

bot.addCommand("mycommand", {
  title: "My Command",
  command: "mycommand (.*)",
  description: "Does something cool",
});
setPrefix(prefix)

Set the command prefix.

bot.setPrefix(":");
sendMessage(message, event, callback)

Send a message to a user.

bot.sendMessage("Hello World!", event);
sendAttachment(fileType, fileUrl, event, callback)

Send an attachment.

bot.sendAttachment("image", "https://example.com/image.png", event);
addAdmin(adminID)

Add an admin user.

bot.addAdmin("facebook_user_id");
listen(callback)

Start the bot server.

bot.listen((app) => {
  console.log("Bot is running!");
});

Utility Functions

Date Utils (utils/date.js)

const date = require("./utils/date");
const now = date(); // Current time in Asia/Manila
const custom = date("2025-12-31 23:59:59", "Asia/Manila");

Gist Utils (utils/gist.js)

const { get, post } = require("./utils/gist");

// Read data
const data = await get("challenges.json");

// Write data
await post("challenges.json", newData);

Markdown Utils (utils/markdown.js)

const markdown = require("./utils/markdown");
const formatted = markdown("Hello World"); // Returns bold Unicode text

📁 Project Structure

iTP-Cybersec/
├── facebook-page/           # Bot framework
│   ├── index.js            # Main FacebookPage class
│   └── web/                # Static web files
│       └── index.html      # Landing page
├── src/                    # Command handlers
│   └── answer.js          # Flag validation logic
├── utils/                  # Utility functions
│   ├── date.js            # Date/timezone utilities
│   ├── gist.js            # GitHub Gist integration
│   └── markdown.js        # Text formatting
├── index.js               # Application entry point
├── package.json           # Dependencies and scripts
├── .env.sample           # Environment variables template
└── .gitignore            # Git ignore rules

File Descriptions

  • index.js: Main application entry point, configures bot commands
  • facebook-page/index.js: Core bot framework with webhook handling
  • src/answer.js: CTF flag validation and challenge progression logic
  • utils/date.js: Timezone-aware date handling utilities
  • utils/gist.js: GitHub Gist API integration for data persistence
  • utils/markdown.js: Unicode text formatting for rich messaging
  • facebook-page/web/index.html: Static landing page for the webhook

🛠️ Development

Adding New Commands

  1. Create a command handler in the src/ directory:
// src/mycommand.js
module.exports = async (api, event, regex) => {
  const userInput = event.message.text.match(regex)[1];
  api.sendMessage(`You said: ${userInput}`, event);
};
  1. Register the command in index.js:
api.addCommand("mycommand", {
  title: "My Command",
  command: "mycommand (.*)",
  description: "Echoes user input",
});

Custom Utilities

Add utility functions in the utils/ directory:

// utils/myutil.js
module.exports = {
  doSomething: (input) => {
    return input.toUpperCase();
  },
};

Testing

  1. Local Development:

    • Use ngrok for webhook testing: ngrok http 3000
    • Update Facebook webhook URL to ngrok URL
  2. Environment Setup:

    • Create test Facebook page
    • Use separate Gist for test data

Debugging

Enable debug logging by setting environment variables:

DEBUG=* node index.js

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature-name
  3. Make your changes
  4. Add tests if applicable
  5. Commit your changes: git commit -am 'Add feature'
  6. Push to the branch: git push origin feature-name
  7. Submit a pull request

Code Style

  • Use consistent indentation (2 spaces)
  • Follow existing naming conventions
  • Add comments for complex logic
  • Update documentation for new features

📄 License

This project is licensed under the ISC License. See the LICENSE file for details.

👨‍💻 Author

Ryann Kim Sesgundo [MPOP Reverse II]
IT Paradigm Organization

🙏 Acknowledgments

  • Facebook Messenger Platform
  • GitHub Gist API
  • Express.js framework
  • Axios HTTP client
  • Cybersecurity education community
  • Ethical hacking professionals

Remember: Cybersecurity education is about building defenses and protecting systems, not attacking them. Use your knowledge responsibly, ethically, and within the bounds of the law.

For more information, visit the Facebook Developers Documentation.

About

Surprise Gift for you

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages