onesystems/tools repository overview

⁠OneSystems Tools (Docker)

SMTP ingress (Echo Mail with SPF, DKIM, DMARC analysis), an optional web test UI for one-shot recipient addresses, and IT tools (DNS, GeoIP, TLS/certs, mail generators, and more) in a single Alpine-based Python image.

• Image: onesystems/tools⁠ (latest, version tags e.g. 1.3.0)
• Entrypoint: python -m onesystems_tools (legacy: python echo_maild.py)
• Compose examples: docker-compose.yml (profiles bridge and host-tls)

Designed for public exposure: SSRF-filtered outbound targets, HTTP rate limits, CSP with per-request nonces, trusted-proxy checks, non-root process, no open SMTP relay by default.

⁠Features

• SMTP listener (aiosmtpd) for configured addresses — classic Echo reply and/or test-<token>@… web flow
• SPF, DKIM, DMARC evaluation (DNS-based; optional fixed resolvers via TOOLS_DNS_SERVERS)
• Optional HTTP UI (Uvicorn + FastAPI) — dashboard, tool forms, JSON API under /api/tools/…
• IT tools: DNS, PTR, subdomains, ping/traceroute, WHOIS/RDAP, GeoIP (local MaxMind MMDB), TLS/cert helpers, mail auth (SPF/DMARC/DKIM), record generators (SPF / DMARC / MTA-STS / TLS-RPT under /generators), client Autoconfig (SRV + Mozilla XML), Exchange Server Check, Base64/password/hashes, optional LibreSpeed under /speedtest (gated), and more
• Static assets under files/ (Bootstrap 5.3.3, no CDN required)
• Optional Matomo (TOOLS_MATOMO_*) and ad slots (TOOLS_WEB_ADS_*) for trusted HTML only
• Hardening: SSRF filter, HTTP rate limits, CSP nonces, HSTS, no-new-privileges, non-root runtime

⁠Quick start

⁠Pull from Docker Hub

docker pull onesystems/tools:latest

Minimal Compose (bridge / port mapping):

services:
  tools:
    image: onesystems/tools:latest
    restart: unless-stopped
    ports:
      - "25:8025"
      # With TOOLS_WEB_ENABLED=true:
      # - "8080:8080"
    environment:
      TOOLS_MAIL_ADDRESSES: [email protected]
      TOOLS_MAIL_HOSTNAME: tools.example.com
      # TOOLS_WEB_ENABLED: "true"
      # WEB_LISTEN_PORT: "8080"

⁠Compose profiles (repo docker-compose.yml)

Pick exactly one profile:

• bridge — host 25 → container 8025 (classic mapping)
• host-tls — host network + Caddy (HTTPS) + web on 127.0.0.1:8080 + optional LibreSpeed

docker compose --profile bridge up -d
# or
cp .env.example .env   # set secrets if using LibreSpeed
docker compose --profile host-tls up -d

Do not run both profiles on the same host if they compete for port 25.

⁠Layout (source / self-build)

src/onesystems_tools/
  __main__.py          # python -m onesystems_tools
  config.py / envutil.py
  smtp/                # server, security, analysis, outbound
  web/                 # FastAPI UI, store, middleware
  api/                 # /api/tools JSON router
  services/            # net_guard, rate_limit, geoip, toolkits
echo_maild.py          # thin legacy wrapper → same main()
files/                 # static assets (css/js/vendor/logo)
speedtest/             # LibreSpeed sidecar Dockerfile + branding
caddy/                 # Caddyfile for host-tls profile
tests/                 # pytest

Env vars use the TOOLS_* / SMTP_* / WEB_* prefixes (ECHO_* / ECHO_TOOLS_* are no longer read).

⁠Build (optional)

Multi-arch example (set VERSION so the image labels / TOOLS_VERSION match the release):

