API Reference — infrabroker¶
This document describes all HTTP endpoints exposed by the infrabroker services.
Keep this file up to date whenever an endpoint is added, removed, renamed, or its
request/response schema changes.
Table of Contents¶
- Signer API —
cmd/signer· HTTPS + mTLS · default:9443 - POST /v1/sign
- GET /v1/hosts
- GET /v1/clusters
- POST /v1/reload
- POST·DELETE /v1/policy/hosts/{host}/allow
- Runtime grants: POST /v1/policy/hosts/{host}/grants · GET /v1/policy/grants · DELETE /v1/policy/grants/{id}
- GET /v1/policy/hosts
- Control Plane API —
cmd/control-plane· HTTPS + mTLS · default:7443 - POST /v1/sign
- GET /v1/sign/result/{id}
- GET /v1/approvals
- POST /v1/approvals/{id}
- Approval UI: GET /ui/approvals · GET /ui/approvals/{id}
- Broker HTTP API —
infrabroker serve-http· HTTPS + mTLS - POST /v1/ssh_run
- MCP HTTP API —
infrabroker serve-mcp-http· HTTPS + OAuth2/OIDC · default:8443 - GET /.well-known/oauth-protected-resource
- MCP Streamable HTTP — tools
- Monitoring endpoints — every service · plain HTTP ·
monitor_listen
Signer API¶
Service: cmd/signer
Transport: HTTPS + mutual TLS (mTLS)
Default listen address: :9443 (configurable via listen in signer.json)
Auth: every request requires a valid TLS client certificate signed by the
configured client_ca. The Common Name (CN) of the certificate is the caller
identity used for RBAC and audit logging.
POST /v1/sign¶
Request an ephemeral SSH certificate for an intent. The signer validates the request against the host policy, signs the ephemeral public key, and returns a scoped certificate.
Auth: mTLS client certificate. CN identifies the broker.
Content-Type: application/json
Max body size: 64 KiB
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
host |
string | ✓ | Logical host name as declared in signer.json. |
role |
string | ✓ | "bastion" or "target". |
purpose |
string | ✓ | "oneshot" or "session". |
session_mode |
string | session intents | "exec", "shell" or "pty". Required for session open and session exec preflight. On a command-policy host only "exec" is allowed; "shell"/"pty" are rejected because their stateful streams cannot be verified per command. |
command |
string | oneshot or session exec preflight | Command to lock into the cert's force-command for one-shot, or to evaluate before ssh_session_exec. Must not contain \n or \r when command policy is evaluated. |
ttl_seconds |
int | Requested TTL in seconds. Capped by per-host max_ttl_seconds (global default: 5 min). |
|
public_key |
string | ✓ | Ephemeral Ed25519 public key in authorized_keys format. |
sudo |
bool | Request NOPASSWD elevation via sudo -n. Requires allow_sudo: true on the host policy. |
|
sudo_user |
string | Target user for sudo. Empty = root. Must match allowed_sudo_users if that list is set. |
|
pty |
bool | Request permit-pty in the certificate. Requires allow_pty: true on the host policy. |
|
file_transfer |
bool | Marks the request as a file transfer (ssh_put_file / ssh_get_file). Requires allow_file_transfer: true on the host policy; rejected 403 otherwise. The transfer command itself travels in command. |
|
dry_run |
bool | If true, resolve policy and return the decision without issuing a usable certificate. The response carries decision and omits certificate/serial. A policy denial in dry-run is reported as decision.allowed=false (HTTP 200), not a 403. |
|
preflight |
bool | Internal broker/control-plane signal, only meaningful with dry_run=true: this decision authorizes an imminent execution such as ssh_session_exec. The signer still issues no certificate, but the control plane applies behavioral guardrails and rate limits as it would for execution. |
|
on_behalf_of |
string | CN of the broker a trusted forwarder (control plane) is acting for. Honored only if the mTLS CN is in trusted_forwarders; otherwise the request is rejected (403). Used as the effective caller for RBAC. |
|
approved |
bool | Marks a require_approval command as approved. Honored only from a trusted forwarder. Without it, a require_approval command returns 200 with no certificate (see below). |
|
end_user |
string | OIDC identity of the end user (propagated by the HTTP frontend). Recorded in the audit log and embedded in the cert KeyId for sshd traceability. |
|
end_user_groups |
[]string | OIDC groups of the end user. When non-nil, activates per-user RBAC: the host's groups field must intersect with this list. |
|
end_user_context |
string | Attribution context of the end user's token (the frontend's oauth.context_claim, e.g. an ASP sandbox_id; SANDBOX.md). Written to the cert KeyId (ctx=) and the audit records (end_user_context); never a decision input. Re-derived from the verified token for callers with require_verified_end_user. |
|
learn_ttl_seconds |
int | Approve-and-learn: ask the signer to mint a TTL'd approval waiver for this approved command/elevation/caller/end-user scope. Honored only from a trusted forwarder (the control plane), exactly like approved. |
|
learn_approver |
string | Audit metadata: approver of the decision that authorized the learning. Trusted forwarder only. | |
learn_approval_id |
string | Audit metadata: approval id that authorized the learning. Trusted forwarder only. |
Kubernetes target fields (only when brokering a cluster; see Kubernetes target):
| Field | Type | Required | Description |
|---|---|---|---|
target_type |
string | "k8s" selects the Kubernetes path (absent or "ssh" = SSH host, the default). On the k8s path host is the cluster name and public_key is not used. |
|
k8s_verb |
string | k8s | One of get, list, logs, apply, delete. |
k8s_resource |
string | k8s | Lowercase plural resource (e.g. pods, deployments). |
k8s_group |
string | API group; omit for core resources. Normalized against the cluster's resource table. | |
k8s_namespace |
string | Namespace; omit for cluster-scoped resources or an all-namespaces list. | |
k8s_name |
string | get/logs/apply/delete | Object name (omitted for list). |
For a k8s request, command must equal the canonical action <verb> <resource[.group]> <namespace>/<name> (with - for an empty namespace/name); the signer recomputes it from the structured fields and rejects a mismatch (400), so the audited/approved action is provably what runs.
Response body (200 OK):
| Field | Type | Description |
|---|---|---|
certificate |
string | Signed SSH certificate in authorized_keys format. Omitted in dry-run and for k8s. |
serial |
uint64 | Certificate serial number (or the k8s issuance serial). Correlates with the audit logs. Omitted in dry-run. |
elevation_prefix |
string | Sudo prefix to prepend to commands in persistent sessions (e.g., "sudo -n"). Empty for one-shot intents — the prefix is already baked into force-command. |
k8s_token |
string | Short-lived bound ServiceAccount token minted for a k8s intent (the k8s analogue of certificate). Omitted in dry-run and for SSH. |
k8s_token_expiry |
string | RFC 3339 expiry of k8s_token. |
decision |
object | Policy decision (always present in dry-run; optional otherwise). See below. |
decision object:
| Field | Type | Description |
|---|---|---|
allowed |
bool | Whether the command would be authorized. |
reason |
string | Denial reason (empty if allowed). |
require_approval |
bool | Whether the command requires human approval (command policy require_approval matched). |
matched_rule |
string | The command_policy rule that drove the decision (e.g., allow:^uptime$, deny:rm -rf, require_approval:^reboot). |
force_command |
string | The force-command that would be baked into the cert (includes the sudo prefix). |
ttl_seconds |
int | TTL the issued cert would carry. |
elevation |
string | Elevation prefix that would apply (sessions). |
enforcement |
string | Effective command-policy enforcement mode: "enforce" or "audit". |
warning |
string | Audit-mode warning, e.g. command_policy audit: would deny (allowlist:no-match). |
would_deny |
bool | In audit mode, true when the command would have been denied in enforce mode. |
would_require_approval |
bool | In audit mode, true when the command would have required approval in enforce mode. |
Host command_policy (in signer.json, never exposed over the wire): mode ("allowlist"/"denylist"/"off"), enforcement ("enforce" default, or "audit"), allow (regexes), deny (regexes), require_approval (regexes), shell_parse (bool, default true — set false to opt out). When parsing is on, the command is parsed as POSIX sh (via mvdan.cc/sh/v3) before regex evaluation: each simple command is evaluated separately, and only a small surface is accepted — simple commands with statically known words, pipes, &&/||/;, fd→fd redirects (2>&1), ( )/{ } grouping, if and while/until. Every other shell construct (command/process substitution, parameter and arithmetic expansion, bash-only $'…'/$"…" quoting (use plain quotes: a shell without them reads different commands), for/select/case/[[ ]]/let/(( )), functions, file redirects and here-documents, environment mutations) is rejected fail-closed in enforce mode or reported as a warning in audit mode, with a reason that names the construct; put such logic in a script on the host (ARCHITECTURE.md §"Anchoring, shell metacharacters & shell_parse"). Pipe commands are allowed but every stage must pass the policy independently. With shell_parse: false the command is matched as a whole string, so a chained command (kubectl get pods; rm -rf /etc) can ride past a prefix allowlist entry — only opt out when the target is not a POSIX shell. One-shot is signer-authoritative via force-command. Every ssh_session_exec is broker-preflighted against the current signer policy, so policy reloads affect already-open sessions: target and bastion access, end-user groups, sudo, sudo_user and PTY are revalidated; the broker also rejects a session command if the host's physical SSH route (addr/user/host_key/jump) changed since the session opened. mode=exec commands are checked when the host has command policy, and session shell/pty commands are rejected once the host has an active command policy.
Composable policies by group (config-only): a named library command_policies plus group_command_policies (group → [policy names], reserved group _default applies to every host) lets a host's effective policy be the composition of its inline command_policy and the policies of all its groups — additive: deny wins, allow is a union, require_approval is a union, and shell_parse is on by default (the effective policy parses unless every contributing policy opts out with shell_parse: false). Enforcement composes conservatively: any "enforce" policy makes the effective policy enforcing; a host is audit-only only when every restricting policy is "audit". This is transparent over the wire: matched_rule may carry the rule of any contributing policy (deny:…, allow:…, allowlist:no-match).
Error responses:
| Status | Condition |
|---|---|
400 Bad Request |
Malformed JSON body or invalid public_key format; or control/whitespace characters in end_user, end_user_context, role, purpose, session_mode, sudo_user, any k8s_* field, or in the resolved caller identity (rejected before any audit emission); or, for a k8s request, command not equal to the canonical action, or any SSH-only knob set (sudo, sudo_user, pty, file_transfer, session_mode) or a role/purpose other than target/oneshot — k8s intents are stateless one-shot API calls and these knobs are rejected (audited denied) rather than silently ignored; or an identity/intent identifier (host, end_user, sudo_user, k8s_*, …) longer than 1 KiB (#572). |
401 Unauthorized |
Missing or invalid mTLS client certificate. |
403 Forbidden |
Host not in caller's allowed groups (RBAC); or policy denied (sudo not allowed, PTY not allowed, file transfer not allowed (allow_file_transfer=false), invalid sudo_user, shell/pty session requested on a host with command_policy, role: "bastion" requested for a host with a command_policy, on_behalf_of from a non-trusted forwarder, etc.). Note: a ttl_seconds above the host cap is silently clamped to the cap, not rejected. |
405 Method Not Allowed |
Request method is not POST. |
429 Too Many Requests |
Per-CN rate limit exceeded (sign_rate_limit_per_min > 0). Keyed on the authenticated mTLS CN, checked before the body is parsed; carries a Retry-After header (seconds). Not audited per rejection by design. |
502 Bad Gateway |
The policy allowed the intent but the signer could not sign: CA backend failure (ssh-agent unreachable, Azure Key Vault Sign error, local key), a sealed-exec preflight on a host with sealed_exec while the signer has no envelope_key, or (k8s) a failed TokenRequest. The body is a generic host "<name>": certificate signing failed / cluster "<name>": token minting failed — the agent socket path, vault details and SA binding stay in the signer's log and audit record (outcome error, not denied). The broker treats it as an upstream failure. |
Approval-required response (200 OK, no certificate): when the command matches
command_policy.require_approval and approved is not set (or not from a trusted
forwarder), the signer returns 200 with decision.require_approval=true and no
certificate. The control plane interprets this and orchestrates approval; a
direct broker treats it as an error. In command_policy.enforcement: "audit",
the signer does not create an approval gate; the decision carries
would_require_approval=true and warning while allowing the command.
GET /v1/hosts also honors X-On-Behalf-Of (header) from trusted forwarders,
so the control plane can fetch the host list filtered by the original broker's groups.
Audit outcomes: issued on success, denied on any authorization or policy failure, approval-required when a command needs approval and was not issued, dry_run_allowed / dry_run_denied for dry-run simulations, end_user_unverified when a require_verified_end_user caller's end user could not be verified (403), frozen_denied when the caller or end user is frozen by the kill switch, error when signing fails on the signer's side such as a CA-backend failure (generic 502), and self_approved as a supplementary marker after issued when an opted-in caller approved its own command. The full list is in the Outcome values table under the audit log.
GET /v1/hosts¶
Return the connectivity data and capabilities for all hosts accessible to the
caller. The broker calls this endpoint at startup and periodically
(hosts_refresh_seconds) to cache the host list for ssh_list_servers. In
remote mode, new ssh_execute and ssh_session_open calls also refresh this
endpoint immediately before building SSH hops; if the refresh fails, the broker
fails closed instead of using a potentially stale route.
Auth: mTLS client certificate.
No request body.
Response body (200 OK):
JSON object mapping host name → host info object.
| Field | Type | Description |
|---|---|---|
addr |
string | SSH server address in host:port form. |
user |
string | SSH account on the remote host. |
host_key |
string | Pinned host key in authorized_keys format. No TOFU — the broker rejects any key that does not match. |
jump |
string | Logical name of the bastion host to use as ProxyJump. Empty if the host is direct. |
allow_sudo |
bool | Whether NOPASSWD sudo elevation is allowed on this host. |
allow_pty |
bool | Whether PTY allocation is allowed on this host. |
allow_file_transfer |
bool | Whether the file-transfer tools (ssh_put_file / ssh_get_file) are allowed on this host. |
groups |
[]string | RBAC groups the host belongs to. The broker uses them to filter the host list shown to an end user by the user's OIDC groups (consistent with the per-user check at signing time). |
Notes:
- The response is filtered by the caller's
allowed_groupsin thecallerssection ofsigner.json. Oncecallersis non-empty it is default-deny (v2.0.0): a caller with no entry receives no hosts. An unlisted CN inherits a reserved"_default"entry if present (add one with groups to grant unlisted CNs a baseline). An empty/absentcallersleaves the caller unrestricted. - The response is also filtered by each host's
allowed_callers(v1.13.0): a host is omitted when itsallowed_callersis non-empty and does not include the caller CN, matching the per-host authorizationPOST /v1/signenforces. Previously/v1/hostsapplied only the group filter and leaked the connectivity of hosts the CN could not sign for. - Policy-internal fields (
principal,source_address,allowed_callers,max_ttl_seconds, command policy, etc.) are never returned. Group names are labels, not secrets; the broker already assertsend_user_groups, so exposing them adds no trust.
Error responses:
| Status | Condition |
|---|---|
401 Unauthorized |
Missing or invalid mTLS client certificate. |
403 Forbidden |
X-On-Behalf-Of header sent by a caller that is not a trusted forwarder, or the caller / forwarder is frozen (subject is frozen; audited frozen_denied). |
405 Method Not Allowed |
Request method is not GET. |
GET /v1/clusters¶
Return the connectivity data for the Kubernetes clusters accessible to the
caller (present only when the signer is configured with a kubernetes.clusters
block; otherwise the response is an empty object). Mirrors GET /v1/hosts for
the k8s target: the broker caches it at startup and refreshes it alongside the
host list, so k8s_list_clusters and the k8s_* tools know the reachable
clusters. See Kubernetes target.
Auth: mTLS client certificate. Honors X-On-Behalf-Of from trusted
forwarders (the control plane forwards it).
No request body.
Response body (200 OK):
JSON object mapping cluster name → cluster info object.
| Field | Type | Description |
|---|---|---|
api_server |
string | Cluster API server URL (https://host:port). |
ca_cert_pem |
string | PEM bundle of the cluster CA (public material; the broker pins it). The signer parses ca_cert at (re)load and publishes only its re-encoded CERTIFICATE blocks — a file that is empty, does not parse, or carries any other block type (e.g. a private key) fails the load. |
groups |
[]string | RBAC groups the cluster belongs to, used for the same per-user filtering as hosts. |
extra_resources |
[]object | Per-cluster CRD resource definitions (resource, group, version, kind, namespaced) extending the curated core table. |
Notes:
- Filtered by the caller's group RBAC (same
callers/_defaultsemantics as/v1/hosts) and each cluster'sallowed_callers. - Policy-internal fields (
token_file,sa_bindings,rules,token_ttl_seconds) are never returned.
Error responses:
| Status | Condition |
|---|---|
401 Unauthorized |
Missing or invalid mTLS client certificate. |
403 Forbidden |
X-On-Behalf-Of header sent by a caller that is not a trusted forwarder, or the caller / forwarder is frozen (subject is frozen; audited frozen_denied, #828). |
POST /v1/reload¶
Hot-reload signer.json without restarting the service. Atomically replaces
in memory the hosts policy, the Kubernetes clusters (kubernetes.clusters),
command_policies / group_command_policies, callers, reload_callers,
trusted_forwarders, sign_rate_limit_per_min, end_user_oidc,
max_ttl_seconds, envelope_key, the CA key (ca_key), and all per-group CA
keys (ca_keys).
If the new config is invalid, the current state is preserved intact.
Auth: mTLS client certificate. The CN must be listed in reload_callers.
No request body.
Response body (200 OK):
| Field | Type | Description |
|---|---|---|
status |
string | Always "ok" on success. |
hosts |
int | Number of hosts loaded from the new config. |
Notes:
listen, TLS material,audit_log/audit_key/audit_fail_mode,redact,state_db,monitor_listen,max_grant_ttl_secondsandauto_reload_secondsare read once at startup and require a full restart — a reload silently keeps the old value. See OPERATIONS.md §3.- If
reload_callersis empty insigner.json, this endpoint always returns403. HTTP reload is effectively disabled;SIGHUPstill works locally. - Alternative trigger:
kill -HUP <pid>(or./signer.sh restart). TheSIGHUPhandler bypasses thereload_callersallowlist because it is local to the host.
Error responses:
| Status | Condition |
|---|---|
401 Unauthorized |
Missing or invalid mTLS client certificate. |
403 Forbidden |
Caller CN not in reload_callers, or reload_callers is empty. |
429 Too Many Requests |
Unauthorised caller over its per-CN budget (sign_rate_limit_per_min > 0): the denial is not audited (see admin denial budget); Retry-After header. |
500 Internal Server Error |
Config file unreadable, JSON invalid, CA key(s) unreadable or unreachable (AKV). Current state preserved. |
405 Method Not Allowed |
Request method is not POST. |
Audit outcomes: reloaded on success, reload-denied on 403, reload-failed on 500.
Admin denial budget¶
Every admin-tier denial (reload-denied, policy-denied, grant-denied,
policy-read-denied) is a signed and fsynced audit record, so an
unauthorised mTLS client looping an admin endpoint could grow and rotate the
log and serialise every legitimate sign behind its fsyncs. The denials
therefore draw on the caller's sign_rate_limit_per_min bucket (same bucket
and limit as POST /v1/sign, keyed on the authenticated CN): the first
limit denials per minute are audited and answered 403 as documented, the
excess gets 429 + Retry-After and, like a rate-limited sign request, is
deliberately not audited. Authorised callers are never gated by this budget;
with sign_rate_limit_per_min unset every denial is audited.
GET /v1/hosts and GET /v1/clusters frozen-subject denials (#828) use a
separate budget: they are always answered 403 subject is frozen (never
429), and only the first sign_rate_limit_per_min frozen_denied records per
minute per frozen subject are written (shared by both endpoints; unset =
every denial audited). The bucket is keyed on the frozen subject, not the
caller CN, so a frozen broker polling through the control plane cannot drain
the control plane's /v1/sign budget.
POST /v1/policy/hosts/{host}/allow · DELETE /v1/policy/hosts/{host}/allow¶
Add (POST) or remove (DELETE) a single command_policy allow regex for
{host}, mutating signer.json and the running policy together — without a hand
edit or a separate reload. The signer validates by building the new state
(CompileHostPolicies + CA load) before persisting or applying: an invalid
regex, an unknown host, or a config that would not compile is rejected and nothing
changes. On success the file is written atomically (temp+rename; top-level keys and
other hosts preserved verbatim) and the whole hot-reloadable state is swapped in
one step — the same swap POST /v1/reload performs, so if the file had been
edited but not yet reloaded (a new sign_rate_limit_per_min, a caller's
require_verified_end_user, a changed end_user_oidc), the mutation applies
those too rather than a hybrid of the new tables with the old limit/verifier
(#466). Adding the
first allow rule turns the host into an allowlist; removing the last leaves an
empty allowlist (which denies every command — by design).
Auth: mTLS client certificate; the CN must be in reload_callers (same trust
tier as /v1/reload). Request body: { "pattern": "<RE2 regex>" }.
Response (200 OK): { "status": "ok", "host": "<host>", "hosts": <int> }.
| Status | Condition |
|---|---|
401 Unauthorized |
Missing or invalid mTLS client certificate. |
403 Forbidden |
Caller CN not in reload_callers. |
429 Too Many Requests |
Unauthorised caller over its admin denial budget; not audited. |
400 Bad Request |
Missing/invalid body or an invalid regex. |
404 Not Found |
Unknown host. |
409 Conflict |
Pattern already present (add) or absent (remove) — no change. |
500 Internal Server Error |
The edited config failed to build (validation); nothing persisted. |
Audit outcomes: policy-changed on success, policy-denied on 403,
policy-failed on a rejected change (recorded as policy-allow-add /
policy-allow-remove with the pattern). CLI: broker-ctl policy add|remove
--host <h> --allow <regex>.
Runtime grants — POST /v1/policy/hosts/{host}/grants · GET /v1/policy/grants · DELETE /v1/policy/grants/{id}¶
A runtime grant temporarily widens a host's allowlist without editing
signer.json: a set of allow patterns that expire on their own after a TTL.
Unlike the mutation API above (which edits the durable file), grants are a
dynamic overlay on the file baseline — "let this command through on web01
for the next 2 hours" without a config change. With state_db set (the
production recommendation) they are write-through SQLite and restored at
startup; they expire on TTL or revoke. Without state_db they live in
memory only and are lost on a signer restart. They survive config reloads
either way.
Widen-only, by construction. A grant carries only allow patterns (never
deny / require_approval), and the signer applies it only on a host that is
already allowlist-active. On a default-allow or denylist-only host a grant is a
no-op — and injecting an allowlist there would invert the host to default-deny —
so the signer refuses it (409). A grant can never override a baseline deny
(deny still wins) nor remove an approval requirement. Creation is operator-only
(reload_callers); the broker/agent can never create one. Every operation is in
the signed audit log.
Auth (all three): mTLS client certificate; the CN must be in reload_callers.
Create — POST /v1/policy/hosts/{host}/grants¶
Request body:
| Field | Type | Required | Meaning |
|---|---|---|---|
allow |
[]string |
yes | RE2 allow patterns to grant (≥1). |
ttl_seconds |
int |
yes | Lifetime; must be > 0 and ≤ max_grant_ttl_seconds if that cap is set. |
caller |
string |
no | Scope: only this broker CN benefits ("" = host-wide). |
end_user |
string |
no | Scope: only this OIDC end user benefits ("" = host-wide). |
# Host-wide grant for 2 hours (mTLS client cert whose CN is in reload_callers)
curl --cert admin.crt --key admin.key --cacert signer-ca.crt \
-X POST https://signer:9443/v1/policy/hosts/web01/grants \
-d '{"allow":["^systemctl restart nginx$"],"ttl_seconds":7200}'
# → 201 Created
# {"id":"42d1eabd7c73b474c85e75a7","host":"web01","expires_at":"2026-06-19T14:00:00Z"}
Response (201 Created): { "id": "<hex>", "host": "<host>", "expires_at": "<RFC3339>" }.
| Status | Condition |
|---|---|
201 Created |
Grant accepted and live. |
401 Unauthorized |
Missing or invalid mTLS client certificate. |
403 Forbidden |
Caller CN not in reload_callers. |
429 Too Many Requests |
Unauthorised caller over its admin denial budget; not audited (create and revoke alike). |
400 Bad Request |
Empty allow, ttl_seconds ≤ 0, an invalid regex, or ttl_seconds above max_grant_ttl_seconds. |
404 Not Found |
Unknown host. |
409 Conflict |
Host is not allowlist-active (a widen-only grant would be a no-op / would invert it), or the grant's caller/end_user scope is currently frozen (a grant cannot be created for a subject the kill switch has frozen). |
List — GET /v1/policy/grants¶
Returns the active (non-expired) grants. Operator-only (the list reveals the current widening posture).
curl --cert admin.crt --key admin.key --cacert signer-ca.crt \
https://signer:9443/v1/policy/grants
# → 200 OK
# [{"id":"42d1...","host":"web01","allow":["^systemctl restart nginx$"],
# "granted_at":"2026-06-19T12:00:00Z","expires_at":"2026-06-19T14:00:00Z"}]
#
# Learned approval waivers appear in the same list, but carry waive_approval
# plus the approval provenance and subject scope:
# [{"id":"7b91...","host":"web01","waive_approval":["^systemctl restart nginx$"],
# "caller":"broker-1","end_user":"alice","approver":"admin","approval_id":"ap1",
# "granted_at":"2026-06-19T12:00:00Z","expires_at":"2026-06-19T14:00:00Z"}]
Revoke — DELETE /v1/policy/grants/{id}¶
Removes a grant immediately (the command is denied again at once). 404 if the id
is unknown (already expired/revoked).
curl --cert admin.crt --key admin.key --cacert signer-ca.crt \
-X DELETE https://signer:9443/v1/policy/grants/42d1eabd7c73b474c85e75a7
# → 200 OK {"status":"ok","id":"42d1eabd7c73b474c85e75a7"}
Audit outcomes: grant-created / grant-revoked on success, grant-denied
on 403, grant-failed on a rejected create or an unknown revoke (recorded as
grant <id> with the allow patterns in policy_rule).
Scope examples (each is one POST body field):
| Intent | Body fragment | Who it applies to |
|---|---|---|
| Host-wide | (omit caller/end_user) |
Any caller/user on the host. |
| One broker | "caller":"broker-1" |
Only requests from CN broker-1. |
| One end user | "end_user":"alice" |
Only requests carrying end user alice. |
Worked scenario (incident response). An allowlist host web01 denies
systemctl restart nginx. During an incident an operator grants it for 2 hours;
the agent's next ssh_execute (or a --dry_run preview) is now allowed; two hours
later the grant expires and the command is denied again — no second action, and the
durable signer.json was never touched. CLI equivalents:
broker-ctl policy grant --host web01 --allow '^systemctl restart nginx$' --ttl 2h,
broker-ctl policy grants, broker-ctl policy revoke <id>.
Approve-and-learn waivers (the second kind of grant)¶
A grant can also carry a waive_approval dimension: patterns whose
require_approval is suppressed for the TTL. This is the approve-and-learn
overlay — distinct from allow:
allowwidens what is permitted (only on an allowlist-active host).waive_approvalun-gates an already-allowed command (skips the human approval for the TTL). It never allows anything new and never overrides adeny, so it has no inversion risk and applies on any host (including default-allow hosts that carry arequire_approvalrule). A learn-minted waiver is bound to the exact command, elevation, broker caller, and end user that were approved — approving the non-sudoform does not waive thesudo(root) form, and another broker/end-user pair still requires its own approval. Re-learning the same command for the same scope refreshes the single waiver instead of accumulating duplicates.
Waivers are not created through this endpoint — they are minted by the signer as
a side-effect of an approved sign that asked to learn (see
POST /v1/approvals/{id} with learn). They live in the same
store, so they appear in GET /v1/policy/grants (with a waive_approval field) and
are revoked by DELETE /v1/policy/grants/{id} like any grant. Audit outcomes:
approval-waiver-created / approval-waiver-failed, carrying the originating
approval_id and approver.
Kill switch — POST /v1/freeze · POST /v1/unfreeze · GET /v1/revocations¶
Freeze a subject so it gets no new certificate (and, for a caller CN, no
connectivity — see Enforcement points below), and brokers kill its live
sessions (#117). A freeze subject is a { "kind": ..., "value":
... } pair where kind is one of caller (broker mTLS CN), end_user,
session_id, or serial.
POST /v1/freeze(mTLS, CN inreload_callers). Body:{ "kind": "caller", "value": "broker-1", "reason": "incident-4821" }(reasonoptional). Freezing acaller/end_useralso revokes that subject's runtime grants and approve-and-learn waivers.valueandreasonmust not contain control/whitespace characters (audit-stream safety) →400otherwise. Aserialvalue must be the decimal certificate serial (a base-10 uint64; no sign, no hex) →400"serial must be a decimal certificate serial" otherwise; it is stored canonicalised ("0012345"is stored as"12345"), and/v1/unfreezeaccepts the same spellings. Response:{ "status": "ok", "newly_frozen": true, "grants_revoked": 1 }. When the signer has nostate_dbthe freeze would be lost on restart (fail-open), so it is refused with409 Conflictunless the body sets"allow_volatile": true(v2.0.0) to accept a memory-only freeze. Answers500when the freeze could not be stored (nothing is frozen), or when it was applied but a follow-up step failed: the durability checkpoint (subject frozen (enforced), but durability checkpoint failed) or the revocation of the subject's grants (subject frozen, but revoking its grants failed). In the latter two cases the freeze is already enforced in memory; the body says which step failed.POST /v1/unfreeze(mTLS,reload_callers). Body:{ "kind": "caller", "value": "broker-1" }. Response:{ "status": "ok", "was_frozen": true }. Answers500when the freeze cannot be removed from the store, or when it was removed but sweeping the subject's residual grants failed (subject unfrozen, but sweeping residual grants failed); the body says which step failed.GET /v1/revocations(mTLS, any authenticated caller — operational data a broker needs, likeGET /v1/hosts). Returns the current freeze set:[{ "kind": "caller", "value": "broker-1", "reason": "...", "frozen_by": "admin", "frozen_at": "2026-07-09T06:00:00Z" }]. Brokers poll it to force-close matching live sessions. Provenance isreload_callers-only: the free-textreasonand the freezing admin's CN (frozen_by) are returned only to the admin tier; an ordinary broker sees justkind,value, andfrozen_at(all it needs to match sessions).
Enforcement points: a frozen subject (caller CN or end user) is rejected at
POST /v1/sign (audited frozen_denied); GET /v1/hosts checks only the
caller — the peer CN and, behind a trusted forwarder, the on_behalf_of
CN — so an end_user freeze has no discovery-time enforcement point and
bites at /v1/sign. The freeze set is persisted in state_db
fail-closed — the signer refuses to start if it cannot load the set, and
without state_db freezes do not survive a restart. CLI: broker-ctl freeze,
broker-ctl unfreeze, broker-ctl revocations.
GET /v1/policy/hosts¶
Return the full host-policy table — the current in-memory state, so it
reflects hot-reloads and policy mutations without a restart. The response uses
exactly the schema of the hosts object in signer.json, including the
internal issuance-policy fields that GET /v1/hosts
deliberately withholds from brokers: principal, source_address,
max_ttl_seconds, allow_as_bastion, allowed_callers, allowed_sudo_users
and command_policy. This is the read counterpart of the policy mutation
APIs, and what broker-ctl host list --remote consumes.
Auth: mTLS client certificate whose CN is in reload_callers — the same
"may change policy" trust tier as POST /v1/reload and the
mutation APIs, because reading the complete policy is as sensitive as changing
it. No X-On-Behalf-Of handling (admin tier is direct-CN only). An empty
reload_callers disables the endpoint (403 for everyone).
No request body.
Response body (200 OK): JSON object mapping host name → the full host
policy object (see signer.json reference).
Errors: 401 no client certificate · 403 CN not in reload_callers ·
429 unauthorised caller over its admin denial budget.
Audit: every read attempt is recorded — outcome policy-read (with the
host count) on success, policy-read-denied on 403 (a 429 is not audited). A
full policy dump is security-sensitive, so unlike GET /v1/hosts this
endpoint is audited.
Control Plane API¶
Service: cmd/control-plane
Transport: HTTPS + mutual TLS (mTLS)
Default listen address: :7443 (configurable via listen in control-plane.json)
Auth: every request requires a valid TLS client certificate signed by the
configured client_ca, with a non-empty CN free of control characters (an empty or
malformed CN is rejected, not treated as an identity). The CN identifies the broker
(for /v1/sign, /v1/hosts, /v1/sign/result) or the approver (for /v1/approvals).
Role separation (signing path). /v1/sign, /v1/hosts, and /v1/sign/result
are restricted to brokers: with a non-empty sign_callers list only those CNs are
allowed; with no list, any CN is allowed except one in approval.callers (an
approver is not a broker — denied the sign path, secure by default). This prevents an
approver certificate, signed by the same client_ca, from originating signing requests.
The control plane speaks the same wire protocol as the signer for /v1/sign,
/v1/hosts, and /v1/clusters (it forwards to the signer, adding the broker's
identity via X-On-Behalf-Of), and adds the approval endpoints below. The CA key
lives only in the signer. On the /v1/sign path a Kubernetes request
(target_type=k8s) returns a k8s_token instead of a certificate, and a
require_approval k8s action follows the same 202 + polling approval flow — the
approver sees the canonical action.
POST /v1/sign (control plane)¶
Same request body as the signer POST /v1/sign. The control plane
forwards to the signer on behalf of the calling broker (on_behalf_of = broker CN).
Responses:
| Status | Meaning |
|---|---|
200 OK |
Issued (allowed, no approval needed) — body is the signer's WireResponse with certificate. Or, for dry_run, the decision. |
202 Accepted |
Approval required (command policy require_approval, or a behavior anomaly in enforce mode). Body: {"approval_id": "...", "status": "pending"}. The broker must poll /v1/sign/result/{id}. |
400 Bad Request |
Malformed JSON body or invalid public_key. |
401 Unauthorized |
Missing or invalid mTLS client certificate. |
403 Forbidden |
Denied by policy/RBAC at the signer; or the CN is not authorised for the sign path (sign_callers, or an approver CN). |
429 Too Many Requests |
Behavioral rate limit exceeded for the subject (behavior.mode=enforce, audited rate-limited). Or the signer answered 429 (its sign_rate_limit_per_min bucket, which behind the control plane is keyed on the control plane's CN): relayed with the signer's Retry-After and text on the live and dry_run paths, not audited (like the signer itself), counted in controlplane_signer_rate_limited_total (#662). |
500 Internal Server Error |
could not create approval request (approval registry / state_db failure). A signer fail-closed 500 is relayed as 502 + an audited error (see the 502 row). |
502 Bad Gateway |
The signer answered 5xx — a CA-backend failure (#465), a k8s token-mint failure (#455) or an outage — relayed with the signer's generic message (signing service unavailable (5xx): …) and audited error, not denied, so the broker classifies it exactly as it would talking to the signer directly. Also: signer reachable but its response carried no certificate in a non-approval state (unexpected signer condition). |
dry_run requests (pure dry-runs, sealed-exec/ssh_session_exec preflights, and the
dry-run the guardrails run before escalating an anomaly) follow the same split: a signer
outage is 502 + an audited error, a signer rejection is 403 + an audited denied,
both records carrying dry_run: true (the guardrail record carries the anomaly
instead) (#660).
Behavioral guardrails: when behavior.mode is observe or enforce, the
control plane checks each request against the subject's baseline (rate spike, new
host, new command). In observe it only audits (outcome=anomaly); in enforce
a rate excess returns 429 and other anomalies escalate to approval (202).
An enforce-mode anomaly is not added to the subject baseline until the approval
is granted and the broker successfully collects the signer response, so retrying
the same unapproved anomaly keeps returning 202 instead of becoming normal.
Pure dry-run requests bypass the guardrails. Executable preflights
(dry_run=true, preflight=true) are checked because the broker will execute
the command if the decision is allowed. Config: behavior.mode,
behavior.rate_limit_per_min in control-plane.json. behavior.mode is
validated at startup; any value other than off, observe, or enforce is
rejected instead of disabling guardrails implicitly.
GET /v1/sign/result/{id}¶
Polled by the broker after a 202. Only the broker that created the request (same
mTLS CN) may read it.
| Status | Meaning |
|---|---|
202 Accepted |
Still pending. Body: {"status":"pending"}. Keep polling. Body is {"status":"issuing"} when another poll of the same approval is already collecting the certificate from the signer. |
200 OK |
Approved and signed — body is the WireResponse with certificate. Served once (the approval is then consumed). |
400 Bad Request |
The stored request's public key no longer parses (not reachable in practice: it was parsed when the request was created). |
403 Forbidden |
Approval denied (audited approval-denied on the first poll that observes it, not on re-polls — #746), or caller is not the request owner. Also: the signer refused the approved forward (4xx — the policy changed or the subject was frozen after the human approved); body is the signer's reason, audited denied with the approval attribution (#576). |
408 Request Timeout |
Approval expired: pending requests expire after approval.timeout_seconds from creation; approved-but-uncollected requests expire after the same TTL from the decision. Audited approval-timeout once, on the first poll that observes it. |
410 Gone |
Approval already consumed (certificate already issued). |
404 Not Found |
Unknown approval id — including requests purged from memory ~2× approval.timeout_seconds after creation. |
429 Too Many Requests |
The signer answered 429 on the approved forward (its sign_rate_limit_per_min bucket, shared by every broker behind this control plane): relayed with the signer's Retry-After and text, not audited, counted in controlplane_signer_rate_limited_total. The approval stays collectable; the broker treats it as transient like 502 (#745). |
502 Bad Gateway |
Signing after approval failed: the signer answered 5xx or was unreachable (audited error; the approval stays collectable, so the next poll retries), or its response carried no decision/certificate/token. The broker treats it as transient and keeps polling within its approval wait, giving up after 10 consecutive 502/503/429 answers (#663, #745). |
503 Service Unavailable |
audit log unavailable — the approval-granted record could not be written and the control plane runs fail-closed (audit_fail_mode: "closed"), so the credential was withheld and the approval stays collectable. Transient for the broker, like 502 (#663). |
GET /v1/approvals¶
Lists approval requests. Auth: CN must be in approval.callers.
Response (200 OK): JSON array of {id, caller, end_user, end_user_stripped, host, command, target_type, sudo, sudo_user, rule, status, created_at, decided_by, decided_at, learn_ttl} (the ephemeral public key is never exposed; learn_ttl appears only when an approve-and-learn TTL was set; end_user_stripped is a boolean present as true only when the originating broker asserted an end_user that was dropped because it is not in trusted_forwarders — learn is refused for such a request, see below; target_type is "k8s" for a Kubernetes request, whose host then names a cluster, and is omitted for SSH — the webhook notifier payload carries the same field, #664). Includes non-pending entries (approved/denied/expired) still held in memory.
POST /v1/approvals/{id}¶
Resolve a pending request. Auth: CN must be in approval.callers.
Request body: {"approve": true} (or false to deny).
Approve-and-learn (allow only): add "learn": true and "ttl_seconds": N to
also waive re-approval for this exact command for N seconds. On the next
(approved) forward to the signer, the control plane carries the learn intent and the
signer mints an approval waiver scoped to the original broker CN
and OIDC end user (honored only because the control plane is a trusted_forwarder).
So the same command from the same subject runs without prompting again until the
waiver expires; revoke it early with broker-ctl policy revoke <id>.
The end-user scope is only as good as the attribution the control plane holds:
when the originating broker is not in the control plane's trusted_forwarders
and asserted an end_user, that assertion was dropped at request time
(end_user_stripped: true in the approval), and learn is refused with 400
(the approval stays pending; approve without learn, or add the broker CN to
trusted_forwarders). Otherwise the signer would mint the waiver with an empty
end user — one that matches every end user of that broker (#451). A broker that
asserted no end user at all (a stdio broker) learns a caller-scoped waiver as before.
| Status | Meaning |
|---|---|
200 OK |
Decision recorded; body is the updated approval object. |
400 Bad Request |
learn without ttl_seconds > 0; or learn on a request whose end_user was stripped (end_user_stripped: true, broker not in trusted_forwarders) — audited approval-learn-refused, the request stays pending and a plain approve still works (#451). |
403 Forbidden |
Caller not in approval.callers; or the caller tries to decide a request it originated itself (four-eyes self-approval guard, audit outcome self-approval-rejected). |
409 Conflict |
Request not pending (already decided or expired). |
503 Service Unavailable |
audit log unavailable — an allow decision's approval-decision-allow record could not be written and the control plane runs fail-closed (audit_fail_mode: "closed"). The decision is already recorded in memory (a retry answers 409), but it is not acknowledged to the approver and no credential is released: the grant path gates on its own approval-granted record (see GET /v1/sign/result/{id} 503) and withholds the certificate/token until the log is writable again. A deny is best-effort and never answers 503. |
415 Unsupported Media Type |
Content-Type is not application/json. CSRF hardening for the browser UI: mTLS client certificates are ambient credentials, and an HTML form (enctype=text/plain) can smuggle a JSON-shaped body cross-site; requiring the JSON media type stops forms, and a cross-origin fetch carrying it is stopped by the CORS preflight (no CORS headers are served). |
Audit outcomes (control plane log): forwarded, approval-required, approval-decision-allow, approval-decision-allow-learn, approval-learn-refused, self-approval-rejected, approval-denied, approval-granted, approval-timeout, denied. The signer additionally logs approval-waiver-created when the waiver is minted.
CLI: broker-ctl approval allow <id> --learn --ttl 2h.
GET /ui/approvals · GET /ui/approvals/{id}¶
Built-in browser UI for approvers, served on the same mTLS listener.
Auth: the browser's mTLS client certificate; the CN must be in
approval.callers (same check as the API, 403 otherwise).
/ui/approvals— all requests in memory, pending first, auto-refreshing./ui/approvals/{id}— one request with its full context (caller, end user, host, command, elevation, matched rule) and, while pending, Approve / Deny buttons plus an optional approve-and-learn TTL. Decisions are same-origin JavaScript POSTs to/v1/approvals/{id}, so the audit trail, the broker/approver role separation, and the four-eyes self-approval guard apply unchanged.404for an unknown or purged id.
Every UI page is served with X-Frame-Options: DENY and
Content-Security-Policy: frame-ancestors 'none' (the decision buttons POST
with the approver's ambient mTLS certificate, so the page must never be
framed under a decoy), Cache-Control: no-store (live decision state, never
cached) and X-Content-Type-Options: nosniff.
Point approval.approval_url_template at
https://<control-plane>/ui/approvals/{id} so notification links (e.g. the
Teams card button) land on the request page.
Outbound Notifications — Notifier contracts¶
When a command requires approval, the control plane sends an outbound notification
via the configured notifier. This is a fire-and-forget POST; failure only
produces a warning and does not block the 202 response to the broker.
Notifier types¶
notifier value |
Target | Format |
|---|---|---|
log (default) |
Process log (stderr) |
Plain text line |
webhook |
webhook_url |
Raw Approval JSON |
teams |
webhook_url (Teams Incoming Webhook / Power Automate Workflow) |
Adaptive Card or MessageCard — see below |
approval.notifier is validated at control-plane startup; any value other than
log, webhook, or teams is rejected instead of falling back to log.
notifier: "teams" — payload contracts¶
The teams notifier sends a POST to webhook_url with Content-Type: application/json.
The exact payload depends on teams_format. Valid values are workflow
(default), adaptivecard (alias for workflow), and messagecard; unknown
values are rejected at startup.
Format workflow / adaptivecard (default, recommended)¶
Wraps an Adaptive Card v1.4 in the Power Automate Workflow message envelope:
{
"type": "message",
"attachments": [
{
"contentType": "application/vnd.microsoft.card.adaptive",
"contentUrl": null,
"content": {
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.4",
"body": [
{ "type": "TextBlock", "size": "Medium", "weight": "Bolder",
"text": "infrabroker — Approval Required", "color": "Warning" },
{ "type": "TextBlock",
"text": "An AI agent action is waiting for human approval before a certificate is issued." },
{ "type": "FactSet", "facts": [ ... ] }
],
"actions": [
{ "type": "Action.OpenUrl", "title": "View request", "url": "<rendered approval_url_template>" }
]
}
}
]
}
The actions array is only present when approval_url_template is non-empty.
Format messagecard (legacy M365 Connectors — deprecated by Microsoft)¶
{
"@type": "MessageCard",
"@context": "http://schema.org/extensions",
"themeColor": "FFA500",
"summary": "Approval required: <command> on <host>",
"sections": [
{
"activityTitle": "infrabroker — Approval Required",
"activitySubtitle": "An AI agent action is waiting for human approval.",
"facts": [ ... ],
"markdown": true
}
],
"potentialAction": [
{ "@type": "OpenUri", "name": "View request",
"targets": [{"os": "default", "uri": "<rendered approval_url_template>"}] }
]
}
potentialAction is only present when approval_url_template is non-empty.
Facts included in every card¶
| Fact name | Source field | Always present |
|---|---|---|
Approval ID |
approval.id |
Yes |
Status |
approval.status |
Yes |
Created |
approval.created_at (RFC3339 UTC) |
Yes |
Host (Cluster when target_type is k8s, #664) |
approval.host |
Yes |
Command |
approval.command |
Yes |
Caller (broker) |
approval.caller |
Yes |
End user |
approval.end_user |
Only if non-empty |
Elevation |
derived from sudo/sudo_user |
Only if sudo=true |
Policy rule |
approval.rule |
Only if non-empty |
Security note: the card never contains the ephemeral public key or any field from the internal
WireRequest. Thereqfield ofApprovalis unexported and excluded from serialization by design.
approval_url_template¶
An optional URL string where {id} is replaced with the approval ID at
notification time. Point it at the control plane's approval UI
(https://<control-plane>/ui/approvals/{id}) so each notification links
straight to the Approve / Deny page for that request — see
Approval UI.
Example: "https://cp.example:7443/ui/approvals/{id}"
Broker HTTP API¶
Service: infrabroker serve-http (legacy broker)
Transport: HTTPS + mutual TLS (mTLS)
Auth: mTLS client certificate. The CN becomes Caller.ID in the audit log.
POST /v1/ssh_run¶
Execute a one-shot SSH command on a managed host. The broker requests an ephemeral certificate from the signer, opens the SSH connection, runs the command, and discards the credential — all within the request lifetime.
Auth: mTLS client certificate.
Content-Type: application/json
Max body size: 64 KiB
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
host |
string | ✓ | Logical host name. Must be known to the signer. |
command |
string | ✓ | Command to execute on the remote host. |
ttl_seconds |
int | Requested certificate TTL in seconds. | |
sudo |
bool | Elevate with sudo -n (NOPASSWD). Requires allow_sudo: true on the host. |
|
sudo_user |
string | Target user for sudo. Empty = root. |
|
pty |
bool | Allocate a PTY for the command. Requires allow_pty: true on the host. When true, stderr in the response will be empty (stdout and stderr merge in the PTY). |
Response body (200 OK):
| Field | Type | Description |
|---|---|---|
stdout |
string | Standard output of the command. |
stderr |
string | Standard error. Empty when pty: true. |
exit_code |
int | Remote process exit code. A non-zero value is not an API-level error. |
serial |
uint64 | Certificate serial for audit log correlation with the signer log and sshd. |
warnings |
[]string | Optional advisory warnings, e.g. command-policy audit mode would have denied or required approval in enforce mode. |
Error responses:
| Status | Condition |
|---|---|
400 Bad Request |
Malformed JSON body, or an empty command. |
400 Bad Request |
Input validation (the same as the MCP tools): a NUL byte in host, command or sudo_user, a host or sudo_user over 1024 bytes, or a command over 64 KiB. The body names the field. Rejected before any certificate is requested. |
401 Unauthorized |
Missing or invalid mTLS client certificate. |
403 Forbidden |
Policy/authorization denial (RBAC, sudo/PTY not allowed, command policy, …). The error text describes the denial. |
404 Not Found |
Host not known to the broker. |
405 Method Not Allowed |
Request method is not POST. |
429 Too Many Requests |
The signing service answered 429 (sign_rate_limit_per_min exhausted); the signer's Retry-After is relayed (#662). |
502 Bad Gateway |
Upstream failure: SSH dial/exec error, or the signing service unreachable / returning 5xx. The body is a generic upstream failure (internal addresses are not leaked; the full error is in the audit log). |
MCP HTTP API¶
Service: infrabroker serve-mcp-http (legacy mcp-broker-http)
Transport: HTTPS (server-only TLS, no mTLS — authentication is via bearer token)
Default listen address: :8443 (configurable via listen in config.json)
Auth: OIDC JWT bearer token, validated locally against the issuer's JWKS.
GET /.well-known/oauth-protected-resource¶
Protected Resource Metadata endpoint (RFC 9728). MCP clients fetch this document to discover the Authorization Server (OIDC issuer) and initiate the OAuth2 Authorization Code + PKCE flow before connecting.
Auth: None — this endpoint is intentionally public.
No request body.
Response body (200 OK):
| Field | Type | Description |
|---|---|---|
resource |
string | Canonical URL of this resource server (resource_url from config.json). |
authorization_servers |
[]string | List containing the configured OIDC issuer URL. |
scopes_supported |
[]string | Required scopes from oauth.required_scopes in config.json. |
bearer_methods_supported |
[]string | Always ["header"]. |
resource_name |
string | Always "infrabroker (MCP)". |
MCP Streamable HTTP — tools¶
All paths except /.well-known/oauth-protected-resource are handled by the MCP
Streamable HTTP transport (go-sdk).
Auth: Authorization: Bearer <OIDC JWT>
If the token is missing or invalid, the server responds with:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="<resource_url>/.well-known/oauth-protected-resource"
Token validation (performed locally on every request):
| Check | Detail |
|---|---|
| Signature | Verified against the JWKS endpoint (cached at startup, auto-rotated). No round-trip to the IdP per request. |
| Claims | iss, aud, exp validated. With max_token_age_seconds > 0, iat is required and validated — a token without a numeric iat is rejected (fail-closed). |
| Scopes | All scopes in oauth.required_scopes must be present. |
| Identity | user_claim (e.g., preferred_username or sub) → Caller.ID → broker audit log. |
| Groups | groups_claim (if configured) → Caller.Groups → forwarded to signer as end_user_groups for per-user RBAC. Fail-closed: a token without the configured claim is rejected (401); an empty list is forwarded as-is (denies every host). |
MCP sessions: the caller (identity, groups, context_claim and the
forwarded raw token) is derived from the token of each tool call's own
request, not from the token presented at initialize: a client that refreshes
its token on an existing Mcp-Session-Id is authorised with the new token's
claims from the next call on (a group removed at the IdP stops granting access
as soon as the client presents a token without it). A token for a different
user on an existing session is refused with 403 (the session is bound to the
user that created it). A session that receives no request for 30 minutes is
closed (404 on its next use; the client must re-initialise); a long-running tool
call does not count as idle. Live SSH sessions belong to the user
(Caller.ID), not to the MCP session, so they survive both a token refresh and
an MCP re-initialisation.
Tool: ssh_list_servers¶
List the SSH hosts accessible to the caller. When the OIDC token carries
groups (groups_claim), the list only includes hosts sharing at least one of
the user's groups — the same filter the signer applies at signing time, so the
model is never offered a host it cannot use. Callers without groups (stdio,
mTLS) see every host.
Parameters: none.
Returns: an object {"servers": [...]} whose array elements are described
below. Connectivity data (addr, user, host_key) is not exposed to the
model — only the logical name and capabilities.
| Field | Type | Description |
|---|---|---|
name |
string | Logical host name. |
allow_sudo |
bool | Whether sudo elevation is available on this host. |
allow_pty |
bool | Whether PTY allocation is available on this host. |
allow_file_transfer |
bool | Whether the file-transfer tools (ssh_put_file / ssh_get_file) are available on this host. |
jump |
string | Bastion host name. Empty if direct. |
Note: always call ssh_list_servers first to discover available hosts and
their capabilities before attempting to execute commands.
Tool: ssh_execute¶
Execute a single command on a host. Issues a one-shot certificate with
force-command baked in. The credential is discarded after the command completes.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
server |
string | ✓ | Logical host name. |
command |
string | ✓ | Command to run on the remote host. Must not contain \n or \r (the signer rejects it); compose with ; or && instead. |
sudo |
bool | Elevate via sudo -n (NOPASSWD). Do not retry if allow_sudo is false. |
|
sudo_user |
string | Sudo target user. Empty = root. |
|
pty |
bool | Allocate a PTY. stderr will be empty. Do not use if allow_pty is false. |
|
ttl_seconds |
int | Certificate TTL override. Defaults to the host policy maximum. | |
dry_run |
bool | Simulate: resolve the host policy and return the decision (allow/deny, approval requirement, matched rule, force-command, TTL) without connecting or executing. |
Returns:
| Field | Type | Description |
|---|---|---|
stdout |
string | Command standard output. |
stderr |
string | Standard error. Empty when pty: true. |
exit_code |
int | Remote process exit code. Non-zero is not a tool error. |
serial |
uint64 | Certificate serial for audit correlation. |
warnings |
[]string | Optional advisory warnings, e.g. command-policy audit mode would have denied or required approval in enforce mode. |
decision |
object | Present only on a dry_run, instead of executed output. Carries allowed, reason_code, reason, require_approval, matched_rule, enforcement, force_command, ttl_seconds, warning and would_deny. reason_code is one of allowed, needs_approval, command_denied, allowlist_no_match, shell_parse_error or denied; branch on it to self-correct (see USAGE.md §2.7). |
With dry_run: true the tool returns the rendered policy decision as text
([dry-run] ALLOWED / [dry-run] DENIED: <reason> plus rule, force-command,
and TTL) instead of execution output, and the same decision as the structured
decision object above.
Tool: ssh_session_open¶
Open a persistent SSH session (connection reuse). Returns a session_id to use
with ssh_session_exec and ssh_session_close. One certificate is issued per
session (no force-command unless the host has sealed_exec, where it is
infrabroker-shim <host>).
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
server |
string | ✓ | Logical host name. |
mode |
string | Session mode. One of "exec" (default), "shell", "pty". |
|
sudo |
bool | Elevate the session. | |
sudo_user |
string | Sudo target user. Empty = root. |
|
ttl_seconds |
int | Certificate TTL override. |
Session modes:
| Mode | Description |
|---|---|
exec |
Each ssh_session_exec call runs in an isolated channel. stdout/stderr are separate. Best for automation and scripting. |
shell |
A single stateful /bin/sh process. cd, variables, and environment state persist across calls. Not suitable for interactive programs that require input or binary output. |
pty |
Shell with a PTY. Use for programs that call isatty() or require a real terminal. stdout and stderr are merged in the PTY stream. |
Returns:
| Field | Type | Description |
|---|---|---|
session_id |
string | Opaque session identifier. Required by ssh_session_exec and ssh_session_close. |
serial |
uint64 | Certificate serial of the session connection, for audit correlation. |
The sudo elevation prefix authorised by the signer is applied automatically by
the broker (per command in exec mode; to the shell process in shell/pty
mode) — it is not returned to the model.
Tool: ssh_session_exec¶
Execute a command on an existing persistent session.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
session_id |
string | ✓ | Session identifier returned by ssh_session_open. |
command |
string | ✓ | Command to execute. Every session command is preflighted against the current signer policy: target and bastion access, end-user groups, sudo, sudo_user, PTY, and the host's physical route are revalidated. In shell/pty sessions it must not contain \n or \r (rejected — a newline would inject extra commands into the persistent shell). exec sessions run each command in an isolated channel, but when the current host policy evaluates commands they must satisfy the command policy, including its newline rejection. In pty sessions a command is also limited to 4000 bytes (tty line limit) and must be printable text only: control bytes, tab included, are rejected (the tty line discipline or readline completion would edit the line before the shell runs it). Either rejection is audited as session_exec_denied; use exec mode or split the command. |
Returns:
| Field | Type | Description |
|---|---|---|
stdout |
string | Command output. |
stderr |
string | Standard error. Empty in pty mode. |
exit_code |
int | Remote process exit code. |
serial |
uint64 | Certificate serial for audit correlation. |
warnings |
[]string | Optional advisory warnings from per-command preflight, e.g. command-policy audit mode would have denied or required approval in enforce mode. |
Tool: ssh_session_close¶
Close a persistent session and release its SSH connection.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
session_id |
string | ✓ | Session identifier returned by ssh_session_open. |
Returns:
| Field | Type | Description |
|---|---|---|
ok |
bool | Always true on success. |
Note: always close sessions when done. Sessions are automatically reaped
after session_idle_seconds or session_max_seconds (configured in
config.json), but explicit closure is recommended to free resources promptly.
Session recording: when session_recording_dir is set in config.json,
shell and pty sessions are recorded to ASCIIcast v2 files in that directory.
Each file is named <session_id>.cast and contains stdin, stdout, and stderr
events with millisecond timestamps. See USAGE.md §8 for details.
Tool: ssh_put_file¶
Write a file on a host. Issues a one-shot certificate whose force-command is
cat > 'path' (plus an optional chmod), with the content streamed over
stdin. Requires allow_file_transfer: true on the host policy; the transfer
command is also subject to the host's command_policy like any one-shot. The
cat > 'path' form uses a file redirect, which shell_parse (the default)
rejects, so on a host with any restricting command_policy and shell_parse
on, every transfer is denied and no allow pattern changes that; do not
retry. Only hosts whose policies all set shell_parse: false can allowlist it
(USAGE.md §9.3). Runs as the host's configured SSH user (no sudo).
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
server |
string | ✓ | Logical host name. |
path |
string | ✓ | Destination path. Created or overwritten. |
content |
string | ✓ | File content (text, or base64 with content_base64: true). Capped by the broker's file_transfer_max_bytes (default 512 KiB). |
content_base64 |
bool | Decode content from base64 before writing (binary files). |
|
mode |
string | Octal permissions to chmod after writing (e.g. "0644"). |
|
ttl_seconds |
int | Certificate TTL override. |
Returns:
| Field | Type | Description |
|---|---|---|
bytes_written |
int | Bytes written to the remote file. |
sha256 |
string | Hex sha256 of the written content; also recorded in the broker audit log (file_put entry, same serial). |
serial |
uint64 | Certificate serial for audit correlation. |
warnings |
[]string | Optional command-policy audit-mode warnings. |
Tool: ssh_get_file¶
Read a file from a host. Issues a one-shot certificate whose force-command
is a bounded read (head -c max+1 < 'path'); a file larger than the limit is
an error, not a truncation. Requires allow_file_transfer: true on the host
policy. The head -c N < 'path' form uses a file redirect, so the same
shell_parse consequence as ssh_put_file applies: on a host with any
restricting command_policy and shell_parse on, every transfer is denied;
only shell_parse: false hosts can allowlist it (USAGE.md §9.3). Runs as the
host's configured SSH user (no sudo).
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
server |
string | ✓ | Logical host name. |
path |
string | ✓ | File to read. |
max_bytes |
int | Size limit for this read. Defaults to (and is capped by) the broker's file_transfer_max_bytes. |
|
ttl_seconds |
int | Certificate TTL override. |
Returns:
| Field | Type | Description |
|---|---|---|
content |
string | File content: text as-is, or base64 when base64 is true (file is not valid UTF-8). |
base64 |
bool | Whether content is base64-encoded. |
size |
int | File size in bytes (decoded). |
sha256 |
string | Hex sha256 of the content; also recorded in the broker audit log (file_get entry, same serial). |
serial |
uint64 | Certificate serial for audit correlation. |
warnings |
[]string | Optional command-policy audit-mode warnings. |
Monitoring endpoints¶
Every service accepts an optional monitor_listen config key that starts a
separate plain-HTTP listener (no TLS, no authentication — bind to
localhost or a private scrape interface):
| Route | Purpose |
|---|---|
GET /healthz |
Liveness. 200 with body ok while the process serves. |
GET /readyz |
Readiness. 200 with body ready once the service's main listener is accepting; 503 not ready before that and while draining on shutdown (#213). Use it for orchestrator readiness probes, not liveness. |
GET /metrics |
Prometheus text exposition format. |
The broker monitor_listen key applies to all three broker transports
(infrabroker serve-http / serve-mcp / serve-mcp-http). See
OPERATIONS.md §7 for the metric inventory and
alerting guidance (audit_append_failures_total in particular).
Audit Log Correlation¶
Every certificate issuance produces an entry in the signer's audit log with a
serial field. The broker's audit log records the same serial for each
execution. OpenSSH sshd (with LogLevel VERBOSE) includes the certificate
serial in the Accepted certificate log line.
Audit log entry fields:
| Field | Description |
|---|---|
time |
RFC3339 timestamp. |
seq |
Monotonically increasing sequence number (restores across restarts). |
caller |
Broker CN (mTLS) or OIDC user identity (HTTP frontend). |
host |
SSH server address (FQDN:port) in the signer log; logical name in the broker log. |
user |
SSH account on the remote host. |
principal |
SSH principal used in the certificate. |
command |
Command requested (one-shot) or session metadata. |
ttl |
Certificate validity window issued. |
serial |
Certificate serial number. |
session_id |
Persistent session ID (omitted for one-shot). |
end_user_context |
Attribution context of the end user's token (context_claim, e.g. an ASP sandbox_id); omitted when the token carries none. The signer also writes it as ctx= in command, mirroring the cert KeyId. |
outcome |
See table below. |
exit_code |
Remote process exit code (broker log only). |
elevation |
Sudo target, e.g., "sudo:root" or "sudo:deploy" (omitted if no escalation). On approval_granted / approval_declined it is the elevation the command was presented to the human with (#468). |
pty |
true if a PTY was allocated (omitted otherwise); on approval_granted / approval_declined, whether the presented command requested one (#468). |
policy_rule |
command_policy rule that drove the decision (omitted if none). |
dry_run |
true if the entry is a dry-run simulation (nothing executed). |
warning |
Advisory warning, e.g. command-policy audit mode would have denied or required approval. |
approval_id |
Approval request id (control plane log; omitted if none). |
approved_by |
CN of the approver (control plane log; omitted if none). |
approved_via |
How a require_approval command was approved outside the control plane: elicitation for an in-conversation approval (#118). Set on the broker's approval_granted and resulting executed records; omitted otherwise. |
anomaly |
Behavioral anomalies detected (control plane log): rate-exceeded, new-host:<h>, new-command:<c>. |
err |
Error message on denial or failure (omitted on success). |
prev_hash |
SHA-256 hex of the previous log line (chain integrity). |
sig |
Ed25519 signature over the canonical JSON of this entry (tamper evidence). |
Outcome values:
| Outcome | Service | Meaning |
|---|---|---|
issued |
Signer | Certificate successfully issued. |
denied |
Signer | Request rejected by policy or RBAC. |
error |
Signer | The policy allowed the intent but signing failed on the signer's side — CA backend (ssh-agent, Azure Key Vault, local key), missing envelope_key on a sealed-exec preflight, or a k8s TokenRequest mint. err carries the backend detail; the caller got a generic 502. |
dry_run_allowed |
Signer | Dry-run simulation: command would be allowed. |
dry_run_denied |
Signer | Dry-run simulation: command would be denied. |
reloaded |
Signer | signer.json successfully reloaded. |
reload-denied |
Signer | Reload rejected (caller not in reload_callers). |
reload-failed |
Signer | Reload attempted but config invalid; previous state preserved. |
end_user_unverified |
Signer | Caller has require_verified_end_user and the end-user identity could not be re-derived from a verified token; sign request denied (403). |
frozen_denied |
Signer | Kill switch: the caller CN or end user is frozen; /v1/sign (no certificate/token), GET /v1/hosts or GET /v1/clusters (no discovery) refused. Discovery denials are audited at most sign_rate_limit_per_min times per minute per frozen subject; the response stays 403 (#828). err names the frozen subject. |
self_approved |
Signer | Supplementary marker after issued: four-eyes was deliberately waived — an opted-in (self_approve) caller approved its own require_approval command in-conversation (#118). |
frozen |
Signer | Kill switch applied (POST /v1/freeze); command carries the subject and grants_revoked=N. |
unfrozen |
Signer | Kill switch lifted (POST /v1/unfreeze); residual subject-scoped grants swept. |
policy-read |
Signer | Full host policy read (GET /v1/policy/hosts); command carries the host count. |
policy-read-denied |
Signer | Full host policy read rejected (caller not in reload_callers). |
policy-changed |
Signer | Runtime command-policy change applied (broker-ctl policy add/remove). |
policy-denied |
Signer | Policy change rejected (caller not authorised). |
policy-failed |
Signer | Policy change rejected (invalid pattern or build failure; nothing persisted). |
grant-created |
Signer | Runtime command grant created (broker-ctl grant). |
grant-denied |
Signer | Grant create/revoke rejected (caller not authorised). |
grant-failed |
Signer | Grant create/revoke failed (rejected create or unknown grant id). |
grant-revoked |
Signer | Runtime grant revoked. |
approval-waiver-created |
Signer | Approve-and-learn waiver minted from an approval decision. |
approval-waiver-skipped |
Signer | Learn requested but the command is not require_approval; nothing waived. |
approval-waiver-failed |
Signer | Approve-and-learn waiver creation failed (best-effort; the cert was still issued). |
executed |
Broker | One-shot command completed. |
approval_granted |
Broker | A require_approval command was approved in-conversation via elicitation (#118); recorded before execution, with the elevation / pty the human approved (#468). |
approval_declined |
Broker | A require_approval command was presented via elicitation and the human declined; nothing executed. Carries the elevation / pty that were presented (#468). |
dry_run_allowed |
Broker | Dry-run: command would be allowed (nothing executed). |
dry_run_denied |
Broker | Dry-run: command would be denied (nothing executed). |
denied |
Broker | Request rejected before execution: a signer policy / RBAC denial of a one-shot, file transfer or session open (command policy, sudo, PTY, allow_file_transfer, session mode), an unknown host, or the session limit (#469). |
approval_required |
Broker | A require_approval one-shot, session open or Kubernetes action was withheld by the signer pending human approval; nothing executed (#469, k8s: #599). |
error |
Broker | Execution failed (SSH error, timeout, signing service unreachable, etc.). |
session_open |
Broker | Persistent session opened. |
session_exec |
Broker | Command executed in a persistent session. |
session_exec_denied |
Broker | Session command blocked by current-policy preflight (policy denial, approval needed, host connectivity drift). A signer / control-plane outage during the preflight is error, not a denial (#577). |
session_close |
Broker | Persistent session closed. err is empty for an explicit ssh_session_close; a forced close names its cause: reaped (idle), reaped (lifetime), reaped (cert expired) (the session's certificate lapsed, even under a command in flight) or broker shutdown (torn down by the broker exiting) (#470). |
session_killed |
Broker | Live session force-closed by the kill switch: its caller or end user was frozen on the signer. |
file_put |
Broker | File uploaded to the host (ssh_put_file). |
file_get |
Broker | File downloaded from the host (ssh_get_file). |
forwarded |
Control plane | Request forwarded to the signer and issued (no approval needed). |
denied |
Control plane | Signer refused the forwarded request — on the direct path, or on the approved forward after a human said yes (policy changed, subject frozen; approval_id/approved_by carry the attribution, #576) — or (enforce mode) a behavioural anomaly was detected and the dry-run check said the command is not allowed. |
error |
Control plane | Infrastructure failure, not a policy decision; nothing issued. The signer answered 5xx or was unreachable — CA-backend failure (#465), k8s token-mint failure (#455), outage — on the direct forward path or on the approved forward, relayed to the broker as 502 (#455, #576); or the signer's response after approval was malformed (no decision/certificate/token). |
approval-required |
Control plane / Signer | Command needs human approval; request recorded. |
approval-decision-allow |
Control plane | Approver allowed a pending request. |
approval-decision-allow-learn |
Control plane | Approver allowed a pending request and learned a waiver (approve-and-learn). |
approval-denied |
Control plane | Approver denied the request (or poll after denial). |
self-approval-rejected |
Control plane | Request originator tried to decide its own request (four-eyes guard). |
approval-learn-refused |
Control plane | Approve-and-learn refused because the request's end_user was stripped (broker not a trusted forwarder); the request stays pending and a plain approve still works. |
approval-granted |
Control plane | Certificate issued after approval. |
approval-timeout |
Control plane | Approval expired before being decided. |
anomaly |
Control plane | Behavioral anomaly detected (observe mode; not blocked). |
rate-limited |
Control plane | Request denied — rate limit exceeded (enforce mode). |
Correlating an execution end-to-end:
# Find a serial in the broker audit log
jq 'select(.serial == 12345)' broker_audit.log
# Find the matching issuance in the signer audit log
jq 'select(.serial == 12345)' signer_audit.log
# In sshd logs (journalctl or /var/log/auth.log)
grep "serial 12345" /var/log/auth.log
Verifying chain integrity:
Each entry's prev_hash is the SHA-256 hex of the previous raw JSON line.
Each entry's sig is the Ed25519 signature over the canonical JSON of the entry
with sig="" (empty string placeholder). Modifying, reordering, or deleting a
record in the middle breaks the chain and can be detected by replaying the
hashes. Dropping the newest records (tail truncation) cannot be detected from
the log alone; compare against an off-host copy (THREAT_MODEL gap #14).