Skip to content
Umbrelle

Umbrelle

Umbrelle (hereinafter the “Application”) is a Discord bot that allows server administrators to configure honeypot channels to automatically detect and soft-ban compromised accounts. When an account posts in a designated honeypot channel, the bot will temporarily ban the user to remove their message history and immediately unban them, allowing them to return once they’ve recovered their account.

1. User Documentation

Section titled “1. User Documentation”

This section is for those interacting with a live instance of the Application.

Getting Started

Section titled “Getting Started”

  1. Adding Umbrelle to Your Server

  2. Setting Up a Honeypot Channel

    • Use the /honeypot command followed by the channel you want to designate as a honeypot
    • Only users with “Manage Guild” permissions can configure honeypot channels
    • Example: /honeypot channel:#suspicious-activity

  3. How It Works

    • When any user (excluding bots and system messages) posts in the configured honeypot channel, they will be automatically soft-banned
    • Soft-ban process:
      • User receives a DM explaining the situation
      • User is banned to remove message history (24 hours of messages)
      • User is immediately unbanned and can rejoin when ready
    • Only accounts that are “bannable” (not server owners, higher role hierarchy) will be affected

Available Commands

Section titled “Available Commands”
  • /about - Display information about Umbrelle and links to support resources
  • /honeypot <channel> - Configure a honeypot channel (requires Manage Guild permission)

Support and Help

Section titled “Support and Help”

If you need assistance:

2. Technical Documentation

Section titled “2. Technical Documentation”

This section is for those interested in running their own instance of the Application.

Architecture Overview

Section titled “Architecture Overview”

Umbrelle is built with:

  • Discord.js v14 - Discord API interaction
  • TypeScript - Type-safe development
  • Prisma - Database ORM
  • MongoDB - Data persistence
  • Fastify - Web server for health monitoring
  • 1Password CLI - Secure environment variable management

System Requirements

Section titled “System Requirements”
  • Node.js (compatible with the version specified in package.json)
  • MongoDB database
  • Discord Bot Token
  • 1Password CLI (for production deployment)

Project Structure

Section titled “Project Structure”
src/
├── components/        # Discord UI components
│   └── about.ts      # About command interface
├── events/           # Discord event handlers
│   ├── handleInteraction.ts  # Slash command processing
│   ├── handleMessage.ts      # Message event handling
│   └── handleReady.ts        # Bot initialization
├── interfaces/       # TypeScript type definitions
│   └── umbrelle.ts   # Core application interface
├── server/           # Web server implementation
│   └── serve.ts      # Health monitoring server
├── utils/           # Utility functions
│   └── logger.ts    # Logging implementation
└── index.ts         # Application entry point

Database Schema

Section titled “Database Schema”

The application uses a simple MongoDB schema with Prisma:

model Honeypots {
  id        String @id @default(auto()) @map("_id") @db.ObjectId
  serverId  String @unique
  channelId String @unique
}

Environment Variables

Section titled “Environment Variables”

Required environment variables:

  • BOT_TOKEN - Discord bot token
  • MONGO_URI - MongoDB connection string

Build and Deployment

Section titled “Build and Deployment”

  1. Development Setup

    Terminal window
    npm install
    npm run build

  2. Production Deployment

    Terminal window
    npm run start  # Uses 1Password CLI for environment management

  3. Available Scripts

    • build - Generate Prisma client and compile TypeScript
    • lint - Run ESLint with zero warnings tolerance
    • start - Production start with 1Password environment loading
    • test - Placeholder test command

Security Considerations

Section titled “Security Considerations”
  • Bot permissions are limited to Guild and Guild Messages intents
  • Only users with Manage Guild permissions can configure honeypots
  • Soft-ban mechanism preserves user ability to rejoin
  • No sensitive data logging or exposure
  • Follows Discord’s best practices for bot development
Section titled “3. Legal Documentation”

This section is for expansions to our legal policies specific to the Application.

License

Section titled “License”

This application is licensed under Naomi’s Public Licence. The full licence text can be found in the LICENSE.md file in the repository.

Section titled “Copyright”

Copyright held by Naomi Carrigan (SpellWare).

Data Handling

Section titled “Data Handling”
  • Umbrelle stores minimal data: server IDs and channel IDs for honeypot configuration
  • No user messages, personal information, or sensitive data is stored
  • Database records are only used for bot functionality
  • Users can request removal of their server’s data by removing the bot from their server

Terms of Service

Section titled “Terms of Service”

Users should refer to TERMS.md for detailed terms of service.

Privacy Policy

Section titled “Privacy Policy”

Users should refer to PRIVACY.md for detailed privacy policy information.

Security Policy

Section titled “Security Policy”

Security concerns should be reported according to the guidelines in SECURITY.md.

4. Contributing Documentation

Section titled “4. Contributing Documentation”

This section is for documentation related to contributing to the Application’s codebase.

Development Environment

Section titled “Development Environment”

  1. Prerequisites

    • Node.js and npm/pnpm
    • MongoDB instance (local or cloud)
    • Discord application with bot token
    • Git for version control

  2. Setup Process

    Terminal window
    git clone <repository-url>
    cd umbrelle
    pnpm install
    # Configure environment variables
    pnpm run build

  3. Code Style

    • ESLint configuration enforces code standards
    • Maximum warnings: 0 (strict enforcement)
    • TypeScript strict mode enabled
    • Follow existing patterns in the codebase

Contribution Guidelines

Section titled “Contribution Guidelines”

Please refer to CONTRIBUTING.md for detailed contribution guidelines including:

  • Code of conduct (CODE_OF_CONDUCT.md)
  • Pull request process
  • Issue reporting
  • Development workflow

Code Quality Standards

Section titled “Code Quality Standards”
  • All code must pass ESLint validation with zero warnings
  • TypeScript strict mode compliance required
  • Proper error handling for all async operations
  • Comprehensive JSDoc comments for public functions
  • Follow existing architectural patterns

Testing

Section titled “Testing”

Currently, the project has placeholder tests. Contributors are welcome to:

  • Implement comprehensive test coverage
  • Add unit tests for core functionality
  • Create integration tests for Discord interactions
  • Establish CI/CD testing pipeline

Contact and Support

Section titled “Contact and Support”

For development questions and support: