mirror of
https://github.com/coder/coder.git
synced 2026-06-03 04:58:23 +00:00
docs: add docs for boundary rules engine (#21471)
Closes: https://github.com/coder/boundary/issues/146 - added docs for rules engine - move all boundary-related docs under new `boundary` directory
This commit is contained in:
Yevhenii Shcherbina
committed by
GitHub
GitHub
parent
a09d85cc26
commit
1bfd776cb4
@@ -2,7 +2,7 @@
|
||||
|
||||
Agent Boundaries are process-level firewalls that restrict and audit what autonomous programs, such as AI agents, can access and use.
|
||||
|
||||
Example of Agent Boundaries blocking a process.
|
||||
Example of Agent Boundaries blocking a process.
|
||||
|
||||
## Supported Agents
|
||||
|
||||
@@ -78,6 +78,8 @@ Boundary automatically reads `config.yaml` from `~/.config/coder_boundary/` when
|
||||
- `method=POST domain=api.example.com path=/users,/posts` - allows specific methods, domain, and paths
|
||||
- `path=/api/v1/*,/api/v2/*` - allows specific URL paths
|
||||
|
||||
For detailed information about the rules engine and how to construct allowlist rules, see the [rules engine documentation](./rules-engine.md).
|
||||
|
||||
You can also run Agent Boundaries directly in your workspace and configure it per template. You can do so by installing the [binary](https://github.com/coder/boundary) into the workspace image or at start-up. You can do so with the following command:
|
||||
|
||||
```hcl
|
||||
@@ -0,0 +1,98 @@
|
||||
# Rules Engine Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The `rulesengine` package provides a flexible rule-based filtering system for HTTP/HTTPS requests. Rules use a simple key-value syntax with support for wildcards and multiple values.
|
||||
|
||||
### Basic Syntax
|
||||
|
||||
Rules follow the format: `key=value [key=value ...]` with three supported keys:
|
||||
|
||||
- **`method`**: HTTP method(s) - Any HTTP method (e.g., `GET`, `POST`, `PUT`, `DELETE`), `*` (all methods), or comma-separated list
|
||||
- **`domain`**: Domain/hostname pattern - `github.com`, `*.example.com`, `*` (all domains)
|
||||
- **`path`**: URL path pattern - `/api/users`, `/api/*/users`, `*` (all paths), or comma-separated list
|
||||
|
||||
**Key behavior**:
|
||||
|
||||
- If a key is omitted, it matches all values
|
||||
- Multiple key-value pairs in one rule are separated by whitespace
|
||||
- Multiple rules in the allowlist are OR'd together (OR logic)
|
||||
- Default deny: if no rule matches, the request is denied
|
||||
|
||||
**Examples**:
|
||||
|
||||
```yaml
|
||||
allowlist:
|
||||
- domain=github.com # All methods, all paths for github.com
|
||||
- method=GET,POST domain=api.example.com # GET/POST to api.example.com
|
||||
- domain=api.example.com path=/users,/posts # Multiple paths
|
||||
- method=GET domain=github.com path=/api/* # All three keys
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Wildcard Symbol for Domains
|
||||
|
||||
The `*` wildcard matches domain labels (parts separated by dots).
|
||||
|
||||
| Pattern | Matches | Does NOT Match |
|
||||
|----------------|------------------------------------------------------------------|--------------------------------------------------------------------------|
|
||||
| `*` | All domains | - |
|
||||
| `github.com` | `github.com`, `api.github.com`, `v1.api.github.com` (subdomains) | `github.io` (diff domain) |
|
||||
| `*.github.com` | `api.github.com`, `v1.api.github.com` (1+ subdomain levels) | `github.com` (base domain) |
|
||||
| `api.*.com` | `api.github.com`, `api.google.com` | `api.v1.github.com` (`*` in the middle matches exactly one domain label) |
|
||||
| `*.*.com` | `api.example.com`, `api.v1.github.com` | - |
|
||||
| `api.*` | ❌ **ERROR** - Cannot end with `*` | - |
|
||||
|
||||
**Important**:
|
||||
|
||||
- Patterns without `*` at the start automatically match subdomains
|
||||
- `*.example.com` matches one or more subdomain levels
|
||||
- Domain patterns **cannot end with asterisk**
|
||||
|
||||
---
|
||||
|
||||
## Wildcard Symbol for Paths
|
||||
|
||||
The `*` wildcard matches path segments (parts separated by slashes).
|
||||
|
||||
| Pattern | Matches | Does NOT Match |
|
||||
|----------------|------------------------------------------------------------|-----------------------------------------|
|
||||
| `*` | All paths | - |
|
||||
| `/api/users` | `/api/users` | `/api/users/123` (subpaths don't match) |
|
||||
| `/api/*` | `/api/users`, `/api/posts` | `/api` |
|
||||
| `/api/*/users` | `/api/v1/users`, `/api/v2/users` | `/api/users`, `/api/v1/v2/users` |
|
||||
| `/*/users` | `/api/users`, `/v1/users` | `/api/v1/users` |
|
||||
| `/api/v1/*` | `/api/v1/users`, `/api/v1/users/123/details` (1+ segments) | `/api/v1` |
|
||||
|
||||
**Important**:
|
||||
|
||||
- `*` matches **exactly one segment** (except at the end)
|
||||
- `*` at the **end** matches **one or more segments** (special behavior)
|
||||
- `*` must match an entire segment (cannot be part of a segment like `/api/user*`)
|
||||
|
||||
---
|
||||
|
||||
## Special Meaning of Wildcard at Beginning and End
|
||||
|
||||
| Position | Domain | Path |
|
||||
|------------|---------------------|-----------------------|
|
||||
| Beginning | 1+ subdomain levels | Exactly 1 segment |
|
||||
| Middle | Exactly 1 label | Exactly 1 segment |
|
||||
| End | ❌ Not allowed | 1+ segments (special) |
|
||||
| Standalone | All domains | All paths |
|
||||
|
||||
---
|
||||
|
||||
## Multipath
|
||||
|
||||
Specify multiple paths in a single rule by separating them with commas:
|
||||
|
||||
```yaml
|
||||
allowlist:
|
||||
- domain=api.example.com path=/users,/posts,/comments
|
||||
- domain=api.example.com path=/api,/api/*
|
||||
```
|
||||
|
||||
`NOTE`: The pattern `/api/*` does not include the base path `/api`.
|
||||
To match both, use `path=/api,/api/*`.
|
||||
@@ -22,6 +22,6 @@ In cases where the IDE is secondary, such as prototyping or long-running backgro
|
||||
|
||||
AI agents can be powerful teammates, but must be treated as untrusted and unpredictable interns as opposed to tools. Without the right controls, they can go rogue.
|
||||
|
||||
[Agent Boundaries](./agent-boundary.md) is a new tool that offers process-level safeguards that detect and prevent destructive actions. Unlike traditional mitigation methods like firewalls, service meshes, and RBAC systems, Agent Boundaries is an agent-aware, centralized control point that can either be embedded in the same secure Coder Workspaces that enterprises already trust, or used through an open source CLI.
|
||||
[Agent Boundaries](./boundary/agent-boundary.md) is a new tool that offers process-level safeguards that detect and prevent destructive actions. Unlike traditional mitigation methods like firewalls, service meshes, and RBAC systems, Agent Boundaries is an agent-aware, centralized control point that can either be embedded in the same secure Coder Workspaces that enterprises already trust, or used through an open source CLI.
|
||||
|
||||
To learn more about features, implementation details, and how to get started, check out the [Agent Boundary documentation](./agent-boundary.md).
|
||||
To learn more about features, implementation details, and how to get started, check out the [Agent Boundary documentation](./boundary/agent-boundary.md).
|
||||
|
||||
@@ -25,4 +25,4 @@ Additional guidance and tooling is coming in future releases of Coder.
|
||||
|
||||
## Set Up Agent Boundaries
|
||||
|
||||
Agent Boundaries are process-level "agent firewalls" that lets you restrict and audit what AI agents can access within Coder workspaces. To learn more about this feature, see [Agent Boundary](./agent-boundary.md).
|
||||
Agent Boundaries are process-level "agent firewalls" that lets you restrict and audit what AI agents can access within Coder workspaces. To learn more about this feature, see [Agent Boundary](./boundary/agent-boundary.md).
|
||||
|
||||
+8
-3
@@ -972,18 +972,23 @@
|
||||
{
|
||||
"title": "Agent Boundaries",
|
||||
"description": "Understanding Agent Boundaries in Coder Tasks",
|
||||
"path": "./ai-coder/agent-boundary.md",
|
||||
"path": "./ai-coder/boundary/agent-boundary.md",
|
||||
"state": ["beta"],
|
||||
"children": [
|
||||
{
|
||||
"title": "nsjail",
|
||||
"description": "Documentation for Namespace Jail",
|
||||
"path": "./ai-coder/nsjail.md"
|
||||
"path": "./ai-coder/boundary/nsjail.md"
|
||||
},
|
||||
{
|
||||
"title": "landjail",
|
||||
"description": "Documentation for LandJail",
|
||||
"path": "./ai-coder/landjail.md"
|
||||
"path": "./ai-coder/boundary/landjail.md"
|
||||
},
|
||||
{
|
||||
"title": "Rules Engine",
|
||||
"description": "Documentation for the Boundary rules engine",
|
||||
"path": "./ai-coder/boundary/rules-engine.md"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user