diff --git a/fern/.docs-snapshots.yml b/fern/.docs-snapshots.yml index 34689eef0..213b355bc 100644 --- a/fern/.docs-snapshots.yml +++ b/fern/.docs-snapshots.yml @@ -1,8 +1,8 @@ snapshots: dev: - source-ref: e2939b919decda8605a1e4037b2cae9d935a870d - source-sha: e2939b919decda8605a1e4037b2cae9d935a870d - version: 0.0.117.dev203 + source-ref: e38d7254e6099a42d6b80329b8e4ef6f0817931f + source-sha: e38d7254e6099a42d6b80329b8e4ef6f0817931f + version: 0.0.117.dev204 latest: source-ref: e36d2315cab8b638e3b718d6cc9d6146e732c2ad source-sha: e36d2315cab8b638e3b718d6cc9d6146e732c2ad diff --git a/fern/pages-dev/providers/profiles.mdx b/fern/pages-dev/providers/profiles.mdx index e1774470e..d89299720 100644 --- a/fern/pages-dev/providers/profiles.mdx +++ b/fern/pages-dev/providers/profiles.mdx @@ -446,6 +446,8 @@ environment value under the actual environment variable key. `endpoints` contains the same endpoint object shape as sandbox network policy. A profile can use access presets, protocol-specific allow rules, deny rules, WebSocket credential rewriting, request body credential rewriting, GraphQL fields, and SSRF IP allowlists. Because profile credentials are not mapped to individual endpoints, OpenShell conservatively treats every endpoint in a profile that declares credentials as credentialed. Such endpoints require L7 inspection and cannot use `tls: skip` unless the profile explicitly sets `allow_uninspected_credentials: true`. +Profile validation rejects unknown `tls`, `enforcement`, and `access` values before the profile can contribute policy to a sandbox. + `binaries` contains the executable paths allowed to reach the profile endpoints when the profile contributes policy to a sandbox. Write each binary as a scalar path. OpenShell also accepts the transitional object form `- path: /usr/bin/example` and exports it as a scalar. The removed `harness` property is rejected; delete it from profiles created before 0.1.0. `inference_capable` is informational metadata that marks profiles intended for diff --git a/fern/pages-dev/reference/policy-schema.mdx b/fern/pages-dev/reference/policy-schema.mdx index 3e4c051d1..5e03c8a92 100644 --- a/fern/pages-dev/reference/policy-schema.mdx +++ b/fern/pages-dev/reference/policy-schema.mdx @@ -212,9 +212,9 @@ Each endpoint defines a reachable destination and optional inspection rules. | `port` | integer | Yes | TCP port number. | | `path` | string | No | Optional HTTP path glob used to select between L7 endpoints that share the same host and port. Empty means all paths. Use this when REST and GraphQL live under the same host, such as `/repos/**` and `/graphql`. | | `protocol` | string | No | Set to `tcp` with a valid DNS hostname to allow native TCP clients through policy DNS and transparent capture without payload inspection. Omit the field for L4 passthrough through an explicit proxy, including legacy hostless `allowed_ips` endpoints. Set to `rest` for HTTP method/path inspection, `websocket` for RFC 6455 upgrade and client text-message inspection, `graphql` for GraphQL-over-HTTP operation inspection, `mcp` for MCP Streamable HTTP request inspection, or `json-rpc` for generic JSON-RPC-over-HTTP method inspection. WebSocket endpoints can also use GraphQL operation rules for GraphQL-over-WebSocket traffic. Provider-credentialed endpoints require an inspected protocol unless `allow_uninspected_credentials` is explicitly set. | -| `tls` | string | No | TLS handling mode. The proxy auto-detects TLS by peeking the first bytes of each connection and terminates it for inspected HTTPS traffic, so this field is optional in most cases. Set to `skip` to disable auto-detection for edge cases such as client-certificate mTLS or non-standard protocols. Provider-credentialed endpoints reject `tls: skip` unless `allow_uninspected_credentials` is explicitly set. The values `terminate` and `passthrough` are deprecated and log a warning; they are still accepted for backward compatibility but have no effect on behavior. | -| `enforcement` | string | No | `enforce` actively blocks disallowed requests. `audit` logs violations but allows traffic through. | -| `access` | string | No | Access preset. One of `read-only`, `read-write`, or `full`. Mutually exclusive with `rules`. Not valid on `protocol: mcp` or `protocol: json-rpc`; MCP uses explicit rules unless `mcp.allow_all_known_mcp_methods: true` enables the endpoint method profile, and JSON-RPC always uses explicit rules. | +| `tls` | string | No | TLS handling mode. The proxy auto-detects TLS by peeking the first bytes of each connection and terminates it for inspected HTTPS traffic, so this field is optional in most cases. Set to `skip` to disable auto-detection for edge cases such as client-certificate mTLS or non-standard protocols. Provider-credentialed endpoints reject `tls: skip` unless `allow_uninspected_credentials` is explicitly set. The values `terminate` and `passthrough` are deprecated and log a warning; they are still accepted for backward compatibility but have no effect on behavior. Remove either value and omit `tls` to use the equivalent automatic handling. Other values are rejected before activation. | +| `enforcement` | string | No | `enforce` actively blocks disallowed requests. `audit` logs violations but allows traffic through. Other values are rejected before activation rather than interpreted as audit mode. | +| `access` | string | No | Access preset. One of `read-only`, `read-write`, or `full`; other values are rejected before activation. Mutually exclusive with `rules`. Not valid on `protocol: mcp` or `protocol: json-rpc`; MCP uses explicit rules unless `mcp.allow_all_known_mcp_methods: true` enables the endpoint method profile, and JSON-RPC always uses explicit rules. | | `rules` | list of allow rule objects | No | Fine-grained protocol-specific allow rules. Mutually exclusive with `access`. | | `deny_rules` | list of deny rule objects | No | L7 deny rules that block specific requests even when allowed by `access` or `rules`. Deny rules take precedence over allow rules. | | `allowed_ips` | list of string | No | CIDR or IP allowlist for SSRF override. Exact user-declared hostname endpoints may resolve to RFC 1918 private addresses without this field, but wildcard, hostless, and policy-advisor-proposed endpoints still require `allowed_ips` for private resolved IPs. A hostless allowlist is valid only for the legacy proxy path and cannot be combined with `protocol: tcp`. Entries overlapping loopback (`127.0.0.0/8`), link-local (`169.254.0.0/16`), or unspecified (`0.0.0.0`) are rejected at load time. | @@ -237,6 +237,15 @@ Each endpoint defines a reachable destination and optional inspection rules. | `mcp.allow_all_known_mcp_methods` | bool | No | Defaults to `false`. When `true`, enables the endpoint MCP method profile: omitted `rules` allow all MCP-family methods and all tools before `deny_rules`, and omitted rule `method` uses that profile. When unset or `false`, explicit MCP method rules are required; rules with `tool` or `params.name` must set `method: tools/call`. | | `json_rpc` | object | No | JSON-RPC endpoint options. For `protocol: json-rpc`, `json_rpc.max_body_bytes` sets the maximum JSON-RPC-over-HTTP request body bytes buffered for inspection. Defaults to `65536`. | +The YAML representation keeps the names shown above. Protobuf and generated SDK +clients use `NetworkTlsMode`, `NetworkEnforcementMode`, and +`NetworkAccessPreset` enums for these fields. This is a breaking source and wire +contract change for clients generated from the earlier string fields. +Regenerate bindings from the current protobuf definitions and replace string +assignments with the corresponding enum values. Unspecified TLS keeps automatic +handling, unspecified enforcement keeps the audit default, and unspecified +access selects no preset. Unknown enum numbers are rejected before activation. + **Validation constraints:** - When present, `endpoints`, `binaries`, `rules`, and `deny_rules` must be lists of objects, even when they contain only one entry. `null` cannot replace a list or an object entry.