diff --git a/docs/ai-coder/agent-boundary.md b/docs/ai-coder/boundary/agent-boundary.md similarity index 95% rename from docs/ai-coder/agent-boundary.md rename to docs/ai-coder/boundary/agent-boundary.md index 703aff8476..815a271a98 100644 --- a/docs/ai-coder/agent-boundary.md +++ b/docs/ai-coder/boundary/agent-boundary.md @@ -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. -![Screenshot of Agent Boundaries blocking a process](../images/guides/ai-agents/boundary.png)Example of Agent Boundaries blocking a process. +![Screenshot of Agent Boundaries blocking a process](../../images/guides/ai-agents/boundary.png)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 diff --git a/docs/ai-coder/landjail.md b/docs/ai-coder/boundary/landjail.md similarity index 100% rename from docs/ai-coder/landjail.md rename to docs/ai-coder/boundary/landjail.md diff --git a/docs/ai-coder/nsjail.md b/docs/ai-coder/boundary/nsjail.md similarity index 100% rename from docs/ai-coder/nsjail.md rename to docs/ai-coder/boundary/nsjail.md diff --git a/docs/ai-coder/boundary/rules-engine.md b/docs/ai-coder/boundary/rules-engine.md new file mode 100644 index 0000000000..3f1a6f4f19 --- /dev/null +++ b/docs/ai-coder/boundary/rules-engine.md @@ -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/*`. diff --git a/docs/ai-coder/index.md b/docs/ai-coder/index.md index 36da055e0c..3ab83fe226 100644 --- a/docs/ai-coder/index.md +++ b/docs/ai-coder/index.md @@ -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). diff --git a/docs/ai-coder/security.md b/docs/ai-coder/security.md index 86a252b8c4..2b7ba88110 100644 --- a/docs/ai-coder/security.md +++ b/docs/ai-coder/security.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). diff --git a/docs/manifest.json b/docs/manifest.json index d8c85a5ad4..10385ecb30 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -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" } ] },