xmpp-bot/README.md

XMPP Bot

XMPP Bot is a tiny little bot making the link between XMPP conversations and webhooks.

User ⇄ XMPP client ⇄ XMPP Server ⇄ XMPP Bot ⇄ REST API

Key features

• Call outgoing webhook on XMPP incoming messages from user chat or group chat (Multi-user chat "MUC"),
• Send message templates (with values to apply to variables in that template) to user or room (MUC) on incoming authorized (basic or bearer) webhook.

Installation

An Ansible role is provided, but you can also use following commands:

• Install Node.js:

  curl -sL https://deb.nodesource.com/setup_10.x | bash -
  apt-get install -y nodejs
  

• Install npm:

  npm install npm@latest -g
  

• Clone repository:

  git clone https://github.com/nioc/xmpp-bot.git /usr/local/bin/xmpp-bot/
  

• Install dependency:

  cd /usr/local/bin/xmpp-bot/ && npm install --production
  

• Create run user (optionnal):

  useradd -r -s /bin/false xmpp-bot
  chown xmpp-bot:xmpp-bot /usr/local/bin/xmpp-bot -R
  

• Set configuration in /lib/config/config.json (you can copy config.json.dist)

• Add systemd service from model:

  cp docs/xmpp-bot.service /etc/systemd/system/xmpp-bot.service
  

• Update systemd:

  systemctl daemon-reload
  

• Start service:

  systemctl start xmpp-bot
  

• Start service at boot:

  systemctl enable xmpp-bot
  

• Add fail2ban filter from model (optionnal):

  cp docs/xmpp-bot.conf /etc/fail2ban/filter.d/xmpp-bot.conf
  

  Add the jail (/etc/fail2ban/jail.local):

  [xmpp-bot]
  enabled  = true
  port     = http,https
  filter   = xmpp-bot
  logpath  = /var/log/xmpp-bot/webhook.log
  maxretry = 3
  bantime  = 21600 ; 6 hours
  

Configuration

Logger

• level log4js level (all < trace < debug < info < warn < error < fatal < mark < off)
• file, console and stdout define log appenders (see log4js doc)

Webhooks listener

• path and port define the listening endpoint
• ssl define key and certificat location and port used for exposing in https, make sure that user of the process is allowed to read cert
• users is an array of user/password for basic authentication
• accessLog define the listener logger

XMPP Server

• service and domain define XMPP server
• username and password define XMPP "bot" user credentials
• rooms list rooms (and optionnal password) where bot will listen

Incoming webhooks (list)

• path is the webhook key:a POST request on this path will trigger corresponding action
• action among enumeration:

  • send_xmpp_message will send message (message in request body) to destination (from request body) ; if destination is found in config.xmppServer.rooms array, message will send as a groupchat). Request exemple:

    POST /webhooks/w1 HTTP/1.1
    Host: domain.ltd:8000
    Content-Type: application/json
    Authorization: Basic dXNlcjE6cGFzczE=
    Content-Length: 70
    
    {
        "destination":"me@domain.ltd",
        "message":"Hi, there something wrong."
    }
    

  • send_xmpp_template will send template with merged variables (using JMESPath) to destination (user or room if type set to chat or groupchat)

XMPP hooks (list)

• room is the XMPP hook key: an incoming groupchat (or chat) from this room (or this user) will trigger corresponding action
• action among enumeration:
  • outgoing_webhook will execute a request to corresponding webhook with args as webhook code

FAQ

• XMPP server is using a self signed certificate, how can i run service? You can allow insecure TLS connections and HTTPS requests by adding Environment=NODE_TLS_REJECT_UNAUTHORIZED=0 in /usr/lib/systemd/system/xmpp-bot.service.

Credits

• Nioc - Initial work

See also the list of contributors to this project.

This project is powered by the following components:

• xmpp.js (ISC)
• express (MIT)
• body-parser (MIT)
• express-basic-auth (MIT)
• morgan (MIT)
• jmespath.js (Apache-2.0)
• request (Apache-2.0)
• node-cleanup (MIT)
• log4js-node (Apache-2.0)

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details