checkers: load external checker plugins from .so files

Scan -plugins-directory paths at startup, open each .so via plugin.Open,
look up the NewCheckerPlugin symbol from checker-sdk-go, and register the
returned definition and observation provider in the global checker
registries. A pluginLoader indirection keeps the door open for future
plugin kinds.

docs/plugins/checker-plugin.md

@@ -0,0 +1,149 @@
+# Building a happyDomain Checker Plugin
+
+This page documents how to ship a **checker** as an in-process Go plugin
+that happyDomain loads at startup. Checker plugins extend happyDomain with
+automated diagnostics on zones, domains, services or users.
+
+If you've never built a happyDomain plugin before, read
+[`checker-dummy`](https://git.happydns.org/checker-dummy) first; it is the
+reference implementation that this page mirrors.
+
+> ⚠️ **Security note.** A `.so` plugin is loaded into the happyDomain process
+> and runs with the same privileges. happyDomain refuses to load plugins from
+> a directory that is group- or world-writable; keep your plugin directory
+> owned and writable only by the happyDomain user.
+
+---
+
+## What a checker plugin must export
+
+happyDomain's loader looks for a single exported symbol named
+`NewCheckerPlugin` with this exact signature:
+
+```go
+func NewCheckerPlugin() (
+    *checker.CheckerDefinition,
+    checker.ObservationProvider,
+    error,
+)
+```
+
+where `checker` is `git.happydns.org/checker-sdk-go/checker` (see
+[Licensing](#licensing) below for why the SDK lives in a separate module).
+
+- `*CheckerDefinition` describes the checker: ID, name, version, options
+  documentation, rules, optional aggregator, scheduling interval, and
+  whether the checker exposes HTML reports or metrics. The `ID` field is
+  the persistent key: pick something stable and namespaced
+  (`com.example.dnssec-freshness`, not `dnssec`).
+- `ObservationProvider` is the data-collection half of the checker. It
+  exposes a `Key()` (the observation key the rules will look up) and a
+  `Collect(ctx, opts)` method that returns the raw observation payload.
+  happyDomain serialises the result to JSON and caches it per
+  `ObservationContext`.
+- Return a non-nil `error` if your plugin cannot initialise (missing
+  environment variable, broken cgo dependency, …); the host will log it and
+  skip the file rather than aborting startup.
+
+### Registration and collisions
+
+The loader calls `RegisterExternalizableChecker` and
+`RegisterObservationProvider` from the SDK registry. Pick globally unique
+identifiers: if your checker ID or observation key collides with a built-in
+or another plugin, the duplicate is ignored.
+
+The same `.so` may export both `NewCheckerPlugin` and (e.g.)
+`NewProviderPlugin`. The loader runs every known plugin loader against
+every file, so a single binary can ship a checker, a provider and a service
+at once.
+
+---
+
+## Minimal example
+
+```go
+// Command plugin is the happyDomain plugin entrypoint for the dummy checker.
+//
+// Build with:
+//   go build -buildmode=plugin -o checker-dummy.so ./plugin
+package main
+
+import (
+    "context"
+
+    sdk "git.happydns.org/checker-sdk-go/checker"
+)
+
+type dummyProvider struct{}
+
+func (dummyProvider) Key() sdk.ObservationKey { return "dummy.observation" }
+
+func (dummyProvider) Collect(ctx context.Context, opts sdk.CheckerOptions) (any, error) {
+    return map[string]string{"hello": "world"}, nil
+}
+
+// NewCheckerPlugin is the symbol resolved by happyDomain at startup.
+func NewCheckerPlugin() (*sdk.CheckerDefinition, sdk.ObservationProvider, error) {
+    def := &sdk.CheckerDefinition{
+        ID:              "com.example.dummy",
+        Name:            "Dummy checker",
+        Version:         "0.1.0",
+        ObservationKeys: []sdk.ObservationKey{"dummy.observation"},
+        // Add Rules / Aggregator / Options here in a real plugin.
+    }
+    return def, dummyProvider{}, nil
+}
+```
+
+Build and deploy:
+
+```bash
+go build -buildmode=plugin -o checker-dummy.so ./plugin
+sudo install -m 0644 -o happydomain checker-dummy.so /var/lib/happydomain/plugins/
+sudo systemctl restart happydomain
+```
+
+happyDomain will log:
+
+```
+Plugin com.example.dummy (.../checker-dummy.so) loaded
+```
+
+---
+
+## Build constraints and platform support
+
+Go's `plugin` package is unforgiving:
+
+- The plugin **must be built with the same Go version** as happyDomain
+  itself, including the same toolchain patch level.
+- It **must use the same versions of every shared dependency**. Vendor the
+  exact module versions happyDomain ships, or pin them in your `go.mod`
+  with `replace` directives.
+- `CGO_ENABLED=1` is required.
+- `GOOS`/`GOARCH` must match the host binary.
+
+If any of these don't match, `plugin.Open` will fail with a (sometimes
+cryptic) error like *"plugin was built with a different version of package
+…"*. The host will log it and skip the file.
+
+Go's `plugin` package only works on **linux**, **darwin** and **freebsd**.
+On other platforms (Windows, plan9, …) happyDomain is built without plugin
+support and `--plugins-directory` is silently ignored apart from a warning
+log line at startup.
+
+---
+
+## Licensing
+
+Checker plugins import only `git.happydns.org/checker-sdk-go/checker`,
+which is licensed under **Apache-2.0**. This is intentional: the
+checker SDK is a small, stable public API for third-party checkers,
+deliberately split out of the AGPL-3.0 happyDomain core so that
+permissively-licensed checker plugins are possible.
+
+You may therefore distribute your checker `.so` under any license compatible
+with Apache-2.0. Note that this only covers checker plugins; provider and
+service plugins still link against AGPL code and remain subject to the
+AGPL-3.0 reciprocity rules described in their respective documentation
+([provider](provider-plugin.md), [service](service-plugin.md)).

internal/app/app.go

@@ -93,6 +93,9 @@ func NewApp(cfg *happydns.Options) *App {
 	app.initStorageEngine()
 	app.initNewsletter()
 	app.initInsights()
+	if err := app.initPlugins(); err != nil {
+		log.Fatalf("Plugin initialization error: %s", err)
+	}
 	app.initUsecases()
 	app.initCaptcha()
 	app.setupRouter()
@@ -108,6 +111,9 @@ func NewAppWithStorage(cfg *happydns.Options, store storage.Storage) *App {
 
 	app.initMailer()
 	app.initNewsletter()
+	if err := app.initPlugins(); err != nil {
+		log.Fatalf("Plugin initialization error: %s", err)
+	}
 	app.initUsecases()
 	app.initCaptcha()
 	app.setupRouter()

internal/app/plugins.go

@@ -0,0 +1,238 @@
+// This file is part of the happyDomain (R) project.
+// Copyright (c) 2020-2026 happyDomain
+// Authors: Pierre-Olivier Mercier, et al.
+//
+// This program is offered under a commercial and under the AGPL license.
+// For commercial licensing, contact us at <contact@happydomain.org>.
+//
+// For AGPL licensing:
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+//go:build linux || darwin || freebsd
+
+package app
+
+import (
+	"errors"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"plugin"
+
+	sdk "git.happydns.org/checker-sdk-go/checker"
+	"git.happydns.org/happyDomain/internal/checker"
+)
+
+// pluginSymbols is the minimal subset of *plugin.Plugin used by the loaders.
+// It exists so that loaders can be unit-tested with a fake instead of
+// requiring a real .so file built via `go build -buildmode=plugin`.
+type pluginSymbols interface {
+	Lookup(symName string) (plugin.Symbol, error)
+}
+
+// pluginLoader attempts to find and register one specific kind of plugin
+// symbol from an already-opened .so file.
+//
+// It returns (true, nil) when the symbol was found and registration
+// succeeded, (true, err) when the symbol was found but something went wrong,
+// and (false, nil) when the symbol simply isn't present in that file (which
+// is not considered an error: a single .so may implement only a subset of
+// the known plugin types).
+type pluginLoader func(p pluginSymbols, fname string) (found bool, err error)
+
+// safeCall invokes fn while recovering from any panic raised by plugin code.
+// A panicking factory must not take the whole server down at startup; the
+// recovered value is converted to an error so the caller can log/skip the
+// offending plugin like any other failure.
+func safeCall(symbol string, fname string, fn func() error) (err error) {
+	defer func() {
+		if r := recover(); r != nil {
+			err = fmt.Errorf("plugin %q panicked in %s: %v", fname, symbol, r)
+		}
+	}()
+	return fn()
+}
+
+// pluginLoaders is the authoritative list of plugin types that happyDomain
+// knows about. To support a new plugin type, add a single entry here.
+var pluginLoaders = []pluginLoader{
+	loadCheckerPlugin,
+}
+
+// loadCheckerPlugin handles the NewCheckerPlugin symbol exported by checkers
+// built against checker-sdk-go (see ../../checker-dummy/README.md).
+func loadCheckerPlugin(p pluginSymbols, fname string) (bool, error) {
+	sym, err := p.Lookup("NewCheckerPlugin")
+	if err != nil {
+		// Symbol not present in this .so, not an error.
+		return false, nil
+	}
+
+	factory, ok := sym.(func() (*sdk.CheckerDefinition, sdk.ObservationProvider, error))
+	if !ok {
+		return true, fmt.Errorf("symbol NewCheckerPlugin has unexpected type %T", sym)
+	}
+
+	var (
+		def      *sdk.CheckerDefinition
+		provider sdk.ObservationProvider
+	)
+	if err := safeCall("NewCheckerPlugin", fname, func() error {
+		var ferr error
+		def, provider, ferr = factory()
+		return ferr
+	}); err != nil {
+		return true, err
+	}
+	if def == nil {
+		return true, fmt.Errorf("NewCheckerPlugin returned a nil CheckerDefinition")
+	}
+	if provider == nil {
+		return true, fmt.Errorf("NewCheckerPlugin returned a nil ObservationProvider")
+	}
+
+	checker.RegisterObservationProvider(provider)
+	checker.RegisterExternalizableChecker(def)
+	log.Printf("Plugin %s (%s) loaded", def.ID, fname)
+	return true, nil
+}
+
+// checkPluginDirectoryPermissions refuses to load plugins from a directory
+// that any non-owner can write to. Loading a .so file is arbitrary code
+// execution as the happyDomain process, so a world- or group-writable
+// plugin directory is treated as a fatal misconfiguration: any local user
+// (or any process sharing the group) able to drop a file there could take
+// over the server. Operators who genuinely need shared deployment should
+// stage plugins elsewhere and rsync them into a directory owned and
+// writable only by the happyDomain user.
+func checkPluginDirectoryPermissions(directory string) error {
+	// Use Lstat to detect symlinks: a symlink could be silently redirected
+	// to an attacker-controlled directory, bypassing the permission check
+	// on the original path.
+	linfo, err := os.Lstat(directory)
+	if err != nil {
+		return fmt.Errorf("unable to stat plugins directory %q: %s", directory, err)
+	}
+	if linfo.Mode()&os.ModeSymlink != 0 {
+		return fmt.Errorf("plugins directory %q is a symbolic link; refusing to follow it", directory)
+	}
+	if !linfo.IsDir() {
+		return fmt.Errorf("plugins path %q is not a directory", directory)
+	}
+	mode := linfo.Mode().Perm()
+	if mode&0o022 != 0 {
+		return fmt.Errorf("plugins directory %q is group- or world-writable (mode %#o); refusing to load plugins from it", directory, mode)
+	}
+	return nil
+}
+
+// checkPluginFilePermissions refuses to load a .so file that is group- or
+// world-writable. Even inside a properly locked-down directory, a writable
+// plugin binary could be replaced by a malicious actor sharing the group.
+// Symlinks are followed: the permission check applies to the resolved target,
+// which allows the common pattern of symlinking to versioned binaries
+// (e.g. checker-foo.so -> checker-foo-v1.2.so) for atomic upgrades.
+// The directory-level symlink ban already prevents attackers from redirecting
+// the scan root itself.
+func checkPluginFilePermissions(path string) error {
+	info, err := os.Stat(path)
+	if err != nil {
+		return fmt.Errorf("unable to stat plugin file %q: %s", path, err)
+	}
+	if !info.Mode().IsRegular() {
+		return fmt.Errorf("plugin %q is not a regular file (or resolves to a non-regular file)", path)
+	}
+	mode := info.Mode().Perm()
+	if mode&0o022 != 0 {
+		return fmt.Errorf("plugin file %q is group- or world-writable (mode %#o)", path, mode)
+	}
+	return nil
+}
+
+// initPlugins scans each directory listed in cfg.PluginsDirectories and loads
+// every .so file found as a Go plugin. A directory that cannot be read is a
+// fatal configuration error; individual plugin failures are logged and
+// skipped so that one bad .so does not prevent the others from loading.
+func (a *App) initPlugins() error {
+	for _, directory := range a.cfg.PluginsDirectories {
+		if err := checkPluginDirectoryPermissions(directory); err != nil {
+			return err
+		}
+
+		files, err := os.ReadDir(directory)
+		if err != nil {
+			return fmt.Errorf("unable to read plugins directory %q: %s", directory, err)
+		}
+
+		for _, file := range files {
+			if file.IsDir() {
+				continue
+			}
+
+			// Only attempt to load shared-object files.
+			if filepath.Ext(file.Name()) != ".so" {
+				continue
+			}
+
+			fname := filepath.Join(directory, file.Name())
+
+			if err := checkPluginFilePermissions(fname); err != nil {
+				log.Printf("Skipping plugin %q: %s", fname, err)
+				continue
+			}
+
+			if err := loadPlugin(fname); err != nil {
+				log.Printf("Unable to load plugin %q: %s", fname, err)
+			}
+		}
+	}
+
+	return nil
+}
+
+// loadPlugin opens the .so file at fname and runs every registered
+// pluginLoader against it. A loader that does not find its symbol is silently
+// skipped. If no loader recognises any symbol in the file a warning is
+// logged, because the file might be a valid plugin for a future version of
+// happyDomain. Loader errors for one plugin kind do not prevent the other
+// kinds in the same .so from being attempted: a single .so is allowed to
+// expose more than one plugin type, and a failure to register (e.g.) the
+// service half should not silently drop the checker half. All loader errors
+// encountered are joined and returned together.
+func loadPlugin(fname string) error {
+	p, err := plugin.Open(fname)
+	if err != nil {
+		return err
+	}
+
+	var (
+		anyFound bool
+		errs     []error
+	)
+	for _, loader := range pluginLoaders {
+		found, err := loader(p, fname)
+		if found {
+			anyFound = true
+		}
+		if err != nil {
+			errs = append(errs, err)
+		}
+	}
+
+	if !anyFound && len(errs) == 0 {
+		log.Printf("Warning: plugin %q exports no recognised symbols", fname)
+	}
+	return errors.Join(errs...)
+}

internal/app/plugins_checker_test.go

@@ -0,0 +1,143 @@
+// This file is part of the happyDomain (R) project.
+// Copyright (c) 2020-2026 happyDomain
+// Authors: Pierre-Olivier Mercier, et al.
+//
+// This program is offered under a commercial and under the AGPL license.
+// For commercial licensing, contact us at <contact@happydomain.org>.
+//
+// For AGPL licensing:
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+//go:build linux || darwin || freebsd
+
+package app
+
+import (
+	"context"
+	"errors"
+	"plugin"
+	"strings"
+	"testing"
+
+	sdk "git.happydns.org/checker-sdk-go/checker"
+	"git.happydns.org/happyDomain/internal/checker"
+	"git.happydns.org/happyDomain/model"
+)
+
+// dummyCheckerProvider is a minimal ObservationProvider used by the tests
+// below. It is intentionally trivial: the loader tests only care that
+// registration succeeds, not what the provider actually collects.
+type dummyCheckerProvider struct {
+	key happydns.ObservationKey
+}
+
+func (d *dummyCheckerProvider) Key() happydns.ObservationKey { return d.key }
+func (d *dummyCheckerProvider) Collect(ctx context.Context, _ happydns.CheckerOptions) (any, error) {
+	return nil, nil
+}
+
+func newDummyCheckerFactory(id string) func() (*sdk.CheckerDefinition, sdk.ObservationProvider, error) {
+	return func() (*sdk.CheckerDefinition, sdk.ObservationProvider, error) {
+		def := &sdk.CheckerDefinition{
+			ID:   id,
+			Name: "Dummy checker",
+		}
+		return def, &dummyCheckerProvider{key: happydns.ObservationKey("dummy-" + id)}, nil
+	}
+}
+
+func TestLoadCheckerPlugin_SymbolMissing(t *testing.T) {
+	found, err := loadCheckerPlugin(&fakeSymbols{}, "missing.so")
+	if found || err != nil {
+		t.Fatalf("expected (false, nil) when symbol is absent, got (%v, %v)", found, err)
+	}
+}
+
+func TestLoadCheckerPlugin_WrongSymbolType(t *testing.T) {
+	fs := &fakeSymbols{syms: map[string]plugin.Symbol{
+		"NewCheckerPlugin": 42, // not a function
+	}}
+	found, err := loadCheckerPlugin(fs, "wrongtype.so")
+	if !found || err == nil || !strings.Contains(err.Error(), "unexpected type") {
+		t.Fatalf("expected wrong-type error, got (%v, %v)", found, err)
+	}
+}
+
+func TestLoadCheckerPlugin_FactoryError(t *testing.T) {
+	factory := func() (*sdk.CheckerDefinition, sdk.ObservationProvider, error) {
+		return nil, nil, errors.New("boom")
+	}
+	fs := &fakeSymbols{syms: map[string]plugin.Symbol{"NewCheckerPlugin": factory}}
+
+	found, err := loadCheckerPlugin(fs, "factoryerr.so")
+	if !found || err == nil || !strings.Contains(err.Error(), "boom") {
+		t.Fatalf("expected factory error to propagate, got (%v, %v)", found, err)
+	}
+}
+
+func TestLoadCheckerPlugin_NilDefinition(t *testing.T) {
+	factory := func() (*sdk.CheckerDefinition, sdk.ObservationProvider, error) {
+		return nil, &dummyCheckerProvider{key: "k"}, nil
+	}
+	fs := &fakeSymbols{syms: map[string]plugin.Symbol{"NewCheckerPlugin": factory}}
+
+	found, err := loadCheckerPlugin(fs, "nildef.so")
+	if !found || err == nil || !strings.Contains(err.Error(), "nil CheckerDefinition") {
+		t.Fatalf("expected nil-definition error, got (%v, %v)", found, err)
+	}
+}
+
+func TestLoadCheckerPlugin_NilProvider(t *testing.T) {
+	factory := func() (*sdk.CheckerDefinition, sdk.ObservationProvider, error) {
+		return &sdk.CheckerDefinition{ID: "x"}, nil, nil
+	}
+	fs := &fakeSymbols{syms: map[string]plugin.Symbol{"NewCheckerPlugin": factory}}
+
+	found, err := loadCheckerPlugin(fs, "nilprov.so")
+	if !found || err == nil || !strings.Contains(err.Error(), "nil ObservationProvider") {
+		t.Fatalf("expected nil-provider error, got (%v, %v)", found, err)
+	}
+}
+
+func TestLoadCheckerPlugin_FactoryPanics(t *testing.T) {
+	factory := func() (*sdk.CheckerDefinition, sdk.ObservationProvider, error) {
+		panic("kaboom")
+	}
+	fs := &fakeSymbols{syms: map[string]plugin.Symbol{"NewCheckerPlugin": factory}}
+
+	found, err := loadCheckerPlugin(fs, "panic.so")
+	if !found || err == nil {
+		t.Fatalf("expected panic to be converted to error, got (%v, %v)", found, err)
+	}
+	if !strings.Contains(err.Error(), "panicked") || !strings.Contains(err.Error(), "kaboom") {
+		t.Errorf("expected wrapped panic error, got %v", err)
+	}
+}
+
+func TestLoadCheckerPlugin_Success(t *testing.T) {
+	factory := newDummyCheckerFactory("dummy-success")
+	fs := &fakeSymbols{syms: map[string]plugin.Symbol{"NewCheckerPlugin": factory}}
+
+	found, err := loadCheckerPlugin(fs, "first.so")
+	if !found || err != nil {
+		t.Fatalf("expected success, got (%v, %v)", found, err)
+	}
+
+	if got := checker.FindChecker("dummy-success"); got == nil {
+		t.Errorf("expected checker %q to be registered", "dummy-success")
+	}
+	if got := sdk.FindObservationProvider(happydns.ObservationKey("dummy-dummy-success")); got == nil {
+		t.Errorf("expected observation provider %q to be registered", "dummy-dummy-success")
+	}
+}

internal/app/plugins_stub.go

@@ -0,0 +1,37 @@
+// This file is part of the happyDomain (R) project.
+// Copyright (c) 2020-2026 happyDomain
+// Authors: Pierre-Olivier Mercier, et al.
+//
+// This program is offered under a commercial and under the AGPL license.
+// For commercial licensing, contact us at <contact@happydomain.org>.
+//
+// For AGPL licensing:
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+//go:build !linux && !darwin && !freebsd
+
+package app
+
+import "log"
+
+// initPlugins is a no-op on platforms where Go's plugin package is not
+// supported (Windows, plan9, …). If the operator configured plugin
+// directories anyway we log a clear warning rather than silently ignoring
+// them, so the misconfiguration is visible at startup.
+func (a *App) initPlugins() error {
+	if len(a.cfg.PluginsDirectories) > 0 {
+		log.Printf("Warning: plugin loading is not supported on this platform; ignoring %d configured plugin directories", len(a.cfg.PluginsDirectories))
+	}
+	return nil
+}

internal/app/plugins_test.go

@@ -0,0 +1,172 @@
+// This file is part of the happyDomain (R) project.
+// Copyright (c) 2020-2026 happyDomain
+// Authors: Pierre-Olivier Mercier, et al.
+//
+// This program is offered under a commercial and under the AGPL license.
+// For commercial licensing, contact us at <contact@happydomain.org>.
+//
+// For AGPL licensing:
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+//go:build linux || darwin || freebsd
+
+package app
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"plugin"
+	"testing"
+)
+
+// fakeSymbols is a pluginSymbols implementation backed by a static map. It
+// lets the loader tests exercise their behaviour without having to compile a
+// real .so file via `go build -buildmode=plugin`.
+type fakeSymbols struct {
+	syms map[string]plugin.Symbol
+}
+
+func (f *fakeSymbols) Lookup(name string) (plugin.Symbol, error) {
+	if s, ok := f.syms[name]; ok {
+		return s, nil
+	}
+	return nil, fmt.Errorf("symbol %q not found", name)
+}
+
+// TestLoadPlugin_NoRecognisedSymbols verifies that when a .so file exports
+// none of the known plugin symbols, every loader returns (false, nil), i.e.
+// the file is silently skipped rather than reported as an error. loadPlugin
+// itself logs a warning in that situation; we exercise the inner loop here
+// because the outer call requires plugin.Open and a real .so file.
+func TestLoadPlugin_NoRecognisedSymbols(t *testing.T) {
+	fs := &fakeSymbols{}
+	for _, loader := range pluginLoaders {
+		found, err := loader(fs, "empty.so")
+		if found || err != nil {
+			t.Fatalf("loader returned (%v, %v) for empty symbol set, expected (false, nil)", found, err)
+		}
+	}
+}
+
+func TestCheckPluginDirectoryPermissions(t *testing.T) {
+	dir := t.TempDir()
+
+	// A freshly-created TempDir is owner-only on every platform we run on,
+	// so this must be accepted.
+	if err := os.Chmod(dir, 0o750); err != nil {
+		t.Fatalf("chmod 0750: %v", err)
+	}
+	if err := checkPluginDirectoryPermissions(dir); err != nil {
+		t.Errorf("expected 0750 directory to be accepted, got %v", err)
+	}
+
+	// World-writable: must be refused.
+	if err := os.Chmod(dir, 0o777); err != nil {
+		t.Fatalf("chmod 0777: %v", err)
+	}
+	if err := checkPluginDirectoryPermissions(dir); err == nil {
+		t.Errorf("expected 0777 directory to be refused")
+	}
+
+	// Group-writable: must also be refused.
+	if err := os.Chmod(dir, 0o770); err != nil {
+		t.Fatalf("chmod 0770: %v", err)
+	}
+	if err := checkPluginDirectoryPermissions(dir); err == nil {
+		t.Errorf("expected 0770 directory to be refused")
+	}
+
+	// Restore permissions so t.TempDir cleanup can remove the directory.
+	_ = os.Chmod(dir, 0o700)
+
+	// Non-existent path: must be refused.
+	if err := checkPluginDirectoryPermissions(filepath.Join(dir, "does-not-exist")); err == nil {
+		t.Errorf("expected missing directory to be refused")
+	}
+
+	// Symlink to a valid directory: must be refused.
+	target := t.TempDir()
+	link := filepath.Join(dir, "symlink-plugins")
+	if err := os.Symlink(target, link); err != nil {
+		t.Fatalf("symlink: %v", err)
+	}
+	if err := checkPluginDirectoryPermissions(link); err == nil {
+		t.Errorf("expected symlink directory to be refused")
+	}
+}
+
+func TestCheckPluginFilePermissions(t *testing.T) {
+	dir := t.TempDir()
+	f := filepath.Join(dir, "test.so")
+	if err := os.WriteFile(f, []byte("fake"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	// Owner-writable, not group/world-writable: accepted.
+	if err := checkPluginFilePermissions(f); err != nil {
+		t.Errorf("expected 0644 file to be accepted, got %v", err)
+	}
+
+	// Group-writable: refused.
+	if err := os.Chmod(f, 0o664); err != nil {
+		t.Fatalf("chmod: %v", err)
+	}
+	if err := checkPluginFilePermissions(f); err == nil {
+		t.Errorf("expected 0664 file to be refused")
+	}
+
+	// World-writable: refused.
+	if err := os.Chmod(f, 0o646); err != nil {
+		t.Fatalf("chmod: %v", err)
+	}
+	if err := checkPluginFilePermissions(f); err == nil {
+		t.Errorf("expected 0646 file to be refused")
+	}
+
+	// Non-existent: refused.
+	if err := checkPluginFilePermissions(filepath.Join(dir, "nope.so")); err == nil {
+		t.Errorf("expected missing file to be refused")
+	}
+
+	// Symlink to a safe regular file: accepted (we follow the link and
+	// check the target's permissions, not the link itself).
+	regular := filepath.Join(dir, "real.so")
+	if err := os.WriteFile(regular, []byte("real"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	link := filepath.Join(dir, "link.so")
+	if err := os.Symlink(regular, link); err != nil {
+		t.Fatalf("symlink: %v", err)
+	}
+	if err := checkPluginFilePermissions(link); err != nil {
+		t.Errorf("expected symlink to safe file to be accepted, got %v", err)
+	}
+
+	// Symlink to a writable target: refused.
+	writable := filepath.Join(dir, "writable.so")
+	if err := os.WriteFile(writable, []byte("bad"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	if err := os.Chmod(writable, 0o666); err != nil {
+		t.Fatalf("chmod: %v", err)
+	}
+	linkBad := filepath.Join(dir, "link-bad.so")
+	if err := os.Symlink(writable, linkBad); err != nil {
+		t.Fatalf("symlink: %v", err)
+	}
+	if err := checkPluginFilePermissions(linkBad); err == nil {
+		t.Errorf("expected symlink to writable file to be refused")
+	}
+}

internal/config/cli.go

@@ -60,6 +60,8 @@ func declareFlags(o *happydns.Options) {
 	flag.StringVar(&o.CaptchaProvider, "captcha-provider", o.CaptchaProvider, "Captcha provider to use for bot protection (altcha, hcaptcha, recaptchav2, turnstile, or empty to disable)")
 	flag.IntVar(&o.CaptchaLoginThreshold, "captcha-login-threshold", 3, "Number of failed login attempts before captcha is required (0 = always require when provider configured)")
 
+	flag.Var(&stringSlice{&o.PluginsDirectories}, "plugins-directory", "Path to a directory containing checker plugins (.so files); may be repeated")
+
 	// Others flags are declared in some other files likes sources, storages, ... when they need specials configurations
 }
 

internal/config/custom.go

@@ -25,8 +25,27 @@ import (
 	"encoding/base64"
 	"net/mail"
 	"net/url"
+	"strings"
 )
 
+// stringSlice is a flag.Value that accumulates string values across repeated
+// invocations of the same flag (e.g. -plugins-directory a -plugins-directory b).
+type stringSlice struct {
+	Values *[]string
+}
+
+func (s *stringSlice) String() string {
+	if s.Values == nil {
+		return ""
+	}
+	return strings.Join(*s.Values, ",")
+}
+
+func (s *stringSlice) Set(value string) error {
+	*s.Values = append(*s.Values, value)
+	return nil
+}
+
 type JWTSecretKey struct {
 	Secret *[]byte
 }

model/config.go

@@ -99,6 +99,10 @@ type Options struct {
 	// CaptchaLoginThreshold is the number of consecutive login failures before captcha is required.
 	// 0 means always require captcha at login (when provider is configured).
 	CaptchaLoginThreshold int
+
+	// PluginsDirectories lists filesystem paths scanned at startup for
+	// checker plugins (.so files).
+	PluginsDirectories []string
 }
 
 // GetBaseURL returns the full url to the absolute ExternalURL, including BaseURL.