Mittens

Middleware for your Wisp server.

Features

• Logging
• Filtering (Apply restrictions even if the Wisp server doesn't support them)
• Anti DDoS (WiP!!!)
• Plugins (Configurable middleware)

Why Mittens?

Mittens allows developers or sysadmins to easily secure and monitor traffic sent over their Wisp server. This can be beneficial for easily monitor traffic sent over your Wisp server, blocking malicious traffic, preventing exploits, and more!

Why Not?

Mittens is written in NodeJS. This means performance will unfortunately suffer. While I have not run any benchmarking tools like WispMark, it is fairly safe to assume that the traffic sent over Mittens will be quite slower then the Wisp server, as NodeJS is pretty slow compared to languages like Rust, which, for example, epoxy uses.

Plugin System

See tests/api.ts

Configuration

How to configure Mittens

CLI

See config.example.jsonc

Programmable

import { Mittens, generateConfig } from "@scaratech/mittens";

const mit = new Mittens(generateConfig({
    host: "ws://localhost:3000/wisp/", // Wisp server
    bind: { // Server configuration
        host: "0.0.0.0", // Interface to bind to
        port: 3000 // Port to bind to
    },
    logging: { // Logging configuration
        enabled: true, // Enable logging
        log_ip: true, // Log client IP addresses
        trust_proxy: true, // Trust reverse proxies
        proxy_header: "X-Forwarded-For", // Header to get client IP from (X-Forwarded-For, X-Real-IP, CF-Connecting-IP)
        log_type: "log", // Log file format (log, json)
        log_dir: "./logs", // Directory to store log files
        log_actions: [ // Actions that get logged
            "connection", // Connections & disconnections to Wisp server
            "error", // Client & server errors (CLOSE packet)
            "CONNECT", // CONNECT packets
            "DATA", // DATA packets
            "blocked", // Client tried to access something blocked by the filter rules
            "INFO", // INFO packets
            "passwordAuth", // Password authentication attempts
            "keyAuth", // Key authentication attempts
            "*" // Log ALL traffic, actions, raw packets, parsed packets, complete request objects, and more
        ]
    },
    wispguard: { // Wispguard configuration
        enabled: true, // Enable wispguard
        ip: { // IP configuration
            type: 'whitelist', // IP filtering type (whitelist, blackist)
            list: ['::ffff:127.0.0.1'] // List of IPs
        },
        ua: { // UA (user agent) configuration
            type: 'whitelist', // UA filtering type (whitelist, blacklist)
            list: ['Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36'] // List of UAs
        }
    },
    filtering: { // Filter configuration
        enabled: true, // Enable filtering
        tcp: true, // Allow TCP connections
        udp: false, // Allow UDP connections
        ports: {
            type: "whitelist", // Port filtering type (whitelist, blacklist)
            list: [80, 443, [8000, 8100]] // List of ports and/or port ranges
        },
        hosts: { // Hosts configuration
            type: "blacklist", // Host filtering type (whitelist, blacklist)
            list: ["scaratek.dev", "*.holo.cat"] // List of hostnames (wildcard support)
        },
        direct_ip: false, // Allow direct IP connections (E.g. 152.53.90.161)
        private_ip: false, // Allow private IP connections (E.g. 192.168.0.1)
        loopback_ip: false // Allow loopback IP connections (E.g. localhost, 0.0.0.0, 127.0.0.1, etc.)
    }
}));

CLI

Easily spin up a Mittens server

[!IMPORTANT] The source code for the mittens-cli is located in a different repository!

$ pnpm dlx @scaratech/mittens-cli -c ./path_to_config.json

Credit

• Mittens is maintained and developed by me and is licensed under the AGPLv3 license.
• mittens-cli was also developed by me and is also licensed under the AGPLv3 license.
• Mittens is middleware for any existing server implementation of the Wisp protocol. Wisp is licensed under the CC-BY-4.0 license and was mostly written by ading2210.