Configuring Security Contexts

A SecurityContext is a named set of capability rules that controls exactly which MCP tools an agent may invoke — and with what arguments. Every agent execution runs within exactly one SecurityContext. If a tool call is not permitted by the context, it is blocked by the SEAL gateway before reaching any tool server.

SecurityContexts are defined in your aegis-config.yaml under spec.security_contexts and referenced by name from your agent manifest.

The Two-Surface Model

AEGIS applies security contexts across two distinct surfaces. Understanding which context applies where is critical for correct policy design.

Chat / MCP Surface

The chat surface is what the Zaru client (or any MCP client) sees when a user is interacting in a conversation. The context applied here is the user's tier context — zaru-free, zaru-pro, zaru-business, or zaru-enterprise. These contexts control what the chat client can invoke: which aegis tools the user may call, workflow signals, and so on. They do not grant filesystem or shell access — Zaru tier contexts deliberately exclude fs.*, cmd.run, and broad web.* access.

Execution Surface

The execution surface governs what agent containers can do once they are running. When a user triggers aegis.task.execute (or any tool that spawns an agent container), the spawned container does not inherit the caller's tier context. Instead, it runs under the aegis-system-agent-runtime context.

This separation is intentional: the user's tier context is about what the user can ask the platform to do; aegis-system-agent-runtime is about what the platform's agent containers are allowed to do on the user's behalf.

The aegis-system-agent-runtime Built-In Context

aegis-system-agent-runtime is a platform-provided security context that ships with AEGIS. It does not need to be defined in aegis-config.yaml — the orchestrator registers it automatically at startup.

What aegis-system-agent-runtime grants

What aegis-system-agent-runtime excludes

• Destructive platform operations (aegis.agent.delete, aegis.workflow.delete, aegis.task.remove)
• Orchestrator commands (aegis.system.info, aegis.system.config)
• Any tool not explicitly listed above

Configuration example

Because aegis-system-agent-runtime is built in, you do not define it in aegis-config.yaml. The orchestrator's compiled-in definition is equivalent to:

- name: "aegis-system-agent-runtime"
  description: "Execution surface for agent containers. Grants filesystem, shell, and web access scoped to /workspace."
  capabilities:
    - tool_pattern: "fs.*"
      path_allowlist:
        - /workspace
    - tool_pattern: "cmd.run"
    - tool_pattern: "web.*"
    - tool_pattern: "aegis.agent.get"
    - tool_pattern: "aegis.agent.list"
    - tool_pattern: "aegis.workflow.get"
    - tool_pattern: "aegis.workflow.list"
    - tool_pattern: "aegis.workflow.signal"
    - tool_pattern: "aegis.task.execute"
  deny_list:
    - "aegis.agent.delete"
    - "aegis.workflow.delete"
    - "aegis.task.remove"
    - "aegis.system.info"
    - "aegis.system.config"

The path_allowlist on fs.* means that all filesystem tools — reads, writes, edits, deletes — are restricted to paths under /workspace. Attempts to access /etc, /agent, or any other path are rejected by the SEAL gateway before the tool server is reached.

Built-In Contexts

The following contexts ship with the platform and do not require operator configuration:

Operator-defined contexts in aegis-config.yaml supplement this list but cannot redefine built-in names.

How Policy Evaluation Works

Every tool call an agent makes is evaluated against its SecurityContext using this algorithm, in order:

1. Deny list — If the tool name appears in deny_list, the call is rejected immediately. Deny list entries always override capabilities.
2. Capability scan — Each capabilities entry is checked in order. The first capability whose tool_pattern matches and whose constraints (path, command, domain) are satisfied returns Ok and allows the call.
3. Default deny — If no capability matches, the call is rejected.

Defining a SecurityContext

In aegis-config.yaml:

spec:
  security_contexts:
    - name: "research-safe"
      description: "Read-only web access. No shell, no writes."
      capabilities:
        - tool_pattern: "web.search"
          domain_allowlist:
            - "wikipedia.org"
            - "arxiv.org"
            - "github.com"
        - tool_pattern: "fs.read"
          path_allowlist:
            - "/workspace"
      deny_list:
        - "fs.write"
        - "fs.delete"
        - "cmd.run"

    - name: "coder-unrestricted"
      description: "Full shell and filesystem access within /workspace."
      capabilities:
        - tool_pattern: "fs.*"
          path_allowlist:
            - "/workspace"
        - tool_pattern: "cmd.run"
          command_allowlist:
            - "python"
            - "node"
            - "npm"
            - "pip"
            - "git"
        - tool_pattern: "web.search"
      deny_list: []

