# Endpoint Monitor Service

A typed FastAPI service for process-local monitor CRUD and secure, on-demand HTTP
checks. The full contract and status semantics are in
[`docs/service-contract.md`](docs/service-contract.md).

## Run locally

```bash
python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
uvicorn app.main:app --reload
```

Create and check a monitor:

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

OpenAPI is at `/docs`. There is intentionally no authentication.

## Configuration

All settings are validated at startup and use the `MONITOR_` prefix:

| Variable | Default | Constraint |
|---|---:|---|
| `MONITOR_APP_NAME` | endpoint-monitor | string |
| `MONITOR_LOG_LEVEL` | INFO | logging level |
| `MONITOR_CONNECT_TIMEOUT_SECONDS` | 2 | >0, <=30 |
| `MONITOR_CHECK_TIMEOUT_SECONDS` | 5 | >0, <=60 |
| `MONITOR_MAX_REDIRECTS` | 3 | 0..10 |

## Quality checks

```bash
ruff format --check .
ruff check .
mypy app
pytest
```

Outbound HTTP is mocked in tests. Security cases cover private DNS answers, redirects
to loopback, bounded errors, compare-and-set status publication, and query redaction.

## Container

```bash
docker build -t endpoint-monitor .
docker run --rm -p 8000:8000 endpoint-monitor
# or: docker compose up --build
```

The image runs as a non-root user and deliberately uses one worker. A restart loses
all monitors. Running multiple workers/replicas creates independent datasets and
inconsistent reads; use a shared durable store before scaling. DNS preflight is not a
replacement for network-level egress controls against rebinding.

## Project layout

- `app/`: API, settings, locked store, checker, SSRF policy, JSON logging
- `tests/`: API, checker, store, configuration, and security tests
- `docs/service-contract.md`: routes, semantics, lifecycle, and threat boundaries
- `VERIFICATION.md`: exact validation commands and execution status