73 lines
2.9 KiB
Markdown
73 lines
2.9 KiB
Markdown
# 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 contract
|
|
- `app/`: configuration, models, locked store, SSRF policy, checker, and API
|
|
- `tests/`: API/unit tests with mocked outbound HTTP and DNS
|
|
- `Dockerfile`, `compose.yaml`: single-worker container packaging
|
|
|
|
## Local development
|
|
Requires Python 3.12.
|
|
|
|
```sh
|
|
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
|
|
```sh
|
|
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
|
|
```sh
|
|
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:
|
|
```sh
|
|
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.
|