Endpoint Monitor

A small, unauthenticated FastAPI service that stores endpoint monitors in memory and checks them on demand. It validates DNS and every redirect destination against an SSRF policy, measures latency, updates status atomically, and emits structured logs with URL query data removed.

Important operating constraints

State is process-local, ephemeral, and not shared. Restarting loses all monitors. Run one worker and one replica only; multiple workers/replicas return inconsistent data. There is no authentication, so bind to a trusted network or put an authenticated gateway in front. DNS validation reduces SSRF risk but network-layer egress controls are still necessary against DNS rebinding and implementation defects. URL paths are logged; do not put secrets in paths.

Layout

app/                 FastAPI routes, models, locked store, checker and SSRF policy
tests/               API/unit tests; outbound HTTP and DNS are mocked
SERVICE_DESIGN.md    full resource, error, status, security and logging contract
Dockerfile           non-root, healthchecked, one-worker image
compose.yaml         local container workflow
pyproject.toml       package, lint, type-check and test configuration
requirements*.txt    pinned direct runtime/development dependencies

Local development

Python 3.12 is required.

python -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-dev.txt
ruff check .
ruff format --check .
mypy app
pytest
uvicorn app.main:app --reload

OpenAPI is at http://127.0.0.1:8000/docs.

API examples

curl -s http://127.0.0.1:8000/health/ready
curl -s -X POST http://127.0.0.1:8000/monitors \
  -H 'content-type: application/json' \
  -d '{"name":"Example","target_url":"https://example.com/"}'
curl -s http://127.0.0.1:8000/monitors
curl -s -X PUT http://127.0.0.1:8000/monitors/MONITOR_UUID \
  -H 'content-type: application/json' \
  -d '{"name":"Example home","target_url":"https://example.com/"}'
curl -s -X POST http://127.0.0.1:8000/monitors/MONITOR_UUID/check
curl -s http://127.0.0.1:8000/monitors/MONITOR_UUID/status
curl -i -X DELETE http://127.0.0.1:8000/monitors/MONITOR_UUID

HTTP below 400 is up, HTTP 400–599 is down, and network/DNS/timeout failures are error. A policy-blocked target returns 400 and leaves the previous completed status unchanged. Missing resources return 404 and invalid request data returns 422.

Configuration

Settings are read at startup. Invalid values prevent startup.

Variable	Default	Constraint
`MONITOR_HOST`	`0.0.0.0`	runtime launcher binding (Compose/Docker command is fixed)
`MONITOR_PORT`	`8000`	1–65535; use with a custom launcher command
`MONITOR_LOG_LEVEL`	`INFO`	DEBUG/INFO/WARNING/ERROR/CRITICAL
`MONITOR_CONNECT_TIMEOUT_SECONDS`	`2`	>0, <=30
`MONITOR_READ_TIMEOUT_SECONDS`	`5`	>0, <=60
`MONITOR_WRITE_TIMEOUT_SECONDS`	`5`	>0, <=60
`MONITOR_POOL_TIMEOUT_SECONDS`	`2`	>0, <=30
`MONITOR_MAX_REDIRECTS`	`5`	0–10
`MONITOR_MAX_CONNECTIONS`	`50`	1–500
`MONITOR_USER_AGENT`	`endpoint-monitor/1.0`	1–100 characters

Containers

docker build -t endpoint-monitor:local .
docker run --rm -p 8000:8000 endpoint-monitor:local
docker inspect --format '{{json .Config.Healthcheck}}' endpoint-monitor:local
docker compose up --build

The image uses a pinned Python 3.12 slim base tag, installs runtime dependencies only, runs as UID/GID 10001, declares a Python-based liveness healthcheck (no curl dependency), disables access logs to avoid unredacted query strings, and explicitly starts one Uvicorn worker.

Verification and current evidence

The intended clean-room verification sequence is:

python -m pip install -r requirements-dev.txt
ruff check . && ruff format --check .
mypy app
pytest
docker build -t endpoint-monitor:verify .
docker run -d --rm --name endpoint-monitor-verify -p 18000:8000 endpoint-monitor:verify
python -c "import urllib.request; print(urllib.request.urlopen('http://127.0.0.1:18000/health/live').read())"
docker inspect --format '{{.State.Health.Status}}' endpoint-monitor-verify
docker rm -f endpoint-monitor-verify

Generation persisted all source, tests, packaging, and documentation in one repository, but the generation environment exposed no shell or Docker executor. Consequently these commands were not executed during generation; there is no claim of passing test/build/startup evidence. The committed tests are inspectable evidence of intended coverage, not execution evidence. Validators should run the sequence above. See VERIFICATION.md for the exact honest status.

4.6 KiB Raw Permalink Blame History Unescape Escape