Repository navigation
Conversation
There was a problem hiding this comment.
Pull request overview
This PR hardens the default gateway posture to be “closed by default” (TLS + auth enabled, and auth required for reads as well as writes), adds a narrowly-scoped public health exemption, and introduces an integration acceptance test that sweeps the live route registry to ensure unauthenticated access is refused across the surface area.
Changes:
- Switch shipped defaults to
auth.enabled: true,auth.require_auth_for: "all", andserver.tls.enabled: true. - Update
AllAuthRequirementPolicyto exempt onlyGET /api/v1/health(plus/api/v1/auth/*) and add unit tests pinning the exemption boundary. - Add/adjust integration tests: a full route-sweep “closed by default” acceptance test and a more precise recovery poll in
test_peer_recovery.
Reviewed changes
Copilot reviewed 27 out of 27 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| src/ros2_medkit_integration_tests/test/features/test_peer_recovery.test.py | Tightens polling to wait for actual “data” readiness rather than HTTP 200 alone. |
| src/ros2_medkit_integration_tests/test/features/test_closed_by_default.test.py | New integration acceptance that sweeps all registered routes for unauthenticated refusal + authenticated pass-through. |
| src/ros2_medkit_gateway/test/test_auth_manager.cpp | Adds regression tests pinning the GET /api/v1/health exemption and /api/v1/auth/* public endpoints under the “all” policy. |
| src/ros2_medkit_gateway/launch/gateway.launch.py | Adds launch args for enabling/disabling auth and injecting JWT secret + clients for quickstart usability. |
| src/ros2_medkit_gateway/include/ros2_medkit_gateway/core/auth/auth_requirement_policy.hpp | Implements the health/auth exemptions for the “all” auth-requirement policy and updates its description string. |
| src/ros2_medkit_gateway/design/hardening.rst | Updates hardening guidance to reflect the new shipped-default locked posture and its implications. |
| src/ros2_medkit_gateway/config/gateway_params.yaml | Changes shipped default params to enable TLS + auth and require auth for all operations. |
| README.md | Updates example curl commands to include Authorization header. |
| docs/tutorials/triggers-use-cases.rst | Updates curl examples to include Authorization header. |
| docs/tutorials/snapshots.rst | Updates curl examples to include Authorization header. |
| docs/tutorials/scripts.rst | Updates curl examples to include Authorization header. |
| docs/tutorials/openapi.rst | Updates curl examples to include Authorization header. |
| docs/tutorials/migration-to-manifest.rst | Updates curl examples to include Authorization header. |
| docs/tutorials/manifest-discovery.rst | Updates curl examples to include Authorization header. |
| docs/tutorials/locking.rst | Updates curl examples to include Authorization header. |
| docs/tutorials/linux-introspection.rst | Updates curl examples to include Authorization header. |
| docs/tutorials/heuristic-apps.rst | Updates curl examples to include Authorization header. |
| docs/tutorials/graph-provider.rst | Updates curl examples to include Authorization header. |
| docs/tutorials/fault-correlation.rst | Updates curl examples to include Authorization header. |
| docs/tutorials/docker.rst | Updates curl examples to include Authorization header (non-health endpoint). |
| docs/tutorials/demos/demo-turtlebot3.rst | Updates curl examples to include Authorization header. |
| docs/tutorials/demos/demo-sensor.rst | Updates curl examples to include Authorization header. |
| docs/tutorials/beacon-discovery.rst | Updates curl examples to include Authorization header. |
| docs/index.rst | Adds a “ships closed” note and updates quick reference curls to include Authorization header. |
| docs/getting_started.rst | Updates quickstart launch invocation and subsequent curl examples for the closed-by-default posture. |
| docs/config/discovery-options.rst | Updates curl examples to include Authorization header. |
| docs/api/rest.rst | Updates curl examples to include Authorization header. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
b69681b to
0771718
Compare
8d5989c to
9bc6bcb
Compare
975193c to
e94fb3e
Compare
e94fb3e to
7c947d9
Compare
d5364a3 to
eea4c8a
Compare
| // A set-but-empty secret closes nothing, and says so. The variable is | ||
| // documented as non-empty, and an operator who exported it empty is | ||
| // holding half a configuration; silence would read as "closed". | ||
| if (jwt_secret.has_value()) { |
There was a problem hiding this comment.
A set-but-empty MEDKIT_JWT_SECRET falls back to the params file with only a WARN, so a compose file with environment: - MEDKIT_JWT_SECRET=${MEDKIT_JWT_SECRET} and a missing host variable starts the container open. An operator who set the variable at all meant to close the gateway, and a blank value is a failed interpolation rather than a choice, so refuse to start here the same way an all-refused MEDKIT_CLIENTS is refused at gateway_node.cpp:607. MEDKIT_AUTH_DISABLED=1 already exists for opening on purpose.
| description=( | ||
| 'Comma-separated "client_id:client_secret:role" triples ' | ||
| '(roles: viewer, operator, configurator, admin). Needed to obtain ' | ||
| 'a token from /auth/token.')) |
There was a problem hiding this comment.
/auth/token only accepts grant_type=refresh_token (auth_handlers.cpp:147), so this help text sends an operator to the wrong endpoint with the credentials they just configured. Say POST /api/v1/auth/authorize.
|
|
||
| docker run -p 8080:8080 \ | ||
| -e MEDKIT_JWT_SECRET="$(head -c 32 /dev/urandom | base64)" \ | ||
| -e MEDKIT_CLIENTS="medkit:$(head -c 24 /dev/urandom | base64):admin" \ |
There was a problem hiding this comment.
This command generates the client secret inline and never captures it, so a reader who pastes it gets a container that nobody, themselves included, can obtain a token from. Put it in a variable first, the way the 8443 example below does with CLIENT_SECRET.
…route list Profiles. config/gateway_params.yaml stays open: auth off, require_auth_for "write", TLS off. Every existing launch, every existing config file and the web UI send no credential. The packages are in rosdistro, so closing that file would close all of them on an apt upgrade. config/gateway_params.secure.yaml is the closed profile: auth on, require_auth_for "all", TLS on, rate limiting on and an explicit CORS origin list. A deployment selects it with config_file:=, which gateway.launch.py and bringup.launch.py both take. Launch arguments. gateway.launch.py also takes jwt_secret, auth_clients, auth_enabled, tls_enabled, cert_file and key_file. When auth or TLS is on and the matching value is missing, it prints what to pass. It reads the active profile from the config_file. When it cannot read that file as a mapping of node names, it says so and leaves the file's values alone. package.xml adds python3-yaml for this. Environment. The node reads MEDKIT_JWT_SECRET, MEDKIT_CLIENTS and MEDKIT_AUTH_DISABLED when it loads its parameters. So the container entrypoint, `ros2 run` and every launch file apply one rule: - MEDKIT_JWT_SECRET closes the gateway with require_auth_for "all" and that secret. - MEDKIT_CLIENTS replaces auth.clients. Entries are trimmed. A duplicate id keeps its first entry. An empty value means no clients. A list whose every entry is refused stops the gateway. - MEDKIT_AUTH_DISABLED=1 opens any gateway. - MEDKIT_JWT_SECRET together with RS256 stops the gateway. A refusal names the setting and where it came from, never its value. A malformed client entry is reported by its position and id. The launch file does not read MEDKIT_TLS_CERT_FILE or MEDKIT_TLS_KEY_FILE. Secrets. auth.jwt_secret, auth.clients and aggregation.peer_auth_header are taken from the merged parameter overrides and handed to their consumers. They are declared with a sentinel and ignore_override in every auth state, so no parameter service or parameter event carries a secret. auth.* and the peer header are read at start, and a runtime set is refused. Public routes. auth.public_routes is a new setting. It lists routes that are answered with no credential. Each entry is "METHOD /path" and is matched exactly. The list layers over require_auth_for and can only remove a requirement, so it is the whole public surface. No shipped profile sets it. It is validated whether or not auth is on. A malformed entry stops the gateway. A blank entry, which is any whitespace, is skipped. /health. On a route listed in auth.public_routes, a caller with no credential gets only status, timestamp, an empty warnings list and warning_schema_version, marked x-medkit-reduced. The full body is not safe to publish there. linking.warnings holds entity names and ROS node FQNs, for example "App 'engine_ecu' cannot bind to '/nav/controller'". x-medkit-entity-cache holds the counts of apps, areas and components. The check runs before any section is built, so a section added later is private by default. Request order. Authentication ran after the CORS preflight and the rate limiter, and both return Handled. With CORS on, an anonymous OPTIONS on a protected route got 204. An exhausted limiter answered 429 on a gateway that requires a credential for every route. The pre-routing handler now works in this order: - Only a real preflight, an OPTIONS with Access-Control-Request-Method, is exempt. A plain OPTIONS is metered and authenticated like any other request. - The limiter meters every request before authentication. - A caller over the limit who sends any Authorization header gets a bare 429 before any token work. - A caller with no credential gets the middleware's standard 401, with WWW-Authenticate and an error document. The refusal carries the CORS headers, so a browser can read the 401. - The X-RateLimit-* headers go on only after the caller is accepted or the route needs no credential. On an anonymous 401 they would disclose the limiter state. Tokens. An access token is accepted on its signature and the local client table. It survives a restart and works on a peer that shares the signing config. The receiving gateway's auth.clients decides its role. POST /auth/revoke writes a revoked record keyed by the refresh token's id. It does this also on a gateway that never issued the token, and for a refresh token past its expiry. An access token presented there changes nothing. A foreign record is kept at most for this gateway's own refresh lifetime. Refresh records are swept every five minutes and on every refresh. The client secret comparison runs in constant time. RS256 keys are read once at start. TLS. server.tls.min_version is enforced on the server's own SSL context. Setting ca_file turns on mutual TLS and requires a client certificate. generate_dev_certs.sh is executable. It no longer prints a ca_file, which would make the gateway demand a client certificate.
…ironment The image carries three params files. The entrypoint applies them left to right, and each can override the one before it: - /etc/ros2_medkit/base.yaml is config/gateway_params.yaml, the file the package ships. The image and a source install share one posture. - /etc/ros2_medkit/container.yaml holds the two values a container needs on top of it: bind every interface, and refresh every 2 s. - /etc/ros2_medkit/params.yaml is the mount point. The image's own copy repeats container.yaml. A mounted file replaces that copy and wins wherever it sets a key, server.host and refresh_interval_ms included. The caller's arguments come after the three files, so a caller's -p wins over them. The Dockerfile CMD is empty. So `docker run <image> --ros-args -p server.port:=9090` keeps server.host at 0.0.0.0. docker/gateway_docker_params.yaml is removed. CORS names no origin. The entrypoint exports MEDKIT_JWT_SECRET, MEDKIT_CLIENTS and MEDKIT_AUTH_DISABLED and does not interpret them. The gateway node applies the environment rule itself. The rule therefore holds for the entrypoint's gateway, for `docker run <image> ros2 launch ...` and for any command started from a shell in the container. Setting MEDKIT_JWT_SECRET runs the container closed. MEDKIT_AUTH_DISABLED=1 forces authentication off. The Dockerfile shows how to point --params-file at the closed profile inside the image. That profile enables TLS, so it also needs a certificate and a key. scripts/smoke_image_auth_posture.sh checks the image with two instruments. For posture it reads the status code of an anonymous GET /areas at the container's bridge address: 200 with no environment, 401 with the secret, and 401 with the secret over a params file that turns auth off. The third case shows that the environment beats the file. For layering it reads the gateway's startup line from the container log: a mounted file's value applies, and -p server.port keeps server.host. The script copies a params file into the container with docker cp. A bind mount and a published port resolve in the daemon's namespace, which need not be the caller's. The per-push workflow runs the smoke script against the digest it is about to tag. It then creates :latest and :main-<sha7> from that inspected digest in one invocation. :latest moves on every merge, so :main-<sha7> is the immutable reference to pin. The multi-arch workflow owns the semver tags and sha-<sha7>, which name its manifest list. The per-push workflow owns :latest and :main-<sha7>, which name its linux/amd64 image. No tag name is written by both, so a release tag cut on a commit that is also on main cannot leave one name pointing at two images. A comment in the multi-arch workflow records this split.
…miter test_closed_by_default runs a gateway on the secure profile. It asks the gateway for its route table and calls every route with no credential, then again with a fake token. It asserts that the table is large, because a sweep over three routes proves almost nothing. A test that read config values would keep passing after a route is registered outside the policy. The test sets rate limiting and the docs routes to values the sweep needs. At the profile's allowance most of the sweep would answer 429, and with /docs off it would cover less. The limiter cases pin the refusal itself: the challenge header, the error document and the single 401 shape. A caller over the limit gets a bare 429 with a valid bearer token and on a plain OPTIONS. The limiter headers reach credentialed callers only. test_secure_profile boots from config/gateway_params.secure.yaml and test_open_default_profile boots from config/gateway_params.yaml, so a flip in either direction fails. test_env_closes_the_gateway drives gateway.launch.py with MEDKIT_JWT_SECRET in the environment and no launch arguments. The container image uses this path. test_env_auth_contract drives the environment rule against the node: - precedence over a params file, proven through a value only the file sets - an empty client list, an all-refused client list and the RS256 refusal - the parameter read-back, and the refused param set, param load and atomic batch - the sentinels in every auth state - a scan of every gateway's output for the secrets after shutdown The params file for `ros2 param load` is keyed on the absolute node name, /gateway_env_closed, because the loader matches keys against that name. Gateways in the refusal cases are killed as a process group. test_forward_auth_across_gateways runs two gateways under forward_auth. A token issued on one works on the other. It is refused there after a revoke on the peer, and it grants the peer's role. CMake registers it as a two-gateway test. test_tls_protocol_floor drives openssl s_client against a real gateway for the protocol floor and for client-certificate verification. An HTTP client can observe neither. test_openapi_contract now waits for calibration's operation before it compares built items. A node is listed in the ROS graph before its service endpoints propagate. A discovery sweep can then build the App with an empty service list, and the cache-derived operation items in /docs come from that list. The health-readiness helper accepts 401 and 403. It waits for a process that listens and speaks HTTP, and a refusal proves both. package.xml adds python3-yaml as a test dependency.
…age layers The configuration reference, the hardening design doc, the authentication tutorial and the HTTPS tutorial name the profile each value belongs to. hardening.rst adds what the secure profile costs to run, and says the secret parameters carry a placeholder, so ros2 param get and /parameter_events do not show them. The gateway refuses to start with auth on and no signing secret. Under require_auth_for "all", only /api/v1/auth/* is exempt. Health also needs a credential. A probe accepts 401, or the operator names the route in auth.public_routes. server.rst, rest.rst, aggregation.rst, authentication.rst, docker.rst and hardening.rst describe: - the environment rule and its notices - what survives a restart: access tokens do, refresh tokens do not - the revocation denylist, and the shared-expiry rule under forward_auth - the limiter's answer for each kind of caller - the five keys of the reduced health body The configuration reference, the HTTPS tutorial and the gateway README no longer describe ca_file as reserved. It turns on mutual TLS and requires a client certificate from every caller. Bearer-token clients without a certificate can then no longer connect. The docker tutorial describes an image that answers without a credential and how to close it. It covers the precedence between the environment and a params file, the image's three config layers and the order they apply in, the closed-profile run command, the CORS file of the compose example, and the main-<sha7> tag published next to :latest on every push to main. The two new subsections under Authentication in server.rst use the underline character that the file already uses for level 3. docutils fixes heading depths by the first character it sees at each depth, so a new character would be an inconsistent title level.
eea4c8a to
76517f6
Compare
Token times are whole seconds. A start late in a second left the two-second wait almost no margin before the three-second refresh expiry, so the refresh was refused on a loaded machine. Starting just after a boundary keeps about a second of margin at every step.
…n the atomic batch test `ros2 param get` shares its streams with DDS diagnostics, so two reads of the same value could differ in text when the middleware logged a warning between them. The test now compares the value line only.
Token times are wall-clock seconds, but the tests slept with sleep_for, which measures the steady clock. When the wall clock steps against the steady clock (NTP or VM time sync), a 2 s sleep can move token time by more than 3 s, and an access token that the test expects to be valid has already expired. The tests now sleep in 10 ms steps until the wall clock reaches the target, so each check happens at the wall time the test reasons about.
The gateway node now reads MEDKIT_JWT_SECRET, MEDKIT_CLIENTS and MEDKIT_AUTH_DISABLED when it loads its parameters, so the same rule holds however it is started: ros2 run, any launch file, a container. - A non-empty MEDKIT_JWT_SECRET turns authentication on, forces require_auth_for to "all" and is the signing secret, over the params file and -p arguments. Set but empty, the gateway refuses to start. With RS256 it is refused as well. - MEDKIT_CLIENTS replaces auth.clients (id:secret:role, comma-separated, trimmed, first duplicate id wins). Malformed entries are reported by position and never echoed; a list where every entry was refused stops the gateway; without a secret the variable is ignored with a warning. - MEDKIT_AUTH_DISABLED=1 turns authentication off over everything else; any other value has no effect. - ros2 param get reports the enforced posture. auth.jwt_secret, auth.clients and aggregation.peer_auth_header are declared with sentinels and never carry a secret. Runtime writes to auth.* and aggregation.peer_auth_header are refused, because the auth configuration is built once at start. - The role-name lowercase conversion is defined for every byte. Integration tests drive the real gateway process through its environment, the ros2 param CLI and HTTP.
A refused MEDKIT_CLIENTS or auth.clients entry is now reported by its position and the reason, never by any of its fields: an entry shifted by one field carries a secret in the id slot. A repeated id points at the earlier entry's position instead of quoting the id. MEDKIT_CLIENTS set to an empty value without MEDKIT_JWT_SECRET now logs the "ignored" warning like any other set value. Test changes: the ready-line wait distinguishes a seen marker from a hit deadline and every control that expects a running gateway also requires an HTTP answer; the runtime refusal is checked for every auth.* parameter and aggregation.peer_auth_header the running gateway lists; every non-1 value of MEDKIT_AUTH_DISABLED is checked against a default gateway. The authentication tutorial notes that a wrongly typed auth.* file value stops the gateway even when an environment variable would replace it.
Each ros2 param call started a ros2-daemon on the test's domain and left it running. Pass --no-daemon so nothing outlives the test.
Plugin config (plugins.<name>.<key>) was declared as node parameters with its real value, so any participant on the DDS domain could read a plugin password with ros2 param get, and every declaration was published on /parameter_events. The gateway now reads the plugin keys from the node's parameter overrides (params files, -p arguments and NodeOptions) and hands them to the plugin without declaring them. Only plugins.<name>.path stays a parameter. Adds an integration test that reads the parameters of two real gateways, one configured by a params file and one by -p, and an in-process test that subscribes to /parameter_events before the node exists and checks that no secret value is published. Documents where a secret is safe. The timeout of test_env_auth_contract is raised because its CLI calls take 580 s on a loaded machine.
test_env_auth_contract ran about 500 s and test_plugin_config_not_served about 155 s on a loaded machine, almost all of it in ros2 param processes that each start up and rediscover the DDS graph. One rclpy node per test process now calls the gateway's parameter services, so discovery happens once. A refusal still checks the reason text, and an undeclared key is checked by its PARAMETER_NOT_SET type. ros2 param load stays a CLI call, because the file it parses is what the case is about. Both timeout overrides are removed. The /parameter_events test no longer depends on a generated to_yaml; it reads the names and string fields of each event.
automatically_declare_parameters_from_overrides and allow_undeclared_parameters make rclcpp declare the overrides, plugin config and auth secrets included, with their values. GatewayNode now throws if either is set, and its constructor documents the precondition. The test plugin gets an opt-in expose_config key that shows the config it received as the Function's description. test_plugin_config_not_served now compares the exact JSON, types and nesting included, for a params-file gateway and a -p gateway. The docs state the node-option precondition, that a plugin must not declare its own config keys, and the trade-off of keeping a secret in the environment.
The check in the constructor body ran after rclcpp had already declared and published every override when automatically_declare_parameters_from_overrides was set. It now runs in the base-class initializer, so the throw comes before any parameter exists.
The branch now carries one change on current main: the gateway node reads MEDKIT_JWT_SECRET, MEDKIT_CLIENTS and MEDKIT_AUTH_DISABLED itself, secrets and plugin config are not served as parameters or on /parameter_events, and auth settings cannot change at runtime. The Docker image layers, the secure profile and its launch arguments, token handling, the rate limiter, public routes and TLS follow as separate pull requests on top of this one.
Pull Request
Summary
The gateway node now reads three environment variables when it loads its parameters, so the same rule holds for
ros2 run, every launch file and a container:MEDKIT_JWT_SECRETturns authentication on withrequire_auth_for: alland that signing secret, whatever the params file or-psays. Set but empty, it stops the gateway at start.MEDKIT_CLIENTSreplacesauth.clientswith comma-separatedid:secret:roleentries. A refused entry is reported by its position only. If every entry is refused, the gateway does not start. WithoutMEDKIT_JWT_SECRETthe variable is ignored with a warning.MEDKIT_AUTH_DISABLED=1turns authentication off over everything else.MEDKIT_JWT_SECRETwithauth.jwt_algorithm: RS256stops the gateway, because the variable holds an HS256 secret.ros2 param getnow reports what the gateway enforces.auth.jwt_secret, eachauth.clientssecret andaggregation.peer_auth_headerread back as<from MEDKIT_JWT_SECRET>or<set at start>.auth.*andaggregation.peer_auth_headerare read at start, soros2 param setandros2 param loadrefuse them with that reason.Plugin config (
plugins.<name>.<key>) is no longer declared as node parameters. The gateway reads it from the node's parameter overrides and hands it to the plugin, so a key such asplugins.opcua.passwordis not served byros2 param getand is not published on/parameter_events. Onlyplugins.<name>.pathstays a parameter. The secrets above are declared with their placeholders from the start, so/parameter_eventsnever carries their values either.GatewayNoderefusesNodeOptionswithautomatically_declare_parameters_from_overridesorallow_undeclared_parametersset, because either makes rclcpp declare the overrides with their values. The check runs before the node exists.The docs say where a secret is safe: the environment keeps it out of params files and the process list (the same user can still read
/proc/<pid>/environ); a params file holding a secret must be readable only by the gateway's user; a value given with-pis visible to every local user in the process list.Breaking changes:
ros2 param get auth.require_auth_forreadsnoneinstead of the configured value.auth.*/aggregation.peer_auth_headercan no longer be set at runtime (before, the set was accepted and had no effect).ros2 param get/liston a gateway no longer showplugins.<name>.<key>(exceptpath). The plugin still receives the same config.GatewayNodewith either of the twoNodeOptionssettings above now getsstd::invalid_argument.Issue
Type
Testing
Start a gateway closed by the environment:
In a second shell:
Plugin config is not served (any plugin; the OPC UA plugin reads
passwordfrom its config):The integration tests
test_env_auth_contract,test_env_closes_the_gatewayandtest_plugin_config_not_servedrun each rule against a real gateway process;test_secrets_not_on_parameter_eventssubscribes to/parameter_eventsbefore the node is built and checks that no secret goes out.Checklist