72 lines
2.1 KiB
Markdown
72 lines
2.1 KiB
Markdown
# 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
|