56 lines
2.4 KiB
Markdown
56 lines
2.4 KiB
Markdown
# 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.
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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.
|