docker-bastion/examples/osm-taxiways/README.md

89 lines
4.7 KiB
Markdown
Raw Normal View History

# OSM taxiway bastion (broker mode)
A **self-contained, whitelisted** SSH box for an OSM taxiway export pipeline. It lets a
backend fetch/generate airport ground-layout GeoJSON without handing it a shell or root:
the bastion only ever runs **three** commands, validated whole-line against a regex
allowlist and exec'd **shell-free** (no `sh -c`, so nothing an ICAO argument contains can
become a shell operator or a path).
```
ssh agent@<osm-host>
└─ bastion-broker (key auth; matches request vs allowed-commands.list)
├─ taxiways-list → ls *-taxiways.geojson in /osm-maps
├─ taxiways-export <ICAO> [<lat> <lon>] → export-icao-geojson.sh <ICAO> [<lat> <lon>]
└─ taxiways-cat <ICAO> → base64 <ICAO>-taxiways.geojson (ssh-safe tunnel)
```
**Pass the aerodrome's coordinates when you have them** (`taxiways-export SJXN -22.710000
-46.500000`, six decimals). OSM reuses ICAO tags: a helipad or a namesake field elsewhere can
carry the same code, and an export by tag alone then centres on the wrong object. With
coordinates the export keeps the tagged object nearest them (aerodrome/airstrip before
helipads, `select-aerodrome.jq`); when no tagged object lies within 15 km it looks for an
aerodrome/airstrip around the coordinates instead. A backend should fall back to the ICAO-only
form when an older bastion refuses the coordinate form (broker exit 126).
The OSM toolchain (`osmium`, `ogr2ogr`, `jq`) is baked into the image (see `Dockerfile`),
so the export runs **inside** this container against the mounted `osm-maps` directory
(which holds a region PBF + `export-icao-geojson.sh`). No docker socket, no second
container — the only host data reachable is that one directory.
## Files
| file | purpose |
|------|---------|
| `Dockerfile` | Debian base (Alpine has no `osmium-tool`) + `osmium-tool`/`gdal-bin`/`jq` + openssh + the wrappers |
| `bastion-broker` | the allowlist gate, verbatim from `docker-bastion/scripts` (whole-line ERE match → shell-free exec) |
| `entrypoint` | broker-only sshd: key-only, single non-root user, every session forced through the broker |
| `bin/taxiways-{list,export,cat}` | the only executables the allowlist lets a client run |
| `allowed-commands.list` | the regex allowlist (`taxiways-export [A-Z]{4}`, …) — the security boundary |
| `export-icao-geojson.sh` + `select-aerodrome.jq` | the export itself; copy BOTH into the osm-maps dir (not into the image). The PBF is `$OSM_PBF`, default `/osm-maps/aerodromes-world.osm.pbf` (a symlink there may point at a PBF mounted elsewhere) |
| `tests/*.test.sh` | `bash tests/select-aerodrome.test.sh` (jq only) and `bash tests/export-anchor.test.sh` (osmium/ogr2ogr stubbed) |
| `docker-compose.yml` | broker-mode service, osm-maps + allowlist + keys mounts, port 6770 |
> This flavor is **Debian standalone** (not `FROM blaxsoftware/bastion`) because the export needs
> `osmium`, which Alpine doesn't package. It reuses the base repo's `bastion-broker` unchanged; only
> the sshd bootstrap is a compact broker-only `entrypoint` instead of the Alpine `start-container`.
## Deploy (on the host holding your osm-maps dir)
```bash
# 1) Authorize the backend's agent key
mkdir -p docker-data/bastion/users.d
cp /path/to/agent.pub docker-data/bastion/users.d/backend.pub
# 2) Let the bastion's `agent` user write into osm-maps (export writes files + work/)
AGENT_UID=$(docker run --rm blaxsoftware/bastion:latest id -u agent)
chown -R "$AGENT_UID" /srv/osm-maps # point at your actual osm-maps dir
# 3) Confirm the osm-maps dir has the script + PBF
ls /srv/osm-maps/export-icao-geojson.sh /srv/osm-maps/*.osm.pbf
# 4) Build + run
docker compose up -d --build
```
To publish the image for reuse:
```bash
docker build --platform linux/amd64 -t blaxsoftware/bastion-osm-taxiways:latest .
docker push blaxsoftware/bastion-osm-taxiways:latest
```
## Test
```bash
ssh -p 6770 agent@<osm-host> taxiways-list # → list (maybe empty)
ssh -p 6770 agent@<osm-host> taxiways-export EDDF # → runs the export (minutes)
ssh -p 6770 agent@<osm-host> taxiways-cat EDDF | base64 -d | head # → GeoJSON
ssh -p 6770 agent@<osm-host> 'rm -rf /' # → "command not permitted", exit 126
ssh -p 6770 agent@<osm-host> taxiways-export eddf # → refused (lowercase ≠ [A-Z]{4})
```
## Backend wiring
The backend stores the private key whose `*.pub` you dropped in `users.d/`, and connects
as `agent@<osm-host>:6770`, sending one of the three commands per connection. `taxiways-cat`
returns base64 that the backend decodes into its own storage; `taxiways-export` runs the
(minutes-long) OSM export. A pure-PHP SSH client (e.g. phpseclib) works fine — no `ssh`
binary is required on the backend side.