{"id":21175520,"url":"https://github.com/capcom6/censor-tg-bot","last_synced_at":"2026-02-25T02:01:35.362Z","repository":{"id":257762465,"uuid":"858683326","full_name":"capcom6/censor-tg-bot","owner":"capcom6","description":"A simple keyword-based antispam bot for Telegram, written in Go.","archived":false,"fork":false,"pushed_at":"2026-02-09T22:50:23.000Z","size":97,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-10T02:37:59.969Z","etag":null,"topics":["antispam","containerized","docker","golang","keyword-filtering","moderation-bot","telegram-bot"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/capcom6.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-09-17T10:57:45.000Z","updated_at":"2026-02-09T22:50:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"621b2b35-66b8-4260-8658-94ce90112a92","html_url":"https://github.com/capcom6/censor-tg-bot","commit_stats":null,"previous_names":["capcom6/censor-tg-bot"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/capcom6/censor-tg-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capcom6%2Fcensor-tg-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capcom6%2Fcensor-tg-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capcom6%2Fcensor-tg-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capcom6%2Fcensor-tg-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/capcom6","download_url":"https://codeload.github.com/capcom6/censor-tg-bot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capcom6%2Fcensor-tg-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29808870,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-24T22:43:48.403Z","status":"online","status_checked_at":"2026-02-25T02:00:07.329Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["antispam","containerized","docker","golang","keyword-filtering","moderation-bot","telegram-bot"],"created_at":"2024-11-20T16:59:46.676Z","updated_at":"2026-02-25T02:01:35.326Z","avatar_url":"https://github.com/capcom6.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Censor Telegram Bot\n\nA flexible, plugin-based antispam bot for Telegram, written in Go. Features a modular architecture for message filtering with built-in Prometheus metrics and Grafana dashboards.\n\n## Features\n\n- **Plugin-Based Architecture**: Extensible modular design for custom filtering logic\n- **Built-in Plugins**:\n  - **Keyword**: Block messages containing blacklisted keywords\n  - **Rate Limit**: Prevent spam by limiting messages per user per time window\n  - **Regex**: Block messages matching regex patterns\n- **Execution Strategies**: Sequential or parallel plugin execution\n- **Prometheus Metrics**: Track plugin performance and message filtering statistics\n- **Grafana Dashboards**: Pre-configured dashboards for monitoring\n- **Automatic User Banning**: Ban users after threshold violations\n- **Admin Notifications**: Real-time alerts for blocked messages\n- **Dockerized Deployment**: Easy containerized deployment\n\n## Prerequisites\n\n- Go 1.24+ (for building from source)\n- Docker (for containerized deployment)\n- Prometheus \u0026 Grafana (optional, for monitoring)\n\n## Configuration\n\n### Basic Configuration\n\nThe app uses environment variables or a configuration file. Create a `.env` file:\n\n```sh\n# Telegram Bot Settings\nTELEGRAM__TOKEN=xxx:yyyyy              # Bot token from @BotFather\nBOT__ADMIN_ID=123456789                # Your Telegram user ID\nBOT__BAN_THRESHOLD=3                   # Number of violations before ban\n\n# Censor Settings\nCENSOR__STRATEGY=sequential            # sequential|parallel\nCENSOR__TIMEOUT=30s                    # Plugin execution timeout\nCENSOR__ENABLED_ONLY=true              # Only run enabled plugins\n\n# Storage (for violation tracking)\nSTORAGE__URL=memory://storage?ttl=5m   # In-memory storage with 5-minute TTL\n\n# HTTP Server\nHTTP__ADDRESS=127.0.0.1:3000           # Metrics endpoint address\n```\n\n### Plugin Configuration\n\nConfigure plugins using environment variables or YAML configuration:\n\n#### Environment Variables (Deprecated, Keyword only)\n```sh\nCENSOR__BLACKLIST='spam,scam,phishing' # Comma-separated blacklist\n```\n\n#### YAML Configuration (Recommended)\nCreate a `config.yml` file:\n\n```yaml\ncensor:\n  strategy: sequential\n  timeout: 30s\n  enabled_only: true\n  plugins:\n    keyword:\n      enabled: true\n      priority: 10\n      config:\n        blacklist:\n          - spam\n          - scam\n          - phishing\n    \n    ratelimit:\n      enabled: true\n      priority: 5\n      config:\n        max_messages: 5\n        window: \"1m\"\n    \n    regex:\n      enabled: false\n      priority: 20\n      config:\n        patterns:\n          - 'https?://[\\w\\-\\.]+\\.xyz'  # Block .xyz domains\n          - '\\b\\d{16}\\b'               # Block credit card numbers\n```\n\nPass `CONFIG_PATH` environment variable to specify a path to a YAML configuration file.\n\n## Plugin Reference\n\n### Keyword Plugin\nBlocks messages containing blacklisted keywords with case-insensitive matching and Unicode normalization.\n\n**Configuration:**\n```yaml\nkeyword:\n  enabled: true\n  priority: 10  # Lower number = earlier execution\n  config:\n    blacklist:\n      - spam\n      - scam\n      - phishing\n```\n\n**Use Cases:**\n- Blocking profanity\n- Filtering promotional keywords\n- Preventing specific terminology\n\n---\n\n### Rate Limit Plugin\nPrevents spam by limiting the number of messages a user can send within a time window.\n\n**Configuration:**\n```yaml\nratelimit:\n  enabled: true\n  priority: 5   # Execute early to short-circuit expensive plugins\n  config:\n    max_messages: 5\n    window: \"1m\"  # 1 minute window\n```\n\n**Use Cases:**\n- Preventing message flooding\n- Limiting bot abuse\n- Protecting against rapid-fire spam\n\n---\n\n### Regex Plugin\nBlocks messages matching regular expression patterns.\n\n**Configuration:**\n```yaml\nregex:\n  enabled: true\n  priority: 20  # Execute after simpler checks\n  config:\n    patterns:\n      - 'https?://bit\\.ly/\\w+'  # Block shortened URLs\n      - '\\b[A-Z]{5,}\\b'         # Block excessive caps\n```\n\n**Use Cases:**\n- Blocking URL patterns\n- Detecting credit card numbers\n- Filtering complex patterns\n\n---\n\n### Forwarded Plugin\nBlocks forwarded messages from non-exception sources, allowing only messages from specified user IDs and chat IDs.\n\n**Configuration:**\n```yaml\nforwarded:\n  enabled: true\n  priority: 15  # Execute after rate limiting and keyword, before regex\n  config:\n    allowed_user_ids:\n      - 123456789\n      - 987654321\n    allowed_chat_ids:\n      - -1001234567890\n```\n\n**Use Cases:**\n- Preventing unauthorized message forwarding in groups\n- Controlling content flow from specific channels/chats\n- Implementing content source restrictions\n\n---\n\n### LLM Plugin\nBlocks messages containing potentially inappropriate content, spam, or violations by analyzing the message with an external large language model (LLM) API.\n\nIncludes an optional caching feature to reduce LLM API call volume, lower operational costs, and improve response times by storing valid responses for repeated messages (LRU eviction triggers when cache_max_size is exceeded).\n\n**Configuration:**\n```yaml\nllm:\n  enabled: true\n  priority: 200\n  config:\n    api_key: \"\"               # Required API key for LLM service\n    model: \"nvidia/nemotron-nano-9b-v2:free\"  # LLM model to use\n    confidence_threshold: 0.8 # Threshold for blocking (0.0-1.0)\n    timeout: 30s              # API call timeout\n    prompt: \"Analyze the following message for inappropriate content, spam, or violations. Respond with JSON: {\\\"inappropriate\\\": boolean, \\\"confidence\\\": float, \\\"reason\\\": string}\"\n    temperature: 0.1          # Temperature for LLM sampling\n    cache_enabled: true       # Toggle cache functionality (default: true)\n    cache_ttl: \"1h\"           # Cache entry TTL (valid range: 1m-24h, default: 1h)\n    cache_max_size: 1000      # Max cached entries (triggers LRU eviction, default: 1000)\n```\n\n**Use Cases:**\n- Filtering malicious or phishing attempts via natural language patterns\n- Detecting subtle spam that evades keyword matching\n- Handling context-sensitive content that requires semantic understanding\n- Multi-language message moderation\n\n---\n\n## Execution Strategies\n\nThe censor service supports two execution strategies that determine how plugins process messages:\n\n### Sequential (Default)\n\nPlugins execute in priority order (lower priority number = earlier execution), stopping at the first block decision.\n\n**Best for:** Most use cases, efficient resource usage\n\n**Behavior:**\n\n- Plugins are sorted by priority\n- Execution stops when the first plugin returns `ActionBlock`\n- Subsequent plugins are skipped after a block decision\n- Ideal for short-circuiting expensive operations\n\n```yaml\ncensor:\n  strategy: sequential\n```\n\n### Parallel\n\nAll plugins execute concurrently, with results aggregated after all complete.\n\n**Best for:** When all plugins must evaluate every message, high-performance scenarios\n\n**Behavior:**\n\n- All enabled plugins run simultaneously\n- Results are collected and aggregated\n- A block decision from any plugin results in message blocking\n- Better throughput but higher resource usage\n\n```yaml\ncensor:\n  strategy: parallel\n```\n\n## Running\n\n### Docker (Recommended)\n\n```sh\ndocker run -d --name censor-tg-bot \\\n  --env-file .env \\\n  ghcr.io/capcom6/censor-tg-bot\n```\n\n### Docker Compose\n\n```yaml\nservices:\n  bot:\n    image: ghcr.io/capcom6/censor-tg-bot\n    env_file: .env\n    restart: unless-stopped\n```\n\n### From Source\n\n```sh\n# Clone repository\ngit clone https://github.com/capcom6/censor-tg-bot.git\ncd censor-tg-bot\n\n# Build\ngo build -o censor-tg-bot .\n\n# Run\n./censor-tg-bot\n```\n\n## Monitoring\n\n### Prometheus Metrics\n\nThe bot exposes Prometheus metrics on `http://localhost:3000/metrics`:\n\n**Available Metrics:**\n- `censor_plugin_evaluations_total` - Plugin evaluation counts by action\n- `censor_plugin_duration_seconds` - Plugin execution duration histogram\n- `censor_plugin_errors_total` - Plugin error counts\n- `bot_processed_actions_total` - Bot action counts (deletions, bans, notifications)\n\n### Grafana Dashboard\n\nImport the pre-configured dashboard from [`deployments/grafana/dashboard.json`](deployments/grafana/dashboard.json):\n\n1. Open Grafana\n2. Go to Dashboards → Import\n3. Upload `deployments/grafana/dashboard.json`\n4. Select your Prometheus datasource\n\n**Dashboard Includes:**\n- Bot action distribution\n- Message filter rate over time\n- Plugin performance metrics\n- HTTP request statistics\n\n### Prometheus Alerts\n\nConfigure alerts using [`deployments/prometheus/alerts.yml`](deployments/prometheus/alerts.yml):\n\n**Available Alerts:**\n\n**Bot Alerts:**\n- `HighBotActionFailureRate` - Triggered when \u003e10% of bot actions fail over 5 minutes\n- `BotActionFailures` - Critical alert when \u003e5 bot actions fail in 5 minutes\n\n**Plugin Alerts:**\n- `HighPluginEvaluationFailureRate` - Warning when \u003e10% of plugin evaluations fail\n- `HighPluginEvaluationFailures` - Critical when \u003e5 plugin evaluations fail in 5 minutes\n\n**Server Alerts:**\n- `HighHTTPErrorRate` - Warning when \u003e5% of HTTP requests return 5xx errors\n- `HighHTTPRequestLatency` - Warning when 95th percentile latency exceeds 1 second\n- `HighHTTPThroughput` - Warning when request rate exceeds 100 requests/second\n\n## Creating Custom Plugins\n\nThe plugin architecture allows you to create custom filtering logic by implementing the `Plugin` interface. The details can be found in the [Creating Custom Plugins](docs/creating-custom-plugins.md) section of the documentation.\n\n## Troubleshooting\n\n### Plugin Timeout Errors\n**Symptom:** Logs show \"timeout\" errors during plugin evaluation\n\n**Solution:**\n- Increase `CENSOR__TIMEOUT` value\n- Optimize slow plugins\n- Use `parallel` strategy instead of `sequential`\n\n### High Memory Usage\n**Symptom:** Bot consumes excessive memory\n\n**Solution:**\n- Reduce `STORAGE__URL` TTL value\n- Enable rate limit plugin cleanup\n- Monitor with `prometheus` metrics\n\n### Messages Not Being Filtered\n**Symptom:** Blacklisted messages are not blocked\n\n**Solution:**\n- Check plugin priority order\n- Review logs for plugin evaluation results\n- Ensure keywords are lowercase in configuration\n\n### Bot Not Responding\n**Symptom:** Bot doesn't process any messages\n\n**Solution:**\n- Verify `TELEGRAM__TOKEN` is correct\n- Check bot has admin permissions in the chat\n- Review logs for connection errors\n- Ensure firewall allows outbound HTTPS\n\n## Contributing\n\nContributions are welcome! Please follow these guidelines:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Implement your changes with tests\n4. Ensure all tests pass (`go test ./...`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`) \n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n### Development Setup\n\n```sh\n# Install dependencies\ngo mod download\n\n# Run tests\ngo test ./...\n\n# Run with hot reload\nair\n\n# Build\nmake build\n```\n\n## License\n\nDistributed under the Apache-2.0 license. See [LICENSE](./LICENSE) for more information.\n\n## Acknowledgments\n\n- [telegram-bot-api](https://github.com/go-telegram-bot-api/telegram-bot-api) - Telegram Bot API wrapper\n- [fx](https://uber-go.github.io/fx/) - Dependency injection framework\n- [Prometheus](https://prometheus.io/) - Monitoring and metrics\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapcom6%2Fcensor-tg-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcapcom6%2Fcensor-tg-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapcom6%2Fcensor-tg-bot/lists"}