SecurityContext Fields

Capability Fields

Each entry in capabilities is one permission grant:

Pattern Matching

tool_pattern supports three forms:

Referencing a SecurityContext from an Agent Manifest

apiVersion: 100monkeys.ai/v1
kind: Agent
metadata:
  name: "my-research-agent"
spec:
  security_context: "research-safe"    # ← references the context by name
  runtime:
    language: python
    version: "3.11"
  prompt: |
    You are a research assistant...

If spec.security_context is omitted, the agent gets the default context defined in your node config (typically the most restrictive context available).

Example: Restricting npm to Safe Subcommands

To allow npm install and npm run but not npm publish:

capabilities:
  - tool_pattern: "cmd.run"
    command_allowlist:
      - "npm"
    subcommand_allowlist:
      - "install"
      - "run"
      - "test"
      - "build"

An agent attempting npm publish would receive a SubcommandNotAllowed violation.

Example: Filesystem Access Scoped to /workspace

capabilities:
  - tool_pattern: "fs.*"
    path_allowlist:
      - "/workspace"

Path allowlist matching is prefix-based: /workspace/src/main.py is allowed; /etc/passwd is not. Path traversal (../) is always blocked by the server-side path canonicalization layer, regardless of SecurityContext settings.

Example: Open Web Access with Deny List Exclusions

To allow any web search except social media:

capabilities:
  - tool_pattern: "web.search"
deny_list:
  - "web.post"
  - "web.submit"

Or to restrict the domains:

capabilities:
  - tool_pattern: "web.search"
    domain_allowlist:
      - "docs.python.org"
      - "developer.mozilla.org"
      - "stackoverflow.com"
      - "github.com"

Policy Violations

When a call is blocked, AEGIS:

1. Returns a PolicyViolation error to the agent's inner loop.
2. Produces a WARN log entry with structured fields: execution_id, tool_name, violation type.
3. Publishes a PolicyViolationBlocked domain event to the event bus (visible in audit trail).

The agent's LLM receives the violation error message and may attempt a different approach within its iteration budget.

Operator SecurityContext

The aegis-system-operator SecurityContext grants platform operators access to administrative tools beyond what any consumer tier provides. It is a superset of enterprise-tier capabilities, adding destructive and orchestrator commands.

- name: "aegis-system-operator"
  description: "Platform operator — all safe tools plus destructive and orchestrator commands"
  capabilities:
    # All safe commands (same as enterprise tier)
    - tool_pattern: "fs.*"
      path_allowlist: [/workspace, /agent, /shared]
    - tool_pattern: "cmd.run"
      subcommand_allowlist:
        git: [clone, add, commit, push, pull, status, diff, stash]
        cargo: [build, test, fmt, clippy, check, run]
        npm: [install, run, test, build, ci]
        python: ["-m"]
    - tool_pattern: "web.*"
    # Execute pipeline commands
    - tool_pattern: "aegis.execute.*"
    # Destructive commands (operator-only)
    - tool_pattern: "aegis.agent.delete"
    - tool_pattern: "aegis.workflow.delete"
    - tool_pattern: "aegis.task.remove"
    # Orchestrator commands (operator-only)
    - tool_pattern: "aegis.system.info"
    - tool_pattern: "aegis.system.config"
  deny_list: []

Tool Categories

Tools exposed by the SEAL gateway are classified into three categories:

The five operator-only tools are:

1. aegis.agent.delete — permanently remove an agent definition
2. aegis.workflow.delete — permanently remove a workflow definition
3. aegis.task.remove — permanently remove a task from the execution queue
4. aegis.system.info — retrieve orchestrator system information (version, uptime, cluster state)
5. aegis.system.config — read and modify runtime configuration

Why the aegis-system- Prefix?

The operator context uses the aegis-system- prefix rather than zaru- to avoid SEAL middleware parameter stripping. For contexts prefixed with zaru-, the SEAL middleware automatically strips force and version parameters from tool calls — a safety measure for consumer-facing requests. Operator sessions need these parameters to reach the orchestrator unmodified, so they use the aegis-system- prefix which bypasses that stripping logic.

Swarm Security Context Ceiling

When an agent spawns child agents in a swarm, the child's security context must be equal to or more restrictive than the parent's. Attempting to spawn a child with greater permissions fails immediately with a SpawnError.

For example: a parent running under "coder-unrestricted" may spawn children using "research-safe", but not vice versa.

See Also

• Security Model — security architecture overview
• Agent Manifest Reference — spec.security_context field
• SEAL Architecture — full protocol specification
• Node Configuration Reference — spec.security_contexts schema