diff --git a/README.md b/README.md index b6cbd33..5238ba7 100644 --- a/README.md +++ b/README.md @@ -58,13 +58,17 @@ docker run -d -p 9100:9100 syntrex/gomcp:latest ## πŸ—οΈ Architecture -```text -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ β”‚ MCP β”‚ GoMCP Server β”‚ Tools β”‚ β”‚ -β”‚ LLM Agent │◀─────▢│ β”œβ”€ DIP Pipeline & Oracle Guard │◀─────▢│ Environment & β”‚ -β”‚ (Ollama/vLLM) β”‚ β”‚ β”œβ”€ CΒ³ Memory (L0-L3) β”‚ β”‚ Local Resources β”‚ -β”‚ β”‚ β”‚ └─ Sentinel Lattice Sync β”‚ β”‚ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +```mermaid +graph LR + LLM["πŸ€– LLM Agent
(Ollama/vLLM)"] <-->|MCP| Server + + subgraph Server["πŸ›‘οΈ GoMCP Server"] + DIP["DIP Pipeline & Oracle Guard"] + Mem["CΒ³ Memory (L0-L3)"] + Sync["Sentinel Lattice Sync"] + end + + Server <-->|Tools| Env["πŸ’» Environment &
Local Resources"] ``` GoMCP sits between your LLM and the world, providing: @@ -80,18 +84,18 @@ GoMCP implements defense-in-depth with multiple layers: | Layer | Protection | Mechanism | |-------|------------|-----------| -| **Intent** | Malicious prompts | DIP Pipeline + Oracle Deny-First | -| **Memory** | Data leakage | CAFL capability flow control | +| **Intent** | Malicious prompts | [DIP Pipeline](docs/security/dip_pipeline.md) + Oracle Deny-First | +| **Memory** | Data leakage | [CAFL](docs/security/cafl.md) capability flow control | | **Tools** | Tool abuse | Entropy Gate + Circuit Breaker | | **Audit** | Tampering | SHA-256 Decision Logger (immutable) | | **Network** | Unauthorized access | mTLS + Genome Verification | -All security primitives are based on the [Sentinel Lattice](docs/lattice.md) framework with mathematical guarantees. +All security primitives are based on the [Sentinel Lattice](https://github.com/syntrex-lab/sentinel-community/blob/main/docs/rnd/2026-02-25-sentinel-lattice-architecture.md) framework with mathematical guarantees. ## πŸ“š Learn More -- πŸ“š [Full Documentation](docs/) -- πŸ›‘οΈ [Sentinel Lattice Specification](docs/lattice.md) +- πŸ“š [Full Documentation](docs/README.md) +- πŸ›‘οΈ [Sentinel Lattice Specification](https://github.com/syntrex-lab/sentinel-community/blob/main/docs/rnd/2026-02-25-sentinel-lattice-architecture.md) - πŸ”§ [MCP Tools Reference](docs/mcp-tools.md) - 🏒 [Enterprise Features](https://syntrex.pro) - πŸ’¬ [Discord Community](https://discord.gg/syntrex) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..864f687 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,13 @@ +# GoMCP Documentation + +Welcome to the GoMCP documentation. GoMCP is the open-source, mathematically proven secure memory core and orchestration engine for Large Language Models (LLMs). Built on the principles of the Sentinel Lattice, it provides persistent memory with unforgeable constraints. + +## Table of Contents + +- [**MCP Tools Reference**](mcp-tools.md) β€” Exhaustive list of 57+ built-in Memory, Session, and Safety tools. +- [**DIP Pipeline**](security/dip_pipeline.md) β€” The Declarative Intent Parser that forms the first line of defense. +- [**CAFL Protocol**](security/cafl.md) β€” Capability-Attenuating Flow Labels and Data Provenance. + +## About Sentinel Lattice + +GoMCP uses the Sentinel Lattice framework to enforce security primitives. For in-depth theoretical understanding, see the [Sentinel Lattice Architecture Specification](https://github.com/syntrex-lab/sentinel-community/blob/main/docs/rnd/2026-02-25-sentinel-lattice-architecture.md). diff --git a/docs/mcp-tools.md b/docs/mcp-tools.md new file mode 100644 index 0000000..0a4fa75 --- /dev/null +++ b/docs/mcp-tools.md @@ -0,0 +1,50 @@ +# GoMCP Tool Reference + +GoMCP exposes a rich set of native MCP tools right out of the box, organized into several categories. These tools provide persistent memory, cognitive state management, and causal reasoning to connected Language Models. + +## Memory Tools +These tools manage the Multi-level (L0-L3) Memory Hierarchy, allowing agents to persist facts across ephemeral chat sessions. + +- `add_fact`: Add a new hierarchical memory fact (L0–L3). Ensures key learnings are never forgotten. +- `get_fact`: Retrieve a specific fact by its immutable ID. +- `update_fact`: Update an existing fact's content or mark it as stale. +- `delete_fact`: Delete a fact by ID. +- `list_facts`: Filter and list facts by domain (e.g., 'auth', 'database') or hierarchy level. +- `search_facts`: Full-text search across all facts. +- `list_domains`: List all unique fact domains currently known to the agent. +- `get_stale_facts`: Get facts that have been marked stale or are very old and require review. +- `get_l0_facts`: Retrieve the bedrock L0 facts (Project-level invariant facts). +- `fact_stats`: Get statistics about the fact store's size and composition. +- `process_expired`: Iterate through facts with a TTL (Time-to-Live) and trim expired ones. + +## Session Tools +Session tools allow the agent to save its "cognitive state" and reload it later, surviving system restarts and context-window wipes. + +- `save_state`: Save the current cognitive state vector (topics, goals, pending tasks). +- `load_state`: Load a saved cognitive state. +- `list_sessions`: List all persisted session IDs. +- `delete_session`: Delete all versions of a session. +- `restore_or_create`: Quick tool to either restore the most recent state or start fresh. +- `get_compact_state`: Retrieve a compressed summary of the state suited for prompt injection. +- `get_audit_log`: Extract the immutable decision audit log for the current session. + +## Causal Reasoning Tools +Tools for modeling decisions mathematically. + +- `add_causal_node`: Add a node to the reasoning graph (decision, reason, consequence, constraint, alternative, assumption). +- `add_causal_edge`: Connect nodes (justifies, causes, constrains). +- `get_causal_chain`: Query the chain of decisions that led to a specific state. +- `causal_stats`: View causal store sizing statistics. + +## Crystal & Operations +These tools deal with underlying system status and code primitive indexing. + +- `search_crystals`: Search code crystals (abstracted AST representations of code primitives). +- `get_crystal`: Retrieve a code crystal. +- `list_crystals`: List all indexed code crystals. +- `crystal_stats`: Sizing of the code crystal index. +- `health`: Check GoMCP health metrics. +- `version`: Server build version and git commit hash. +- `dashboard`: Get aggregate statistics across all subsystems. + +*There are an additional 11 NLP-based bridging tools available if GoMCP is run with the `-bridge-script` flag for Python integration.* diff --git a/docs/security/cafl.md b/docs/security/cafl.md new file mode 100644 index 0000000..359e250 --- /dev/null +++ b/docs/security/cafl.md @@ -0,0 +1,31 @@ +# Capability-Attenuating Flow Labels (CAFL) + +**CAFL** is a genuinely new defense primitive introduced by Sentinel Lattice within the GoMCP architecture. While existing Information Flow Control (IFC) mechanisms assume deterministic programs, CAFL operates on the assumption that an LLM can perform **any** information transformation (worst-case taint propagation). + +## Attenuation Over Time + +Every data object in the GoMCP execution context carries a set of *capability labels* (e.g., `{read, process, transform, export, delete}`). CAFL enforces a unidirectional rule: **Capabilities can only DECREASE across boundaries.** + +### Example Flow + +1. **Tool Output Returns Sensitive Data** + `file_read(.env) -> output features capabilities: {process, display}` + *(Note the lack of the `{export}` capability.)* +2. **LLM Interaction** + The LLM parses the data and returns a response. The response inherently inherits the *most restrictive* (most attenuated) capabilities of all inputs it consumed. +3. **Execution Block** + If the LLM now attempts a tool call: + `email_send(body: LLM_response) -> operation requires {export}` + Because the `.env` data attenuated the flow's capabilities (removing `{export}`), the chain is **BLOCKED**. + +## The Membrane Pattern + +Trust boundary crossings inherently attenuate capabilities unless explicitly authorized by the developer: + +- **Internal β†’ External:** Removes `{export}` +- **User β†’ System:** Removes `{modify_config}` +- **Session β†’ Persistent:** Removes `{ephemeral}` + +This means that even if a prompt injection tricks the LLM into initiating an exfiltration attempt, the mathematical capabilities of the data prevent the outbound network call. + +See the full mathematical foundation in the [Sentinel Lattice Architecture Specification](https://github.com/syntrex-lab/sentinel-community/blob/main/docs/rnd/2026-02-25-sentinel-lattice-architecture.md). diff --git a/docs/security/dip_pipeline.md b/docs/security/dip_pipeline.md new file mode 100644 index 0000000..de337fe --- /dev/null +++ b/docs/security/dip_pipeline.md @@ -0,0 +1,15 @@ +# DIP Pipeline (Declarative Intent Parsing) + +The **DIP Pipeline** is the first line of defense in the GoMCP architecture, designed to thwart malicious prompts and adversarial intent before they ever reach the underlying LLM. + +## How it Works + +Traditional security proxies rely heavily on blacklists, regex, or second-model classifiers to detect a "jailbreak." The DIP pipeline flips this paradigm: + +1. **Deny-First Oracle**: Instead of allowing all inputs except identified threats, the system denies all inputs except identified benign operations. +2. **Intent Distillation**: It parses the text, extracts the fundamental "intent vector," and compares it to a rigid list of allowed capabilities. +3. **Entropy Gate**: Analyzes Shannon entropy of text to detect adversarial/chaotic signals and encoded payloads. + +## Lattice Integration + +DIP feeds directly into the larger [Sentinel Lattice](https://github.com/syntrex-lab/sentinel-community/blob/main/docs/rnd/2026-02-25-sentinel-lattice-architecture.md) architecture by creating early *Provenance Certificates*. This guarantees that even if a prompt "tricks" the semantic layers, the root source (the external untrusted user) is forever linked mathematically to the parsed intent.