Skip to content

Agent Mesh

docs: add comprehensive node-configuration guide for operators and clarify baseline policy fallback

Antonio Ojea77a8002a2aa0
diff --git a/site/content/docs/development/policy.md b/site/content/docs/development/policy.md
index fcd65933..413777fa 100644
--- a/site/content/docs/development/policy.md
+++ b/site/content/docs/development/policy.md
@@ -67,7 +67,7 @@ allow if group("engineering");
## 2. Hub Policy Schema (`policies.yaml`)
Admins define central permissions by mapping OIDC roles to specific capabilities.
-* **`allowed_targets`**: Defines which logical groups or specific peers a user can route messages to, analogous to Active Directory security groups. Target definitions must be formatted as resolved facts (e.g., `group:<name>`, `user:<sub-id>`, `email:<email>`, `role:<role-name>`, or `node:<peer-id>`).
+* **`allowed_targets`**: Defines which logical groups or specific peers a user can route messages to, analogous to Active Directory security groups. Target definitions must be formatted as resolved facts (e.g., `group:<name>`, `user:<sub-id>`, `email:<email>`, `role:<role-name>`, or `node:<peer-id>`). *Note: These are evaluated exclusively by the destination node (see Section 3.1).*
* **`allowed_services`**: Defines the application-level tools or endpoints a user can access, prefixed by their service type.
> [!NOTE]
@@ -91,8 +91,8 @@ roles:
- 'department("analytics");' # Raw injected facts
```
-## 3. Node Local Attenuation Schema (`local_policy.yaml`)
-Local developers can further restrict access to their specific node. Local policies can only attenuate (restrict) access, never expand it beyond what the Hub allowed.
+## 3. Node Local Attenuation Schema (`sam-node-config.yaml`)
+Local developers can further restrict access to their specific node. Local policies can only attenuate (restrict) access, never expand it beyond what the Hub allowed. They are evaluated entirely at the destination node.
```yaml
version: "v1alpha1"
@@ -103,6 +103,34 @@ attenuation:
- 'check if time($time), $time < 2026-12-31T00:00:00Z;'
```
+### 3.1 Evaluating `allowed_targets` at the Destination
+The SAM network operates on a Zero Trust architecture. The origin node does not police its own traffic. When the Hub injects an `allowed_targets` permission (like `- "group:backend-nodes"`) into the token, it creates a `network_target("group:backend-nodes")` capability fact.
+
+It is up to the **destination node** to mathematically prove that it is the intended target. To do this, the destination node injects its own identity into its local config using `rules`, and enforces the match using `policies`:
+
+```yaml
+version: "v1alpha1"
+attenuation:
+ rules:
+ # 1. The destination defines what it "is" locally
+ - 'target("group:backend-nodes") <- true;'
+ - 'target("email:[email protected]") <- true;'
+ policies:
+ # 2. The destination strictly enforces that the token contains the matching network_target
+ - 'allow if target($t), network_target($t);'
+```
+
+If the calling node's token does not contain a `network_target` fact that exactly matches one of the destination's `target` rules, the destination node's authorization middleware will reject the connection.
+
+> [!WARNING]
+> **What happens if a node does not set any local target policies?**
+> If a node does not define any `target` rules or `allow if target($t), network_target($t);` policies in its local configuration, it defaults to relying strictly on the Hub's **Baseline Security Rules** (Section 4). In this default state, the node is "open" to *any* peer in the mesh, provided the peer possesses the explicit `allow_service` permissions required to execute the tool. In other words, `allowed_targets` is an *opt-in* mechanism for the destination to attenuate traffic further; without it, the destination trusts the Hub's `allowed_services` whitelist implicitly.
+>
+> **Does this mean the mesh is insecure by default?**
+> No. By default, `sam-hub` operates in a **Default-Deny** state. If a user is not explicitly mapped to a role in the Hub's `policies.yaml`, or if their role does not explicitly grant an `allowed_service` capability, their token will contain no service permissions. Because the destination node's Baseline Rules require an explicit `allow_service` fact to execute any tool, the connection will be instantly denied (even if no targets are defined).
+>
+> It is entirely a **Mesh Operator decision** how the mesh behaves. Operators can choose to rely solely on service whitelists (granting broad mesh-wide execution), or strictly partition the network into isolated zones by injecting `allowed_targets` and enforcing them locally on the nodes.
+
## 4. Node Baseline Security Rules
Every `sam-node` enforces a set of baseline security rules (defined in Go code) to secure the transport layer. These rules run automatically before evaluating custom OIDC or local policies:
diff --git a/site/content/docs/user/kubernetes-deployment.md b/site/content/docs/user/kubernetes-deployment.md
index 3e2e0aca..d64e0795 100644
--- a/site/content/docs/user/kubernetes-deployment.md
+++ b/site/content/docs/user/kubernetes-deployment.md
@@ -204,7 +204,30 @@ metadata:
namespace: sam-nodes
```
-### 2. Deploy Nodes using Token Projection
+### 2. Configure Node Identity and Services
+Create a ConfigMap defining the node's local services and local security target identity (see the [Node Configuration Guide](../node-configuration/) for schema details):
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: sam-node-config
+ namespace: sam-nodes
+data:
+ sam-node.yaml: |
+ version: "v1alpha1"
+ services:
+ - type: mcp
+ name: db-agent
+ command: ["echo", "placeholder db-agent service"]
+ attenuation:
+ rules:
+ - 'target("group:backend-nodes") <- true;'
+ policies:
+ - 'allow if target($t), network_target($t);'
+```
+
+### 3. Deploy Nodes using Token Projection
Deploy the nodes. We use a `projected` volume to request a short-lived token containing the audience expected by the hub (`sam-hub-audience`):
```yaml
diff --git a/site/content/docs/user/node-configuration.md b/site/content/docs/user/node-configuration.md
new file mode 100644
index 00000000..25197188
--- /dev/null
+++ b/site/content/docs/user/node-configuration.md
@@ -0,0 +1,79 @@
+---
+title: "Node Configuration Guide"
+linkTitle: "Node Configuration"
+weight: 15
+---
+
+The `sam-node` acts as a local security gateway and tool proxy for AI agents. While the Hub acts as the central control plane, each Node independently defines its own local tool catalogue and enforces its own local security identity.
+
+---
+
+## 1. Node Configuration File (`sam-node.yaml`)
+
+By default, `sam-node` runs without exposing any local tools to the mesh. To expose local tools or strictly enforce your node's network identity, you must create a Node configuration file and pass it to the daemon using the `--config` flag:
+
+```bash
+sam-node run --config ./sam-node.yaml --api-token "secret"
+```
+
+### Configuration Schema
+
+The `sam-node.yaml` file supports defining local **Services** and local **Attenuation** security rules.
+
+```yaml
+version: "v1alpha1"
+
+# 1. Define Local Services
+services:
+ # Example: Expose a local CLI MCP server to the mesh
+ - type: mcp
+ name: local-shell-tools
+ description: "Execute bash commands safely in a local container"
+ command: ["npx", "-y", "@modelcontextprotocol/server-everything"]
+
+ # Example: Expose a local inference endpoint
+ - type: inference
+ name: local-ollama
+ description: "DeepSeek local inference proxy"
+ target_url: "http://localhost:11434"
+
+# 2. Define Local Security Identity (Zero Trust)
+attenuation:
+ rules:
+ # Explicitly define this node's identity in the mesh
+ - 'target("group:backend-nodes") <- true;'
+ - 'target("email:[email protected]") <- true;'
+ policies:
+ # Enforce that the incoming caller's token contains a matching network_target
+ - 'allow if target($t), network_target($t);'
+```
+
+---
+
+## 2. Defining Local Services
+
+The `services` array allows you to register endpoints that remote peers in the SAM Network can discover and execute (provided they possess the proper `allow_service` credentials issued by the Hub).
+
+| Property | Description |
+| :--- | :--- |
+| `type` | The protocol protocol type. Supported values are `mcp` (Model Context Protocol), `inference`, or `a2a`. |
+| `name` | The unique name of the service (e.g., `git-helper`). This must exactly match the name authorized by the Hub's `policies.yaml` (e.g., `mcp:git-helper`). |
+| `description` | A human-readable description published to the mesh discovery catalogue. |
+| `command` | *(For MCP)* The executable command array to spawn as a local subprocess (e.g. `["node", "index.js"]`). |
+| `env` | *(For MCP)* Key-value environment variables passed to the subprocess. |
+| `target_url` | *(For HTTP/Inference)* The upstream local URL to proxy traffic to. |
+
+---
+
+## 3. Defining Local Security (Target Attenuation)
+
+In a Zero Trust architecture, the destination node is entirely responsible for verifying that it is the intended recipient of an incoming request.
+
+While the Hub injects routing boundaries (like `network_target("group:backend-nodes")`) into the caller's token, the destination node will **ignore these targets by default** (relying solely on the Hub's service whitelist) unless you explicitly configure the node's local identity.
+
+If your mesh operator utilizes `allowed_targets` to partition the network, your node **must** define its identity in the `attenuation` block to accept traffic:
+
+1. **`rules`**: Inject Datalog facts asserting the node's identity (e.g. `target("group:backend-nodes") <- true;`).
+2. **`policies`**: Add a local policy strictly enforcing that the incoming token possesses the matching capability (e.g. `allow if target($t), network_target($t);`).
+
+If a calling node attempts to connect and its token does not contain the required `network_target` matching your local `target` rules, the connection will be cryptographically rejected.