AegisAgent Concepts¶
This page explains AegisAgent in simple terms.
If you remember only one thing:
AegisAgent is not an AI agent. AegisAgent is the security layer that controls what AI agents are allowed to do.
AegisAgent focuses on actions, not just text.
Why agent security is different¶
Traditional application security usually protects users, servers, databases, and APIs.
AI agents add a new problem:
The software can read instructions from untrusted places and then take real actions.
For example, a coding agent might read a GitHub issue that says:
The danger is not only that the prompt is malicious.
The danger is that the agent may then call a real tool:
AegisAgent controls the action boundary where that tool call happens.
Core concepts¶
AI agent¶
An AI agent is software that uses a model to decide what to do, then uses tools or APIs to act.
Examples:
- coding agents
- support agents
- DevOps agents
- research agents
- browser agents
- workflow automation agents
AegisAgent does not replace these agents. It controls them.
Tool call¶
A tool call is when an agent asks external software to do something.
Examples:
- read a GitHub issue
- merge a pull request
- send a Slack message
- create a Jira ticket
- run a shell command
- read or write a file
- call an MCP tool
AegisAgent is most useful when important tool calls are forced through an AegisAgent choke point.
Action¶
An action is the exact operation the agent wants to perform.
AegisAgent treats this as structured data:
{
"tool": "github",
"action": "merge_pull_request",
"resource": "repo/payments-service/pull/482",
"parameters": {
"base_branch": "main"
}
}
AegisAgent can then ask:
- Which tool is being used?
- What action is requested?
- What resource is affected?
- Is this read-only or mutating?
- Is the source trusted?
- Does policy allow it?
- Is approval required?
Mutating action¶
A mutating action changes something.
Examples:
- merging a pull request
- deleting a file
- sending an email
- changing infrastructure
- posting to Slack
- writing to a database
- creating or closing a ticket
Mutating actions are higher risk than read-only actions.
AegisAgent's default demo policy blocks or escalates risky mutations when they are triggered by untrusted external content.
Source trust¶
Source trust means: where did the instruction or context come from?
A command from a trusted internal workflow is different from text copied from a public issue, email, web page, or user comment.
AegisAgent's policy can use source trust as a deterministic signal:
trusted internal context
→ lower risk
untrusted external context
→ risky mutations should be denied or require approval
This is important because malicious text can look harmless. The source often tells you more than the wording.
Prompt injection¶
Prompt injection is when untrusted text tries to override the agent's real instructions.
Example:
AegisAgent does not rely on guessing whether every prompt is malicious. Instead, it controls the actions that happen after the prompt.
Untrusted text
→ agent proposes action
→ AegisAgent checks source trust + action risk
→ allow, deny, or require approval
Action hash¶
An action hash is a cryptographic fingerprint of the exact action.
AegisAgent canonicalizes the action into deterministic JSON, then hashes it.
If any important part of the action changes, the hash changes.
That means approval can be bound to one exact action instead of a vague summary.
Approval integrity¶
Approval integrity prevents approve-then-swap attacks.
Without approval integrity:
With AegisAgent:
Agent requests action A.
AegisAgent computes action_hash(A).
Human approval is bound to action_hash(A).
Before execution, the SDK recomputes the hash.
If the action changed, execution fails closed.
An approval is valid for exactly the action that was approved.
Fail closed¶
Fail closed means the safe failure mode is to block the action.
AegisAgent should fail closed when:
- policy cannot be evaluated
- approval cannot be verified
- the action hash changed
- receipt writing fails for a protected action
- a required security check is unavailable
For security infrastructure, silent allow is dangerous.
Receipt¶
A receipt is tamper-evident evidence for a protected decision or action.
A receipt helps answer:
- What did the agent try to do?
- Was it allowed, denied, or paused for approval?
- What exact action was approved?
- Who approved it?
- Which agent and tenant were involved?
- Has the evidence chain been modified?
AegisAgent receipts are designed to be verifiable instead of just ordinary logs.
MCP¶
MCP means Model Context Protocol.
MCP lets agents discover and call tools exposed by MCP servers.
This is powerful, but it creates risk:
AegisAgent's MCP Gateway Lite adds governance around MCP tools, including registration, discovery, approval/disable controls, unknown-tool denial, and audit events.
Choke point¶
A choke point is a place where AegisAgent can reliably inspect and control an action.
Examples:
- SDK wrapper
- gateway authorization API
- MCP gateway
- tool broker
- egress proxy
- runtime sensor
- agent cage
- approval engine
- receipt engine
Important reality:
AegisAgent can only control what passes through AegisAgent choke points.
If an agent bypasses every AegisAgent choke point, AegisAgent should not pretend it controlled that action.
The target runtime architecture treats bypassing agents as unknown or hostile and controls them through sandboxing, egress controls, process controls, bans, and quarantine.
Known agent vs unknown agent¶
Known agent¶
A known agent is integrated with AegisAgent on purpose.
Today, this usually means the agent uses the SDK or gateway before executing protected tools.
Unknown agent¶
An unknown agent is not trusted to cooperate.
The target architecture controls unknown agents through runtime data-plane components:
Unknown agent
→ cage runner sandbox
→ node sensor observes runtime behavior
→ egress proxy controls network
→ tool broker controls credentials and APIs
→ gateway sends signed control commands
These runtime components are roadmap items, not all part of the current MVP.
Control plane¶
The control plane is the central brain.
It owns:
- policy
- authorization decisions
- approvals
- receipts
- tenants
- audit events
- MCP governance
- future ban/quarantine state
- future runtime control commands
In the current repository, the Rust gateway is the start of the control plane.
Runtime data plane¶
The runtime data plane is the enforcement layer near where agents run.
The target runtime data plane includes:
- node sensor
- agent cage runner
- egress proxy
- tool broker
- signed command channel
- local durable event queue
- ban and quarantine enforcement
This should remain separate from the gateway. The gateway should not run untrusted agents directly.
Policy vs LLM judgment¶
AegisAgent policy decisions should be deterministic.
An LLM may help summarize evidence or draft an incident report, but it should not be the authority that decides whether a privileged action is allowed.
Simple end-to-end mental model¶
Untrusted GitHub issue
→ source_trust = untrusted_external
→ agent proposes github.merge_pull_request
→ AegisAgent computes action_hash
→ Cedar policy denies or requires approval
→ SDK fails closed if not allowed
→ receipt/audit evidence is written
That is the core of AegisAgent today.
The roadmap expands the same idea to unknown agents, runtime behavior, network egress, credentials, bans, quarantine, and SOC evidence.