docker buildx create --name multiarch --driver docker-container --use
docker buildx inspect --bootstrap
docker run --privileged --rm tonistiigi/binfmt --install all

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --push \
  --build-arg VERSION="1.3.0" \
  --build-arg BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --tag onesystems/tools:1.3.0 \
  --tag onesystems/tools:latest \
  .

If VERSION is omitted, the image resolves the version from pyproject.toml at build time (never leaves a bare dev placeholder).

⁠Configuration overview

⁠HTTP / Web UI (onesystems_tools.web)

Static files are served under /web-assets/…. Mounting ./files:/app/files replaces the entire directory — include css/, js/, vendor/ or mount single files only.

⁠HTTP server (Uvicorn)

⁠Web test storage

⁠SMTP ingress

⁠Mail record generators

UI under /generators (SPF wizard, DMARC, MTA-STS, TLS-RPT). Live preview via /api/tools/mail-generate and related load endpoints. No extra env vars required beyond TOOLS_IT_TOOLS_ENABLED.

⁠IT tools API

⁠SSRF filter (services/net_guard)

User-supplied hosts/IPs/URLs are checked before any outbound connection (public IPs only; DNS-rebinding mitigated by connecting to the validated IP).

⁠HTTP rate limit (services/rate_limit)

Limit hits return 429 with Retry-After.

⁠LibreSpeed (/speedtest, optional)

Optional sidecar (speedtest/Dockerfile) behind Caddy + Tools forward_auth gate (host-tls profile).

• UI: /tools/speedtest (info) → /speedtest/ (LibreSpeed). Override logo with ./speedtest/branding/logo.png.
• Servers: optional ./speedtest/servers.json. Missing/empty → local backend only. With 2+ entries a server picker appears.
• Secrets: copy .env.example → .env and set TOOLS_SPEEDTEST_TICKET_SECRET / TOOLS_SPEEDTEST_STATS_PASSWORD.
• Mount a MaxMind Country/City MMDB and point TOOLS_GEOIP_DB / the Compose volume at your host path.

⁠Web test flow

With TOOLS_WEB_ENABLED=true and HTTP exposed:

1. Open http://<host>:8080/<TOOLS_WEB_SUBPATH>/new (default …/echo/new) or /.
2. You receive test-<token>@<domain> from TOOLS_MAIL_ADDRESSES.
3. Send a test message to that address.
4. /w/<token> auto-refreshes; /r/<token> shows the report.

⁠Networking (NAT / Docker)

Outbound connections often use an internal source IP. Plan SPF, PTR, and optional SMTP_RELAY_* accordingly.

⁠Echo replies via Mailcow (recommended relay)

Allow sending as the Echo From address and keep SPF/DKIM aligned with Mailcow outbound.

⁠Logs

• Short connections to 127.0.0.1 at startup are normal (listener check).
• Connection lost during _handle_client() after QUIT is normal.
• Empty MAIL FROM:<> DSN-style messages are accepted without reply loops.

⁠Security

• SSRF filter on outbound targets — TOOLS_ALLOW_PRIVATE_TARGETS=true to opt out.
• DNS-rebinding mitigation — connect to the validated IP; hostname only as SNI/HELO.
• HTTP rate limit per client subnet (API vs UI buckets).
• Trusted proxies — honor X-Forwarded-* only for peers in TOOLS_TRUSTED_PROXIES.
• Security headers + CSP with per-request nonce / strict-dynamic.
• Non-root (nobody), no-new-privileges; host-tls adds NET_BIND_SERVICE for port 25.
• TOOLS_REPLY_ENABLED=false by default — avoid backscatter on public SMTP.
• Treat TOOLS_WEB_ADS_* as privileged HTML input.
• Behind a reverse proxy set both WEB_FORWARDED_ALLOW_IPS and TOOLS_TRUSTED_PROXIES.

⁠Development

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt -e . pytest
.venv/bin/pytest -q
python -m onesystems_tools

⁠Author

Michael Kleger — OneSystems GmbH

https://www.onesystems.ch⁠ · [email protected]⁠

⁠License

MIT — free for commercial and private use.