ModueAgent is a Zero-Trust AI Agent Framework derived from ModueHarness Microkernel Security Principles.
While 1st-generation agent frameworks (LangChain, AutoGPT, CrewAI) rely on fragile prompt instructions ("please do not execute dangerous commands"), ModueAgent treats the LLM as an untrusted entity that can be cognitively hijacked at any moment via Indirect Prompt Injection. Security is structurally enforced via microkernel boundaries, ephemeral capabilities, output sandboxing, and resource budgets.
- 🛡️ Threat Model & 2026 Attack Evaluation: Benchmarking 7 real-world 2026 AI agent attack vectors and v0.1.1 defense verification.
- 🏛️ ModueHarness Microkernel Principles: Foundational zero-trust philosophy, untrusted cognition axiom, and 5 microkernel security rules.
- 🛠️ Developer Manual & Architecture Guide: End-to-end guide on building secure agents, feature stacking workflow, mental models, and anti-patterns.
- 📐 Security Architecture Specification: Detailed threat model, OCap boundaries, and XOA sandboxing internals.
- 🇰🇷 개발자 매뉴얼 (한국어): 기능 빌드업 4계층 순서, 핵심 보안 설계 원칙 및 배포 체크리스트.
- 🇰🇷 보안 아키텍처 명세서 (한국어): 위협 모델, 객체 역량 경계 및 XOA 출력 격리 상세.
AI agents executing real-world actions (web fetch, file system, API, shell) face severe attack vectors:
- Indirect Prompt Injection & Cognitive Hijacking: Untrusted web pages or documents hijack the agent's reasoning, turning it into a Confused Deputy.
- Arbitrary Code Execution (RCE): Monolithic frameworks grant unrestricted shell or
eval()access, leading to full host takeover when poisoned. - Credential & Secret Leaking: Raw tool outputs carrying environment variables or API keys are directly injected into prompt context and exfiltrated.
- Denial of Wallet (DoW): Malicious injection triggers infinite loops, racking up massive API billing overnight.
- Cognition & Action Physical Separation: The LLM's natural language reasoning and the tool execution environments are separated by strict capability checks.
- Object Capability (Zero-Trust JIT Tokens): No permanent global tool permissions. Ephemeral tokens with tight TTLs (60s to 10m) are issued JIT per step and immediately revoked.
- Side-Effect Classification (
EffectClass): Tools are categorized intoREAD(3600s TTL, cached),WRITE(600s TTL), andDESTRUCTIVE(60s TTL). Destructive actions trigger mandatory Verification Traps before execution. - XOA (Execute-Only Architecture) Output Sandboxing: Tools only expose strictly whitelisted fields (
extract_paths) via a safe JSONPath-lite walker. Raw tool outputs are immediately dropped from memory, preventing secret leakage. - AST Safe Evaluation & Zero Dependencies: Math evaluation eliminates
eval()/exec()via an AST node whitelist. The core framework has zero third-party dependencies, protecting against supply-chain poisoning. - Denial-of-Wallet Budgets: Hard limits on execution steps (
max_steps) and token counts (max_tokens) force clean circuit-breaking and safe fallback synthesis.
ModueAgent is designed to be co-developed with leading AI coding tools. AGENTS.md serves as the central Single Source of Truth (SSOT), with lightweight bridges connecting seamlessly to:
- Claude Code:
CLAUDE.md - Cursor:
.cursorrules&.cursor/rules/modueagent.mdc - GitHub Copilot:
.github/copilot-instructions.md - Google Gemini & Antigravity:
GEMINI.md - Cortex & Open Agents: Native
AGENTS.mddetection
Run the assistant verification script to ensure all configurations are in sync:
python3 scripts/bootstrap_tools.pyflowchart TD
subgraph Cognition ["Cognition Layer (Untrusted LLM Space)"]
User["User Prompt"] --> Agent["SecureAgent (ReAct Loop)"]
end
subgraph SecurityKernel ["Zero-Trust Security Boundary"]
Agent -->|"Tool Call Intent"| Guard["Schema Validator & Tool Whitelist"]
Guard --> CapEngine{"JIT Capability Verification"}
CapEngine -- Denied --> Err["Permission Denied"]
CapEngine -- Granted --> EffectCheck{"EffectClass Check"}
EffectCheck -- DESTRUCTIVE --> Trap["Verification Trap / HITL Approval"]
Trap -- Approved --> Exec["Sandboxed Tool Executor"]
Trap -- Rejected --> TrapErr["Execution Rejected"]
EffectCheck -- READ / WRITE --> Exec
end
subgraph Execution ["Execution Layer (Sandboxed)"]
Exec --> SafeWorker["Tool Function"]
SafeWorker --> XOA["XOA extract_safe (Whitelisted fields only)"]
XOA -->|"Raw output dropped"| Agent
end
git clone https://github.com/JeaMinLim/ModueAgent.git
cd ModueAgent
pip install -e .from modueagent import SecureAgent, tool, EffectClass, Budget
# 1. Define a tool with side-effect classification and XOA field extraction
@tool(
name="get_stock_price",
description="Fetch stock price.",
effect_class=EffectClass.READ, # Query-only, cacheable
extract_paths={"ticker": "data.symbol", "price": "data.price"} # Raw secrets dropped!
)
def get_stock_price(symbol: str) -> dict:
return {
"data": {"symbol": symbol.upper(), "price": 182.5},
"internal_api_key": "SK_LIVE_DO_NOT_EXPOSE", # Stripped by XOA
}
# 2. Configure SecureAgent with explicit whitelist and resource budget
agent = SecureAgent(
name="FinancialAgent",
tools=[get_stock_price],
allowed_tools=["get_stock_price"], # Strict whitelist
budget=Budget(max_steps=5, max_tokens=2000), # Prevents Denial of Wallet
)
# 3. Execute
answer = agent.run("What is the stock price of AAPL?")
print(answer)PYTHONPATH=src python3 examples/quickstart.pyPYTHONPATH=src python3 -m unittest discover -s tests -p "test_*.py" -v- v0.1.0 (Current): Core Zero-Trust capability engine,
@toolwithEffectClass& XOA,SecureAgent,SecureRuntime, and unifiedAGENTS.mdassistant bootstrap. - v0.2.0: Dynamic Taint Tracking (
TAINTEDcontext state on external input) and Human-in-the-Loop (HITL) CLI/Web approval hooks. - v0.3.0: Dual-LLM Cognitive Isolation (Privileged Planner vs. Quarantined Worker).
- v0.4.0: Native ModueHarness Central Microkernel RPC connector.
This project is licensed under the Apache 2.0 License.