crucible-agent-build-fastapi-endpoint/README.md

Endpoint Monitor Service

A typed FastAPI API that keeps endpoint monitors in concurrency-safe, process-local memory and performs SSRF-aware checks on demand. The service has no authentication and should not be exposed directly to untrusted users.

Quick start

Requires Python 3.12.

python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
./scripts/validate.sh
uvicorn monitor_service.api:app --reload

Create and check a monitor:

curl -sS -X POST http://localhost:8000/monitors -H 'content-type: application/json' \
  -d '{"name":"Example","url":"https://example.com/?secret=not-logged"}'
curl -sS -X POST http://localhost:8000/monitors/MONITOR_UUID/check
curl -sS http://localhost:8000/monitors/MONITOR_UUID/status

OpenAPI is at /docs. Liveness and readiness are at /healthz and /readyz.

Configuration

All settings use the MONITOR_ prefix: APP_NAME, LOG_LEVEL, CONNECT_TIMEOUT_SECONDS (default 3), READ_TIMEOUT_SECONDS (5), POOL_TIMEOUT_SECONDS (3), MAX_REDIRECTS (5), and USER_AGENT. Invalid or out-of-range values fail startup. Use one worker: memory is not durable or shared among processes.

Security behavior

Every initial and redirected HTTP(S) target is resolved before a request. A hop is denied if any answer is non-global, URL credentials are denied, redirect count is bounded, and timeouts are finite. Logs and check responses remove URL query and fragment data. See docs/service-contract.md for status/error semantics and the documented DNS resolver/connect TOCTOU limitation.

Container

docker build -t endpoint-monitor .
docker run --rm -p 8000:8000 endpoint-monitor
# or: docker compose up --build
curl -f http://localhost:8000/healthz

The image is two-stage, runs as a non-root user, contains a healthcheck, and deliberately starts one Uvicorn worker.

Layout and verification

• docs/service-contract.md: API and architecture contract
• src/monitor_service/: application, checker, state, models, settings, logging
• tests/: API, concurrency, checker, SSRF redirect/DNS, failure, and redaction tests
• scripts/validate.sh: the authoritative Ruff format/lint, mypy, and pytest contract
• Dockerfile and compose.yaml: container workflows

Run ./scripts/validate.sh. Container verification additionally uses the build/run/curl commands above. VALIDATION.md records what was and was not executed by generation; it must not be read as a substitute for fresh CI output.