ovh-voip-spam-filter 0.2.0

Reconcile your OVH SIP incoming blacklist with the Saracroche community list — Docker image + Python CLI.

ovh-voip-spam-filter

🇬🇧 English · 🇫🇷 Français

Reconcile your OVH SIP incoming blacklist with Saracroche, the community-driven blocklist of ~16 million French telemarketing numbers.

📖 Full documentation: raedkit.github.io/ovh-voip-spam-filter

---

[!WARNING] Use the API (sync), not the CSV. The OVH Manager's CSV import fails past ~80 entries (empirically confirmed). This project exists to push the same data through the OVH API one prefix at a time, throttled and idempotent. The CSV mode is kept for completeness but is not the recommended path.

Quickstart

docker run --rm \
  -e OVH_APPLICATION_KEY=... \
  -e OVH_APPLICATION_SECRET=... \
  -e OVH_CONSUMER_KEY=... \
  -e OVH_BILLING_ACCOUNT=... \
  -e OVH_SERVICE_NAME=... \
  ghcr.io/raedkit/ovh-voip-spam-filter:latest sync

Or via PyPI:

pip install ovh-voip-spam-filter
ovh-voip-spam-filter sync

Generate an OVH token with this pre-filled URL (minimum scopes pre-checked).

Full setup walkthrough: docs/quickstart.

Why this exists

OVH's Manager UI offers a CSV import for the incoming blacklist, but it POSTs each row internally without rate-limiting. The Saracroche list is 643 prefixes — the import returns HTTP 429 after ~80. This tool does the same job correctly: signed API requests, client-side throttle, exponential backoff on 429, auto-adaptation if OVH tightens the quota. One bootstrap run takes ~13 minutes; subsequent runs are idempotent and take seconds.

How it works

            ┌────────────────────────────┐
            │  Saracroche live API       │
            │  (~643 block-only prefixes)│
            └─────────────┬──────────────┘
                          │  fallback when down
                          ▼
            ┌────────────────────────────┐
            │  Hard-coded ARCEP fallback │
            │  (23 prefixes, additive)   │
            └─────────────┬──────────────┘
                          ▼
            ┌────────────────────────────┐
            │  Diff vs current OVH state │
            │  (GET-first reconciliation)│
            └─────────────┬──────────────┘
                          ▼
            ┌────────────────────────────┐
            │  Signed OVH API push       │
            │  (throttled, 429-aware)    │
            └────────────────────────────┘

• Normal mode (Saracroche reachable) — strict sync: adds missing prefixes, removes the ones Saracroche removed.
• Degraded mode (Saracroche unreachable) — uses the hard-coded ARCEP fallback, additive only, never deletes. Anti-regression guarantee.

Details: reconciliation semantics.

Acknowledgments

🙏 This project would not exist without Saracroche by Camille Bouvat.

Saracroche is an open-source community blocklist of ~16 million French telemarketing and spam numbers, maintained solo and pro bono since 2020. We consume the french-list-arcep-operators endpoint as our primary source of truth, with no caching on the redistribution side — the freshness you get is whatever Saracroche has right now.

If this tool saved you from a spam call, please support Camille:

• 💛 Liberapay (preferred)
• 💳 Stripe / one-shot
• 🐙 GitHub Sponsors

Saracroche source:

• 📱 Apps: iOS · Android
• 🦊 Code: Codeberg (android) · GitHub (legacy)

Documentation

Full docs at raedkit.github.io/ovh-voip-spam-filter:

• Quickstart — token generation, discover, sync
• Configuration — env vars, CLI flags, Kubernetes
• Docker — image details, multi-arch, CronJob sketch
• PyPI — install + library usage
• Reconciliation — normal vs degraded mode
• API reference
• Roadmap

Contributing

PRs welcome. See CONTRIBUTING.md for setup and the PR checklist. By participating you agree to the Code of Conduct.

Security issues: see SECURITY.md. Please don't open public issues for credential-handling bugs.

License

GPL-3.0-or-later — matches Saracroche.