A Facebook Messenger bot framework designed for Capture The Flag (CTF) competitions, built with Node.js and Express.
- Overview
- Educational Purpose & Legal Notice
- Features
- Architecture
- Installation
- Configuration
- Usage
- API Reference
- Project Structure
- Development
- Contributing
- Legal & Policy Information
- License
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.
- 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
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.
- 🤖 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
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]
-
FacebookPage Class (
facebook-page/index.js)- Main bot framework
- Webhook handling
- Message routing
- Command management
-
Answer Handler (
src/answer.js)- Flag validation logic
- Challenge progression
- Score management
-
Utility Modules (
utils/)- Date/timezone handling
- GitHub Gist integration
- Text formatting
- Node.js (v14 or higher)
- npm or yarn
- Facebook Developer Account
- GitHub Account (for Gist integration)
-
Clone the repository
git clone https://github.com/RyannKim327/iTP-Cybersec.git cd iTP-Cybersec -
Install dependencies
npm install
-
Configure environment variables
cp .env.sample .env
-
Set up Facebook App
- Create a Facebook App at Facebook Developers
- Set up Messenger webhook
- Get your Page Access Token
-
Set up GitHub Gist
- Create a GitHub Personal Access Token
- Create a new Gist for data storage
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- Webhook URL:
https://your-domain.com/webhook - Verify Token: Use the same value as
KEY_TOKEN - Subscription Fields:
messages,messaging_postbacks
The bot expects two JSON files in your GitHub Gist:
[
{
"flag": "flag_sample",
"next": {
"title": "Sample Title",
"description": "Sample Description",
"hints": ["sample hint"]
},
"due_date": "12-31-2025"
}
][
{
"id": "user1_user2",
"players": {
"user1": 1,
"user2": 1
},
"failed": 0
}
]node index.jsThe server will start on the configured port (default: 3000).
The bot supports the following commands:
- Help:
:help- Display available commands - Flag Submission:
iTP{flag_content}- Submit CTF flags - Nickname:
nickname [name]- Set user nickname
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,
});title: Display name for the commandcommand: Regex pattern to matchhidden: Hide from help menuunprefix: Don't require command prefixany: Match anywhere in messageci: Case insensitive matching
const FacebookPage = require("./facebook-page");
const bot = new FacebookPage();Add a new command handler.
bot.addCommand("mycommand", {
title: "My Command",
command: "mycommand (.*)",
description: "Does something cool",
});Set the command prefix.
bot.setPrefix(":");Send a message to a user.
bot.sendMessage("Hello World!", event);Send an attachment.
bot.sendAttachment("image", "https://example.com/image.png", event);Add an admin user.
bot.addAdmin("facebook_user_id");Start the bot server.
bot.listen((app) => {
console.log("Bot is running!");
});const date = require("./utils/date");
const now = date(); // Current time in Asia/Manila
const custom = date("2025-12-31 23:59:59", "Asia/Manila");const { get, post } = require("./utils/gist");
// Read data
const data = await get("challenges.json");
// Write data
await post("challenges.json", newData);const markdown = require("./utils/markdown");
const formatted = markdown("Hello World"); // Returns bold Unicode textiTP-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
index.js: Main application entry point, configures bot commandsfacebook-page/index.js: Core bot framework with webhook handlingsrc/answer.js: CTF flag validation and challenge progression logicutils/date.js: Timezone-aware date handling utilitiesutils/gist.js: GitHub Gist API integration for data persistenceutils/markdown.js: Unicode text formatting for rich messagingfacebook-page/web/index.html: Static landing page for the webhook
- 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);
};- Register the command in
index.js:
api.addCommand("mycommand", {
title: "My Command",
command: "mycommand (.*)",
description: "Echoes user input",
});Add utility functions in the utils/ directory:
// utils/myutil.js
module.exports = {
doSomething: (input) => {
return input.toUpperCase();
},
};-
Local Development:
- Use ngrok for webhook testing:
ngrok http 3000 - Update Facebook webhook URL to ngrok URL
- Use ngrok for webhook testing:
-
Environment Setup:
- Create test Facebook page
- Use separate Gist for test data
Enable debug logging by setting environment variables:
DEBUG=* node index.js- Fork the repository
- Create a feature branch:
git checkout -b feature-name - Make your changes
- Add tests if applicable
- Commit your changes:
git commit -am 'Add feature' - Push to the branch:
git push origin feature-name - Submit a pull request
- Use consistent indentation (2 spaces)
- Follow existing naming conventions
- Add comments for complex logic
- Update documentation for new features
This project is licensed under the ISC License. See the LICENSE file for details.
Ryann Kim Sesgundo [MPOP Reverse II]
IT Paradigm Organization
- 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.