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 SMCP 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.

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.

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
• SMCP Architecture — full protocol specification
• Node Configuration Reference — spec.security_contexts schema