187 lines
4.3 KiB
Markdown
187 lines
4.3 KiB
Markdown
# ThreeGate
|
|
|
|
**ThreeGate** is a security-first architecture for local, agent-assisted research and analysis.
|
|
|
|
It is designed to support *useful* agent behavior while strictly limiting blast radius by enforcing
|
|
**three independent security gates** between reasoning, retrieval, and execution.
|
|
|
|
The system is intentionally conservative: capability is earned incrementally, audited at every boundary,
|
|
and never co-located with reasoning.
|
|
|
|
---
|
|
|
|
## Core Design Goal
|
|
|
|
> Enable powerful local research assistance **without** granting an AI system uncontrolled execution,
|
|
> network access, or persistence.
|
|
|
|
ThreeGate is especially suited to:
|
|
- academic and technical research assistants
|
|
- policy analysis
|
|
- code review and synthesis
|
|
- data transformation and ranking tasks
|
|
|
|
It is *not* intended to run autonomous agents with self-directed persistence or open-ended tool use.
|
|
|
|
---
|
|
|
|
## The Three Gates (Non-Negotiable)
|
|
|
|
### Gate 1 — **CORE (Reasoning & Synthesis)**
|
|
|
|
- No network access
|
|
- No execution capability
|
|
- Consumes *only validated artifacts*
|
|
- Produces analysis, summaries, and *Tool Requests* for human approval
|
|
|
|
CORE is the only place where LLM reasoning occurs.
|
|
|
|
---
|
|
|
|
### Gate 2 — **FETCH (Controlled Retrieval)**
|
|
|
|
- HTTPS only
|
|
- Strict domain allowlist
|
|
- Proxy-enforced egress
|
|
- Size-capped and content-typed retrieval
|
|
- Emits **Research Packets** only (never executable instructions)
|
|
|
|
FETCH treats *all external content as hostile data*.
|
|
|
|
---
|
|
|
|
### Gate 3 — **TOOL-EXEC (Constrained Execution)**
|
|
|
|
Execution is split into **two distinct backends**:
|
|
|
|
#### TOOL-EXEC-Lite (Monty)
|
|
- Python-subset interpreter
|
|
- No filesystem
|
|
- No environment
|
|
- No network
|
|
- No subprocess
|
|
- No external functions (by default)
|
|
- Stdio-only inputs/outputs
|
|
|
|
Used for:
|
|
- JSON transformations
|
|
- ranking/scoring
|
|
- small algorithms
|
|
- validation helpers
|
|
|
|
This is the **default execution lane**.
|
|
|
|
#### TOOL-EXEC-Heavy (ERA microVM)
|
|
- Full isolation via microVM
|
|
- Used only when Monty cannot express the task
|
|
- Requires explicit justification
|
|
|
|
Both execution lanes:
|
|
- Require human-approved Tool Requests
|
|
- Emit **Tool Results** as immutable artifacts
|
|
- Are never allowed to feed results back into FETCH or execute recursively
|
|
|
|
---
|
|
|
|
## Data Flow (One-Way, Audited)
|
|
|
|
```
|
|
|
|
External Sources
|
|
↓
|
|
FETCH
|
|
↓ (Research Packets)
|
|
handoff/
|
|
↓
|
|
CORE
|
|
↓ (Approved Tool Requests)
|
|
TOOL-EXEC
|
|
↓ (Tool Results)
|
|
handoff/
|
|
↓
|
|
CORE
|
|
|
|
```
|
|
|
|
No component both **decides** and **acts**.
|
|
|
|
---
|
|
|
|
## Artifact Types
|
|
|
|
### Research Packet
|
|
- Markdown + strict front matter
|
|
- Metadata, bounded excerpts, provenance
|
|
- No instructions, no executable content
|
|
- Validated before CORE ingestion
|
|
|
|
### Tool Request
|
|
- Human-approved
|
|
- Backend-specific (`ERA` or `monty`)
|
|
- Declarative constraints
|
|
- No self-modifying behavior
|
|
|
|
### Tool Result
|
|
- Immutable output
|
|
- Captured stdout/stderr
|
|
- Content hashes
|
|
- Treated as untrusted data by CORE
|
|
|
|
---
|
|
|
|
## Security Principles (Do Not Violate)
|
|
|
|
- No reasoning component may execute code
|
|
- No execution component may reason or fetch
|
|
- Network access is centralized and audited
|
|
- Redirects are never trusted without re-validation
|
|
- All cross-gate artifacts are hostile by default
|
|
- Escalation of capability is a security change
|
|
|
|
---
|
|
|
|
## Repository Structure (Key Paths)
|
|
|
|
```
|
|
|
|
core/ # CORE consumers (read-only)
|
|
fetch/ # FETCH retrievers (proxy-bound)
|
|
tool-exec/
|
|
monty/ # TOOL-EXEC-Lite (pure compute)
|
|
era/ # TOOL-EXEC-Heavy (microVM)
|
|
tools/ # Validators and shared helpers
|
|
policy/ # Human-readable enforcement rules
|
|
infra/ # Docker, proxy, firewall scaffolding
|
|
docs/ # Architecture and operator guides
|
|
|
|
```
|
|
|
|
---
|
|
|
|
## Status
|
|
|
|
This repository currently provides:
|
|
- Full FETCH scaffolding with allowlisted, size-capped retrieval
|
|
- Crossref DOI metadata ingestion
|
|
- Redirect-safe URL fetching
|
|
- Monty execution backend (pure compute)
|
|
- ERA execution stubs
|
|
- Validators enforcing backend-specific rules
|
|
|
|
It is suitable for **local research workflows** and **controlled experimentation**.
|
|
|
|
---
|
|
|
|
## Philosophy
|
|
|
|
ThreeGate assumes:
|
|
- LLMs are powerful but non-deterministic
|
|
- External content is adversarial by default
|
|
- Execution is the highest-risk capability
|
|
- Separation of duties beats clever sandboxing
|
|
|
|
The goal is not to build an autonomous agent.
|
|
The goal is to build a *trustworthy assistant*.
|
|
```
|
|
|