Endpoint Monitor
A typed FastAPI service that stores endpoint monitors in concurrency-safe, process-local memory and checks them on demand with bounded timeouts, redirect validation, DNS-based SSRF policy, latency/status updates, and redacted JSON logs. There is intentionally no authentication.
Layout
SPEC.md: normative API, status, security, logging, and lifecycle contractapp/: configuration, models, locked store, SSRF policy, checker, and APItests/: API/unit tests with mocked outbound HTTP and DNSDockerfile,compose.yaml: single-worker container packaging
Local development
Requires Python 3.12.
python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
ruff format --check .
ruff check .
mypy app
pytest -q
uvicorn app.main:app --reload
OpenAPI is at http://localhost:8000/docs.
Examples
curl -s http://localhost:8000/healthz
curl -s http://localhost:8000/readyz
curl -s -X POST http://localhost:8000/monitors -H 'content-type: application/json' \
-d '{"name":"example","url":"https://example.com/?token=secret","timeout_seconds":3}'
curl -s -X POST http://localhost:8000/monitors/UUID/check
curl -s http://localhost:8000/monitors/UUID/status
CRUD also supports GET /monitors, GET|PUT|DELETE /monitors/{id}.
Configuration
All settings are startup-validated. Invalid values prevent startup.
| Environment | Default | Constraint |
|---|---|---|
MONITOR_REQUEST_TIMEOUT_SECONDS |
5 | >0, <=30 |
MONITOR_MAX_REDIRECTS |
5 | 0..10 |
MONITOR_MAX_MONITORS |
1000 | 1..100000 |
MONITOR_LOG_LEVEL |
INFO | standard uppercase level |
Per-monitor timeout overrides the default. Query strings are emitted only as ?REDACTED.
Container
docker build -t endpoint-monitor .
docker run --rm -p 8000:8000 endpoint-monitor
# or: docker compose up --build
curl http://localhost:8000/healthz
The image runs as a non-root user with exactly one Uvicorn worker.
Verification
Run the lint, format, type, and test commands above, then:
docker build -t endpoint-monitor .
docker run -d --rm --name endpoint-monitor -p 8000:8000 endpoint-monitor
curl --fail http://localhost:8000/healthz
curl --fail http://localhost:8000/readyz
docker stop endpoint-monitor
Security and operational limitations
DNS and every redirect target are checked and non-global addresses are denied. This policy is defense in depth, not a substitute for egress firewalling: the standard HTTP transport performs its own DNS lookup, so hostile DNS rebinding between policy resolution and connection remains possible. Enforce outbound network policy in production.
Data is ephemeral and isolated per process. Restarting loses all monitors; multiple workers produce divergent state. There is no scheduler, persistence, cross-process readiness dependency, TLS termination, rate limiting, or authentication. Deploy one worker, place behind appropriate controls, and use persistent shared storage before scaling.