GUARDRAIL: Gateway for Unified Access, Resource Delegation, and Risk-Attenuating Information Limits
#Technical Specification v1.0
#1. Introduction
#1.1 Purpose
This document specifies the GUARDRAIL security framework for Model Context Protocol (MCP) environments. GUARDRAIL addresses information flow security challenges in LLM application ecosystems by implementing comprehensive security controls to prevent unauthorized data infiltration and exfiltration.
#1.2 Scope
This specification covers:
- Core architecture and components
- Information flow control mechanisms
- Context verification processes
- Request control systems
- Execution containment rules
- Audit and monitoring requirements
- Implementation guidelines for MCP environments
#1.3 References
- Model Context Protocol Specification
- SHIELD Specification v1.1
- NIST SP 800-53: Security and Privacy Controls
- OWASP API Security Top 10
#1.4 Terminology
- Information Flow: Movement of data between security boundaries
- Context: The execution environment and trust properties of a system
- Capability: A transferable, attenuable token granting specific permissions
- Classification: Sensitivity level assigned to information
- Attestation: Verification of system or component properties
#2. Core Architecture
#2.1 Layer Structure
GUARDRAIL implements a layered security architecture:
- Information Gateway Layer (IGL)
- Context Verification Layer (CVL)
- Request Control Layer (RCL)
- Execution Containment Layer (ECL)
- Audit and Monitoring Layer (AML)
#2.2 Component Interaction
┌────────────────────────────────────────────────────────┐
│ MCP Client │
└───────────────────────────┬────────────────────────────┘
│
┌───────────────────────────▼────────────────────────────┐
│ Information Gateway Layer │
│ ┌──────────────┐ ┌───────────────┐ ┌────────────┐ │
│ │ Flow Policies │ │Classification │ │ Transport │ │
│ │ Engine │ │ Engine │ │ Security │ │
│ └──────────────┘ └───────────────┘ └────────────┘ │
└───────────────────────────┬────────────────────────────┘
│
┌───────────────────────────▼────────────────────────────┐
│ Context Verification Layer │
│ ┌──────────────┐ ┌───────────────┐ ┌────────────┐ │
│ │ Attestation │ │ Trust Scoring │ │ Policy │ │
│ │ Engine │ │ Engine │ │ Discovery │ │
│ └──────────────┘ └───────────────┘ └────────────┘ │
└───────────────────────────┬────────────────────────────┘
│
┌───────────────────────────▼────────────────────────────┐
│ Request Control Layer │
│ ┌──────────────┐ ┌───────────────┐ ┌────────────┐ │
│ │ Request │ │ Resource │ │ Action │ │
│ │ Filter │ │ Guard │ │ Limiter │ │
│ └──────────────┘ └───────────────┘ └────────────┘ │
└───────────────────────────┬────────────────────────────┘
│
┌───────────────────────────▼────────────────────────────┐
│ Execution Containment Layer │
│ ┌──────────────┐ ┌───────────────┐ ┌────────────┐ │
│ │ Memory │ │ Resource │ │ Call Chain │ │
│ │ Isolation │ │ Quotas │ │ Tracker │ │
│ └──────────────┘ └───────────────┘ └────────────┘ │
└───────────────────────────┬────────────────────────────┘
│
┌───────────────────────────▼────────────────────────────┐
│ Audit and Monitoring Layer │
│ ┌──────────────┐ ┌───────────────┐ ┌────────────┐ │
│ │ Flow │ │ Anomaly │ │ Tamper- │ │
│ │ Logging │ │ Detection │ │ Evidence │ │
│ └──────────────┘ └───────────────┘ └────────────┘ │
└───────────────────────────┬────────────────────────────┘
│
┌───────────────────────────▼────────────────────────────┐
│ MCP Server │
└────────────────────────────────────────────────────────┘
#2.3 Component Requirements
Each component must:
- Operate independently with clear interfaces
- Fail securely if compromised
- Operate with minimum necessary privileges
- Maintain comprehensive audit records
- Support dynamic configuration
#3.1 Flow Policy Engine
3.1.1 Structure
1{
2 "FlowPolicyEngine": {
3 "version": "1.0",
4 "default_policy": "deny",
5 "policy_evaluation_order": ["explicit", "role", "default"],
6 "conflict_resolution": "most_restrictive",
7 "cache_ttl": 300,
8 "emergency_lockdown": false
9 }
10}
3.1.2 Flow Rules Definition
1{
2 "FlowRule": {
3 "id": "string",
4 "name": "string",
5 "description": "string",
6 "priority": "integer",
7 "source": {
8 "type": "string",
9 "identifier": "string",
10 "classification": ["string"]
11 },
12 "destination": {
13 "type": "string",
14 "identifier": "string",
15 "minimum_classification": "string"
16 },
17 "conditions": {
18 "temporal": {
19 "time_window": {
20 "start": "ISO8601_timestamp",
21 "end": "ISO8601_timestamp"
22 },
23 "max_rate": "integer"
24 },
25 "contextual": {
26 "required_trust_level": "float",
27 "required_capabilities": ["string"],
28 "environment_checks": ["string"]
29 }
30 },
31 "transformations": ["string"],
32 "action": "allow|deny|transform",
33 "logging": {
34 "level": "string",
35 "include_content": "boolean"
36 }
37 }
38}
3.1.3 Rule Evaluation Algorithm
- Identify the source and destination of the information flow
- Determine the classification of the information
- Retrieve applicable rules based on source, destination, and classification
- Evaluate rules in priority order
- Apply the action from the first matching rule
- If no rules match, apply the default policy
#3.2 Content Classification Engine
3.2.1 Classification Levels
1{
2 "ClassificationLevels": [
3 {
4 "name": "PUBLIC",
5 "value": 0,
6 "description": "Information safe for public disclosure",
7 "default_flow_action": "allow",
8 "requires_marking": false,
9 "requires_audit": false
10 },
11 {
12 "name": "INTERNAL",
13 "value": 10,
14 "description": "Information restricted to the application",
15 "default_flow_action": "allow",
16 "requires_marking": true,
17 "requires_audit": true
18 },
19 {
20 "name": "SENSITIVE",
21 "value": 20,
22 "description": "Information requiring protection",
23 "default_flow_action": "deny",
24 "requires_marking": true,
25 "requires_audit": true
26 },
27 {
28 "name": "RESTRICTED",
29 "value": 30,
30 "description": "Highly sensitive information",
31 "default_flow_action": "deny",
32 "requires_marking": true,
33 "requires_audit": true
34 }
35 ]
36}
3.2.2 Classification Rules
1{
2 "ClassificationRule": {
3 "id": "string",
4 "name": "string",
5 "description": "string",
6 "priority": "integer",
7 "patterns": [
8 {
9 "type": "regex|semantic|exact",
10 "value": "string",
11 "weight": "float"
12 }
13 ],
14 "threshold": "float",
15 "classification": "string",
16 "confidence_required": "float"
17 }
18}
3.2.3 Classification Process
- Extract content to be classified
- Apply all applicable classification rules
- Compute classification score based on matching patterns
- Assign highest classification level that exceeds its threshold
- Record classification decision and confidence level
- Apply required markings based on classification level
#3.3 Transport Encapsulation
3.3.1 Security Properties
1{
2 "TransportSecurity": {
3 "confidentiality": {
4 "algorithm": "AES-256-GCM",
5 "key_rotation": "24h"
6 },
7 "integrity": {
8 "algorithm": "HMAC-SHA-256",
9 "include_metadata": true
10 },
11 "authentication": {
12 "mechanism": "x509|psk|token",
13 "validation": "every_message"
14 },
15 "replay_protection": {
16 "window_size": 1000,
17 "ttl": 300
18 }
19 }
20}
3.3.2 Transport Adapters
1{
2 "TransportAdapter": {
3 "type": "string",
4 "configuration": {
5 "security_level": "integer",
6 "timeout": "integer",
7 "buffer_size": "integer",
8 "compression": "boolean"
9 },
10 "error_handling": {
11 "retry_attempts": "integer",
12 "backoff_strategy": "string",
13 "failure_action": "string"
14 }
15 }
16}
3.3.3 Message Structure
1{
2 "ProtectedMessage": {
3 "header": {
4 "version": "string",
5 "message_id": "string",
6 "timestamp": "ISO8601_timestamp",
7 "source": "string",
8 "destination": "string",
9 "classification": "string"
10 },
11 "metadata": {
12 "flow_id": "string",
13 "session_id": "string",
14 "correlation_id": "string",
15 "security_context": "string"
16 },
17 "payload": {
18 "type": "string",
19 "encoding": "string",
20 "data": "string"
21 },
22 "security": {
23 "integrity_token": "string",
24 "encryption_info": {
25 "algorithm": "string",
26 "parameters": "string",
27 "key_id": "string"
28 }
29 }
30 }
31}
#4. Context Verification Layer
#4.1 Attestation Engine
4.1.1 Attestation Model
1{
2 "AttestationModel": {
3 "version": "string",
4 "methods": [
5 {
6 "id": "string",
7 "name": "string",
8 "type": "static|dynamic|remote",
9 "trust_weight": "float",
10 "verification_period": "integer",
11 "failure_action": "string"
12 }
13 ],
14 "required_score": "float",
15 "grace_period": "integer"
16 }
17}
4.1.2 Evidence Collection
1{
2 "AttestationEvidence": {
3 "id": "string",
4 "timestamp": "ISO8601_timestamp",
5 "type": "string",
6 "source": "string",
7 "data": {
8 "type": "string",
9 "format": "string",
10 "value": "string"
11 },
12 "metadata": {
13 "collector": "string",
14 "collection_method": "string",
15 "chain_of_custody": ["string"]
16 },
17 "signature": {
18 "algorithm": "string",
19 "value": "string",
20 "key_id": "string"
21 }
22 }
23}
4.1.3 Attestation Process
- Determine required attestation methods based on security context
- Collect evidence using each required method
- Verify each piece of evidence
- Calculate aggregate trust score
- Compare against required threshold
- Issue attestation result with expiration
- Monitor for environmental changes that would invalidate attestation
#4.2 Trust Scoring Engine
4.2.1 Trust Metrics
1{
2 "TrustMetrics": [
3 {
4 "id": "string",
5 "name": "string",
6 "description": "string",
7 "weight": "float",
8 "evaluation_method": "string",
9 "refresh_period": "integer",
10 "thresholds": {
11 "high_trust": "float",
12 "medium_trust": "float",
13 "low_trust": "float"
14 }
15 }
16 ]
17}
4.2.2 Trust Level Calculation
1{
2 "TrustCalculation": {
3 "algorithm": "weighted_average|minimum|bayesian",
4 "normalization": "boolean",
5 "decay_factor": "float",
6 "confidence_requirement": "float"
7 }
8}
4.2.3 Trust Assessment Process
- Collect current values for all trust metrics
- Apply weights to each metric
- Combine according to trust calculation algorithm
- Normalize to produce final trust score (0.0-1.0)
- Map score to discrete trust level
- Record assessment with justification
#4.3 Policy Discovery
4.3.1 Policy Registry
1{
2 "PolicyRegistry": {
3 "policies": [
4 {
5 "id": "string",
6 "name": "string",
7 "version": "string",
8 "type": "string",
9 "applicability": {
10 "environments": ["string"],
11 "classifications": ["string"],
12 "trust_levels": ["string"]
13 },
14 "uri": "string",
15 "hash": "string"
16 }
17 ],
18 "update_frequency": "integer",
19 "validation_method": "string"
20 }
21}
4.3.2 Policy Selection Algorithm
1{
2 "PolicySelection": {
3 "strategy": "most_specific|highest_security|composite",
4 "context_factors": ["environment", "classification", "trust_level"],
5 "override_rules": [
6 {
7 "condition": "string",
8 "policy_id": "string",
9 "priority": "integer"
10 }
11 ],
12 "conflict_resolution": "most_restrictive|most_recent|explicit_priority"
13 }
14}
4.3.3 Policy Discovery Process
- Determine current security context (environment, classification, trust level)
- Query policy registry for applicable policies
- Apply selection algorithm to choose specific policies
- Resolve any conflicts according to conflict resolution rules
- Retrieve and validate selected policies
- Apply policies to current session
#5. Request Control Layer
#5.1 Request Filter
5.1.1 Filter Configuration
1{
2 "RequestFilter": {
3 "enabled": true,
4 "default_action": "deny",
5 "inspection_depth": "integer",
6 "max_request_size": "integer",
7 "rate_limiting": {
8 "window_size": "integer",
9 "max_requests": "integer",
10 "per_client": true
11 }
12 }
13}
5.1.2 Request Validation Rules
1{
2 "ValidationRule": {
3 "id": "string",
4 "name": "string",
5 "target": "headers|parameters|body|method",
6 "operation": "presence|format|range|enum|custom",
7 "parameters": {
8 "pattern": "string",
9 "min_value": "number",
10 "max_value": "number",
11 "allowed_values": ["string"],
12 "custom_validator": "string"
13 },
14 "action": "allow|deny|sanitize|transform",
15 "severity": "info|warning|error|critical"
16 }
17}
5.1.3 Request Processing Pipeline
- Receive incoming request
- Apply size and rate limits
- Parse and normalize request
- Apply validation rules in sequence
- Execute transformations for matching rules
- Block request if any critical rules match
- Forward validated request to next layer
#5.2 Resource Guard
5.2.1 Resource Descriptor
1{
2 "Resource": {
3 "id": "string",
4 "type": "string",
5 "uri": "string",
6 "name": "string",
7 "description": "string",
8 "owner": "string",
9 "classification": "string",
10 "operations": [
11 {
12 "name": "string",
13 "description": "string",
14 "required_capability": "string",
15 "required_trust_level": "float"
16 }
17 ],
18 "metadata": {
19 "created": "ISO8601_timestamp",
20 "modified": "ISO8601_timestamp",
21 "version": "string"
22 }
23 }
24}
5.2.2 Access Control Rules
1{
2 "AccessControl": {
3 "strategy": "capability|acl|rbac",
4 "default_policy": "deny",
5 "rules": [
6 {
7 "principal": "string",
8 "resource": "string",
9 "operations": ["string"],
10 "conditions": {
11 "temporal": {
12 "valid_from": "ISO8601_timestamp",
13 "valid_until": "ISO8601_timestamp",
14 "time_of_day": ["string"]
15 },
16 "environmental": {
17 "min_trust_level": "float",
18 "source_constraints": ["string"],
19 "system_state": ["string"]
20 }
21 }
22 }
23 ],
24 "inheritance": "boolean",
25 "delegation": {
26 "allowed": "boolean",
27 "max_depth": "integer",
28 "restrictions": ["string"]
29 }
30 }
31}
5.2.3 Resource Access Flow
- Identify the resource being accessed
- Determine the operation being requested
- Verify the requestor's identity and capabilities
- Check access control rules for explicit matches
- Apply default policy if no explicit rules match
- Record access attempt with outcome
- Apply any output transformations required by classification
#5.3 Action Limiter
5.3.1 Action Constraints
1{
2 "ActionConstraint": {
3 "id": "string",
4 "name": "string",
5 "action_type": "string",
6 "scope": "global|session|client",
7 "limits": {
8 "rate": {
9 "count": "integer",
10 "window": "integer"
11 },
12 "quota": {
13 "total": "integer",
14 "reset_period": "integer"
15 },
16 "concurrency": {
17 "max": "integer"
18 }
19 },
20 "enforcement": "strict|soft",
21 "violation_action": "block|throttle|notify"
22 }
23}
5.3.2 Action Context
1{
2 "ActionContext": {
3 "action_id": "string",
4 "session_id": "string",
5 "client_id": "string",
6 "request_path": "string",
7 "parameters": ["string"],
8 "resource_impact": {
9 "cpu": "float",
10 "memory": "integer",
11 "io": "integer",
12 "network": "integer"
13 },
14 "security_impact": {
15 "classification_level": "string",
16 "privilege_level": "string",
17 "blast_radius": "string"
18 }
19 }
20}
5.3.3 Limiting Process
- Identify the action type from the request
- Load applicable constraints for the action
- Retrieve current usage metrics for the scope
- Evaluate constraints against current usage
- Apply enforcement action if limits exceeded
- Update usage metrics
- Attach limit metadata to request context
#6. Execution Containment Layer
#6.1 Memory Isolation
6.1.1 Isolation Configuration
1{
2 "MemoryIsolation": {
3 "mechanism": "process|container|vm|language",
4 "enforcement": "hardware|software|hybrid",
5 "granularity": "process|thread|object|region",
6 "permissions": {
7 "read": "boolean",
8 "write": "boolean",
9 "execute": "boolean"
10 }
11 }
12}
6.1.2 Memory Protection Rules
1{
2 "MemoryProtection": {
3 "regions": [
4 {
5 "name": "string",
6 "base_address": "integer",
7 "size": "integer",
8 "protection": "rwx|ro|none",
9 "classification": "string"
10 }
11 ],
12 "default_protection": "string",
13 "canaries": "boolean",
14 "aslr": "boolean",
15 "dep": "boolean"
16 }
17}
6.1.3 Memory Access Control
- Initialize memory regions with appropriate protections
- Monitor memory access attempts
- Validate access against protection rules
- Block unauthorized access attempts
- Log memory protection violations
- Apply memory sanitization on release
#6.2 Resource Quotas
6.2.1 Quota Configuration
1{
2 "ResourceQuotas": {
3 "cpu": {
4 "limit": "float",
5 "burst": "float",
6 "period": "integer"
7 },
8 "memory": {
9 "limit": "integer",
10 "reservation": "integer"
11 },
12 "storage": {
13 "limit": "integer",
14 "reservation": "integer"
15 },
16 "network": {
17 "ingress_mbps": "integer",
18 "egress_mbps": "integer",
19 "connections": "integer"
20 },
21 "operations": {
22 "requests_per_second": "integer",
23 "concurrent_operations": "integer"
24 }
25 }
26}
6.2.2 Resource Accounting
1{
2 "ResourceAccounting": {
3 "tracking_granularity": "request|session|client",
4 "measurement_interval": "integer",
5 "resource_metrics": ["cpu", "memory", "io", "network"],
6 "alerting_threshold": "float"
7 }
8}
6.2.3 Quota Enforcement
- Establish resource quotas for each execution context
- Monitor resource usage continuously
- Predict resource needs before executing operations
- Block operations that would exceed quotas
- Reclaim resources when they are no longer needed
- Enforce fair sharing of resources between contexts
#6.3 Call Chain Tracking
6.3.1 Call Chain Model
1{
2 "CallChainModel": {
3 "tracking_enabled": true,
4 "max_depth": "integer",
5 "attributes_tracked": ["caller", "operation", "parameters", "context"],
6 "storage_duration": "integer"
7 }
8}
6.3.2 Stack Frame
1{
2 "StackFrame": {
3 "id": "string",
4 "caller": "string",
5 "operation": "string",
6 "timestamp": "ISO8601_timestamp",
7 "parameters": [
8 {
9 "name": "string",
10 "type": "string",
11 "value_hash": "string",
12 "classification": "string"
13 }
14 ],
15 "context": {
16 "trust_level": "float",
17 "capabilities": ["string"],
18 "classification": "string"
19 }
20 }
21}
6.3.3 Call Chain Validation
- Initialize call chain for new execution context
- Push stack frame for each function/method call
- Validate operation against security policy
- Check for suspicious patterns or behaviors
- Pop stack frame upon operation completion
- Associate call chain with audit records
#7. Audit and Monitoring Layer
#7.1 Flow Logging
7.1.1 Log Configuration
1{
2 "FlowLogging": {
3 "enabled": true,
4 "level": "debug|info|warn|error",
5 "destinations": ["file", "database", "syslog"],
6 "format": "json|syslog|custom",
7 "rotation": {
8 "size": "integer",
9 "interval": "integer",
10 "retention": "integer"
11 }
12 }
13}
7.1.2 Log Record Structure
1{
2 "FlowRecord": {
3 "id": "string",
4 "timestamp": "ISO8601_timestamp",
5 "sequence": "integer",
6 "flow_type": "request|response|notification|internal",
7 "source": {
8 "id": "string",
9 "type": "string"
10 },
11 "destination": {
12 "id": "string",
13 "type": "string"
14 },
15 "operation": "string",
16 "resource": "string",
17 "classification": "string",
18 "size": "integer",
19 "decision": "allow|deny|transform",
20 "reason": "string",
21 "context": {
22 "session_id": "string",
23 "correlation_id": "string",
24 "trust_level": "float"
25 },
26 "metadata": {
27 "key": "value"
28 }
29 }
30}
7.1.3 Logging Process
- Capture flow events at layer boundaries
- Construct flow record with relevant metadata
- Apply privacy controls based on classification
- Sign record for integrity
- Store according to retention policy
- Forward to monitoring system for analysis
#7.2 Anomaly Detection
7.2.1 Detection Rules
1{
2 "AnomalyRule": {
3 "id": "string",
4 "name": "string",
5 "description": "string",
6 "type": "pattern|statistical|behavioral|hybrid",
7 "parameters": {
8 "baseline_period": "integer",
9 "detection_threshold": "float",
10 "min_confidence": "float"
11 },
12 "pattern": "string",
13 "severity": "info|warning|error|critical",
14 "response": "log|alert|block"
15 }
16}
7.2.2 Behavioral Baseline
1{
2 "Baseline": {
3 "entity_id": "string",
4 "entity_type": "client|server|user|resource",
5 "metrics": [
6 {
7 "name": "string",
8 "statistical_model": "string",
9 "values": {
10 "mean": "float",
11 "median": "float",
12 "std_dev": "float",
13 "min": "float",
14 "max": "float"
15 },
16 "patterns": [
17 {
18 "name": "string",
19 "confidence": "float"
20 }
21 ]
22 }
23 ],
24 "last_updated": "ISO8601_timestamp",
25 "confidence": "float"
26 }
27}
7.2.3 Detection Process
- Collect and preprocess flow records
- Compare against established baselines
- Apply detection rules to identify anomalies
- Calculate confidence score for each detected anomaly
- Filter anomalies based on severity and confidence
- Generate alerts for significant anomalies
- Update baselines with new observations
#7.3 Tamper-Evidence
7.3.1 Evidence Chain
1{
2 "EvidenceChain": {
3 "algorithm": "merkle|hash_chain|blockchain",
4 "hash_function": "SHA-256|SHA-3|BLAKE2",
5 "seal_interval": "integer",
6 "verification_tokens": {
7 "interval": "integer",
8 "distribution": ["local", "remote", "trusted_party"]
9 }
10 }
11}
7.3.2 Forensic Snapshot
1{
2 "ForensicSnapshot": {
3 "id": "string",
4 "timestamp": "ISO8601_timestamp",
5 "trigger": "scheduled|incident|request",
6 "scope": "system|session|flow",
7 "content": [
8 {
9 "type": "string",
10 "data": "string",
11 "metadata": {
12 "source": "string",
13 "collector": "string",
14 "hash": "string"
15 }
16 }
17 ],
18 "chain_position": {
19 "previous_hash": "string",
20 "merkle_root": "string"
21 },
22 "signature": {
23 "algorithm": "string",
24 "value": "string",
25 "key_id": "string"
26 }
27 }
28}
7.3.3 Evidence Preservation
- Generate cryptographic hash of each audit record
- Incorporate hash into the evidence chain
- Periodically seal the chain by creating verification tokens
- Distribute verification tokens to trusted parties
- Create forensic snapshots at regular intervals or triggered by events
- Store evidence securely with appropriate retention periods
- Support verification of chain integrity and individual records
#8. Implementation Guidelines
#8.1 MCP Integration
8.1.1 Client Integration
1// Example TypeScript integration with MCP Client
2import { Client, ClientOptions } from "@modelcontextprotocol/sdk/client";
3import { GuardrailClient, GuardrailOptions } from "@guardrail/sdk/client";
4
5interface SecureClientOptions extends ClientOptions {
6 security: GuardrailOptions;
7}
8
9function createSecureClient(options: SecureClientOptions): Client {
10 // Create standard MCP client
11 const mcpClient = new Client({
12 name: options.name,
13 version: options.version
14 });
15
16 // Wrap with Guardrail protection
17 return new GuardrailClient(mcpClient, {
18 security: options.security
19 });
20}
8.1.2 Server Integration
1// Example TypeScript integration with MCP Server
2import { Server, ServerOptions } from "@modelcontextprotocol/sdk/server";
3import { GuardrailServer, GuardrailOptions } from "@guardrail/sdk/server";
4
5interface SecureServerOptions extends ServerOptions {
6 security: GuardrailOptions;
7}
8
9function createSecureServer(options: SecureServerOptions): Server {
10 // Create standard MCP server
11 const mcpServer = new Server({
12 name: options.name,
13 version: options.version
14 }, {
15 capabilities: options.capabilities
16 });
17
18 // Apply Guardrail protection
19 return new GuardrailServer(mcpServer, {
20 security: options.security
21 });
22}
8.1.3 Transport Security
1// Secure transport implementation
2import { Transport } from "@modelcontextprotocol/sdk/transport";
3import { GuardrailTransport } from "@guardrail/sdk/transport";
4
5function createSecureTransport(baseTransport: Transport): Transport {
6 return new GuardrailTransport(baseTransport, {
7 encryption: {
8 algorithm: "AES-256-GCM",
9 key_rotation_hours: 24
10 },
11 integrity: {
12 algorithm: "HMAC-SHA-256",
13 include_metadata: true
14 },
15 authentication: {
16 mechanism: "token",
17 token_ttl: 3600
18 },
19 replay_protection: true
20 });
21}
#8.2 Configuration Management
8.2.1 Configuration Format
1{
2 "GuardrailConfig": {
3 "version": "1.0",
4 "layers": {
5 "information_gateway": {
6 "enabled": true,
7 "flow_policy": "standard",
8 "classification_engine": "enabled",
9 "transport_security": "high"
10 },
11 "context_verification": {
12 "enabled": true,
13 "attestation": "required",
14 "trust_scoring": "enabled",
15 "policy_discovery": "enabled"
16 },
17 "request_control": {
18 "enabled": true,
19 "request_filter": "strict",
20 "resource_guard": "enabled",
21 "action_limiter": "enabled"
22 },
23 "execution_containment": {
24 "enabled": true,
25 "memory_isolation": "process",
26 "resource_quotas": "enforced",
27 "call_chain_tracking": "enabled"
28 },
29 "audit_monitoring": {
30 "enabled": true,
31 "flow_logging": "comprehensive",
32 "anomaly_detection": "enabled",
33 "tamper_evidence": "enabled"
34 }
35 },
36 "profiles": {
37 "high_security": {
38 "description": "Maximum security profile",
39 "layers": {
40 "information_gateway": {
41 "flow_policy": "strict",
42 "classification_engine": "aggressive",
43 "transport_security": "maximum"
44 },
45 "context_verification": {
46 "attestation": "hardware",
47 "trust_scoring": "continuous",
48 "policy_discovery": "enforced"
49 },
50 "request_control": {
51 "request_filter": "maximum",
52 "resource_guard": "strict",
53 "action_limiter": "aggressive"
54 },
55 "execution_containment": {
56 "memory_isolation": "vm",
57 "resource_quotas": "strict",
58 "call_chain_tracking": "comprehensive"
59 },
60 "audit_monitoring": {
61 "flow_logging": "full_content",
62 "anomaly_detection": "real_time",
63 "tamper_evidence": "blockchain"
64 }
65 }
66 },
67 "standard": {
68 "description": "Balanced security profile",
69 "layers": {
70 "information_gateway": {
71 "flow_policy": "standard",
72 "classification_engine": "enabled",
73 "transport_security": "high"
74 },
75 "context_verification": {
76 "attestation": "required",
77 "trust_scoring": "enabled",
78 "policy_discovery": "enabled"
79 },
80 "request_control": {
81 "request_filter": "strict",
82 "resource_guard": "enabled",
83 "action_limiter": "enabled"
84 },
85 "execution_containment": {
86 "memory_isolation": "process",
87 "resource_quotas": "enforced",
88 "call_chain_tracking": "enabled"
89 },
90 "audit_monitoring": {
91 "flow_logging": "comprehensive",
92 "anomaly_detection": "enabled",
93 "tamper_evidence": "enabled"
94 }
95 }
96 },
97 "performance": {
98 "description": "Performance-optimized profile",
99 "layers": {
100 "information_gateway": {
101 "flow_policy": "basic",
102 "classification_engine": "minimal",
103 "transport_security": "standard"
104 },
105 "context_verification": {
106 "attestation": "periodic",
107 "trust_scoring": "basic",
108 "policy_discovery": "enabled"
109 },
110 "request_control": {
111 "request_filter": "basic",
112 "resource_guard": "enabled",
113 "action_limiter": "basic"
114 },
115 "execution_containment": {
116 "memory_isolation": "language",
117 "resource_quotas": "monitored",
118 "call_chain_tracking": "minimal"
119 },
120 "audit_monitoring": {
121 "flow_logging": "essential",
122 "anomaly_detection": "basic",
123 "tamper_evidence": "hash_chain"
124 }
125 }
126 }
127 }
128 }
129}
8.2.2 Configuration Validation
1function validateConfiguration(config: GuardrailConfig): ValidationResult {
2 // Schema validation
3 const schemaErrors = validateSchema(config, GuardrailConfigSchema);
4
5 // Security validation
6 const securityErrors = validateSecurityRequirements(config);
7
8 // Consistency validation
9 const consistencyErrors = validateConsistency(config);
10
11 return {
12 valid: schemaErrors.length === 0 && securityErrors.length === 0 && consistencyErrors.length === 0,
13 errors: [...schemaErrors, ...securityErrors, ...consistencyErrors]
14 };
15}
8.2.3 Dynamic Reconfiguration
1async function reconfigureGuardrail(server: GuardrailServer, newConfig: GuardrailConfig): Promise<void> {
2 // Validate new configuration
3 const validation = validateConfiguration(newConfig);
4 if (!validation.valid) {
5 throw new Error(`Invalid configuration: ${validation.errors.join(', ')}`);
6 }
7
8 // Create configuration diff
9 const diff = diffConfigurations(server.getConfiguration(), newConfig);
10
11 // Apply changes in safe order
12 await server.prepareReconfiguration();
13
14 // Update each layer in sequence
15 for (const layer of ['audit_monitoring', 'execution_containment', 'request_control', 'context_verification', 'information_gateway']) {
16 if (diff.layers[layer]) {
17 await server.reconfigureLayer(layer, newConfig.layers[layer]);
18 }
19 }
20
21 // Commit changes
22 await server.commitReconfiguration();
23}
#8.3 Deployment Models
8.3.1 Embedded Model
┌─────────────────────────────────────────────────────┐
│ Host Process │
│ │
│ ┌──────────────┐ ┌───────────────────┐ │
│ │ │ │ │ │
│ │ MCP Client │◄─────────►│ MCP Server │ │
│ │ │ │ │ │
│ └──────┬───────┘ └─────────┬─────────┘ │
│ │ │ │
│ ┌──────▼───────┐ ┌─────────▼─────────┐ │
│ │ GUARDRAIL │ │ GUARDRAIL │ │
│ │ Client │◄─────────►│ Server │ │
│ │ Module │ │ Module │ │
│ └──────────────┘ └───────────────────┘ │
│ │
└─────────────────────────────────────────────────────┘
8.3.2 Gateway Model
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ │ │ │ │ │
│ MCP Client │◄─────►│ GUARDRAIL │◄─────►│ MCP Server │
│ │ │ Gateway │ │ │
│ │ │ │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
8.3.3 Service Mesh Model
┌─────────────────────────┐ ┌─────────────────────────┐
│ Client Pod │ │ Server Pod │
│ │ │ │
│ ┌─────────────────┐ │ │ ┌─────────────────┐ │
│ │ │ │ │ │ │ │
│ │ MCP Client │ │ │ │ MCP Server │ │
│ │ │ │ │ │ │ │
│ └────────┬────────┘ │ │ └────────┬────────┘ │
│ │ │ │ │ │
│ ┌────────▼────────┐ │ │ ┌────────▼────────┐ │
│ │ GUARDRAIL │ │ │ │ GUARDRAIL │ │
│ │ Sidecar │◄───┼───────┼──►│ Sidecar │ │
│ │ │ │ │ │ │ │
│ └─────────────────┘ │ │ └─────────────────┘ │
│ │ │ │
└─────────────────────────┘ └─────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────┐
│ GUARDRAIL Control Plane │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ Policy │ │ Identity │ │ Audit │ │
│ │ Server │ │ Service │ │ Collector │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
#9. Security Considerations
#9.1 Threat Model
9.1.1 Adversary Capabilities
1{
2 "AdversaryModel": {
3 "external_attacker": {
4 "network_access": true,
5 "protocol_knowledge": true,
6 "computational_resources": "medium"
7 },
8 "malicious_plugin": {
9 "execution_access": true,
10 "api_access": true,
11 "persistence": "limited"
12 },
13 "malicious_model": {
14 "prompt_manipulation": true,
15 "output_manipulation": true,
16 "system_knowledge": "partial"
17 },
18 "compromised_client": {
19 "credential_access": true,
20 "full_api_access": true,
21 "system_access": "partial"
22 }
23 }
24}
9.1.2 Attack Vectors
-
Data Exfiltration
- Extracting sensitive information from the system
- Bypassing data loss prevention controls
- Covert channels for information leakage
-
Data Infiltration
- Injecting malicious content into the system
- Prompt injection attacks against LLMs
- Poisoning input data
-
Authentication Bypass
- Credential theft
- Session hijacking
- Token forgery
-
Authorization Bypass
- Privilege escalation
- Capability abuse
- Access control bypass
-
Resource Abuse
- Denial of service
- Resource exhaustion
- Rate limiting bypass
-
Supply Chain
- Compromised dependencies
- Malicious plugins
- Backdoored components
9.1.3 Critical Assets
1{
2 "CriticalAssets": [
3 {
4 "name": "User credentials",
5 "impact": "high",
6 "protection_mechanisms": ["encryption", "access_control", "audit"]
7 },
8 {
9 "name": "API tokens",
10 "impact": "high",
11 "protection_mechanisms": ["rotation", "scope_limitation", "monitoring"]
12 },
13 {
14 "name": "Sensitive user data",
15 "impact": "high",
16 "protection_mechanisms": ["classification", "flow_control", "encryption"]
17 },
18 {
19 "name": "Model context",
20 "impact": "medium",
21 "protection_mechanisms": ["sanitization", "access_control", "monitoring"]
22 },
23 {
24 "name": "Configuration data",
25 "impact": "medium",
26 "protection_mechanisms": ["validation", "integrity_checking", "access_control"]
27 },
28 {
29 "name": "Audit logs",
30 "impact": "medium",
31 "protection_mechanisms": ["tamper_evidence", "encryption", "backup"]
32 }
33 ]
34}
#9.2 Countermeasures
9.2.1 Data Exfiltration Countermeasures
-
Content Classification
- Automated classification of all data
- Marking of sensitive information
- Validation of classification before transfers
-
Flow Control
- Policy-based restrictions on information movement
- Content-aware filtering
- Transformation and redaction of sensitive data
-
Transport Protection
- Encrypted communications
- Secure channels
- Controlled endpoints
9.2.2 Data Infiltration Countermeasures
-
Input Validation
- Strict schema validation
- Content filtering
- Sanitization of potentially malicious content
-
Prompt Security
- LLM prompt hardening
- Prompt injection detection
- Context isolation
-
Source Verification
- Verification of data origin
- Integrity checking
- Reputation-based filtering
9.2.3 Authentication Protections
-
Strong Identity
- Multi-factor authentication
- Hardware-backed credentials
- Biometric verification when applicable
-
Credential Protection
- Secure credential storage
- Regular rotation
- Limited scope and lifetime
-
Session Security
- Secure session management
- Automatic timeouts
- Context-aware validation
9.2.4 Authorization Protections
-
Principle of Least Privilege
- Minimal grants by default
- Just-in-time access
- Regular privilege review
-
Capability-Based Control
- Fine-grained capabilities
- Limited delegation
- Capability revocation
-
Context-Aware Access
- Environmental factors in access decisions
- Risk-based authentication
- Continuous authorization
#9.3 Security Testing
9.3.1 Testing Methods
1{
2 "SecurityTesting": {
3 "static_analysis": {
4 "frequency": "continuous",
5 "tools": ["code_scanners", "dependency_checkers"],
6 "scope": "all_code"
7 },
8 "dynamic_analysis": {
9 "frequency": "weekly",
10 "tools": ["fuzzing", "penetration_testing"],
11 "scope": "exposed_interfaces"
12 },
13 "security_review": {
14 "frequency": "quarterly",
15 "type": "manual_expert_review",
16 "scope": "architecture_and_critical_components"
17 },
18 "red_team": {
19 "frequency": "biannual",
20 "type": "adversarial_assessment",
21 "scope": "full_system"
22 }
23 }
24}
9.3.2 Test Cases
-
Information Flow Testing
- Test classification accuracy
- Verify flow control enforcement
- Attempt unauthorized information transfers
-
Authentication Testing
- Verify credential protection
- Test authentication bypasses
- Check for token vulnerabilities
-
Authorization Testing
- Test capability enforcement
- Verify privilege boundaries
- Attempt escalation and delegation attacks
-
Resource Control Testing
- Test quota enforcement
- Verify isolation boundaries
- Attempt resource exhaustion
-
Audit Testing
- Verify log integrity
- Test tamper evidence
- Validate detection capabilities
9.3.3 Security Metrics
1{
2 "SecurityMetrics": [
3 {
4 "name": "Mean time to detection",
5 "description": "Average time to detect security incidents",
6 "target": "< 1 hour",
7 "measurement": "time_series"
8 },
9 {
10 "name": "False positive rate",
11 "description": "Percentage of security alerts that are false positives",
12 "target": "< 5%",
13 "measurement": "percentage"
14 },
15 {
16 "name": "Security test coverage",
17 "description": "Percentage of security controls covered by automated tests",
18 "target": "> 90%",
19 "measurement": "percentage"
20 },
21 {
22 "name": "Vulnerability closure time",
23 "description": "Average time to remediate identified vulnerabilities",
24 "target": "critical: < 24h, high: < 7d, medium: < 30d",
25 "measurement": "time_period"
26 },
27 {
28 "name": "Security maturity level",
29 "description": "Overall security maturity according to framework",
30 "target": "Level 4+",
31 "measurement": "level"
32 }
33 ]
34}
10.1.1 Level 1: Basic Security
1{
2 "Level1Requirements": [
3 {
4 "id": "L1-IGL-1",
5 "description": "Basic information flow control",
6 "verification": "functional_test"
7 },
8 {
9 "id": "L1-CVL-1",
10 "description": "Client/server identity verification",
11 "verification": "functional_test"
12 },
13 {
14 "id": "L1-RCL-1",
15 "description": "Basic access control for resources",
16 "verification": "functional_test"
17 },
18 {
19 "id": "L1-ECL-1",
20 "description": "Process-level isolation",
21 "verification": "functional_test"
22 },
23 {
24 "id": "L1-AML-1",
25 "description": "Security event logging",
26 "verification": "functional_test"
27 }
28 ]
29}
10.1.2 Level 2: Standard Security
1{
2 "Level2Requirements": [
3 {
4 "id": "L2-IGL-1",
5 "description": "Content classification and marking",
6 "verification": "functional_test"
7 },
8 {
9 "id": "L2-CVL-1",
10 "description": "Context-aware trust scoring",
11 "verification": "functional_test"
12 },
13 {
14 "id": "L2-RCL-1",
15 "description": "Capability-based access control",
16 "verification": "functional_test"
17 },
18 {
19 "id": "L2-ECL-1",
20 "description": "Resource quotas enforcement",
21 "verification": "functional_test"
22 },
23 {
24 "id": "L2-AML-1",
25 "description": "Tamper-evident logging",
26 "verification": "functional_test"
27 }
28 ]
29}
10.1.3 Level 3: Enhanced Security
1{
2 "Level3Requirements": [
3 {
4 "id": "L3-IGL-1",
5 "description": "Advanced information flow control with transformations",
6 "verification": "functional_test"
7 },
8 {
9 "id": "L3-CVL-1",
10 "description": "Hardware-backed attestation",
11 "verification": "functional_test"
12 },
13 {
14 "id": "L3-RCL-1",
15 "description": "Fine-grained capability delegation",
16 "verification": "functional_test"
17 },
18 {
19 "id": "L3-ECL-1",
20 "description": "Strong memory isolation and protection",
21 "verification": "functional_test"
22 },
23 {
24 "id": "L3-AML-1",
25 "description": "Real-time anomaly detection",
26 "verification": "functional_test"
27 }
28 ]
29}
#10.2 Compatibility Requirements
10.2.1 MCP Compatibility
1{
2 "MCPCompatibility": {
3 "protocol_version": ">=1.0",
4 "transport_compatibility": [
5 {
6 "transport": "stdio",
7 "compatible": true,
8 "limitations": "none"
9 },
10 {
11 "transport": "http_sse",
12 "compatible": true,
13 "limitations": "none"
14 },
15 {
16 "transport": "websocket",
17 "compatible": true,
18 "limitations": "none"
19 }
20 ],
21 "message_compatibility": {
22 "request_handling": "full",
23 "notification_handling": "full",
24 "result_handling": "full",
25 "error_handling": "extended"
26 }
27 }
28}
10.2.2 Operating Environment Compatibility
1{
2 "EnvironmentCompatibility": {
3 "platforms": [
4 {
5 "os": "Windows",
6 "version": ">=10",
7 "architecture": ["x64", "arm64"],
8 "limitations": "none"
9 },
10 {
11 "os": "macOS",
12 "version": ">=10.15",
13 "architecture": ["x64", "arm64"],
14 "limitations": "none"
15 },
16 {
17 "os": "Linux",
18 "version": "kernel >= 5.4",
19 "architecture": ["x64", "arm64"],
20 "limitations": "none"
21 }
22 ],
23 "runtimes": [
24 {
25 "name": "Node.js",
26 "version": ">=16.x",
27 "limitations": "none"
28 },
29 {
30 "name": "Python",
31 "version": ">=3.8",
32 "limitations": "none"
33 },
34 {
35 "name": "Java",
36 "version": ">=11",
37 "limitations": "none"
38 }
39 ]
40 }
41}
#10.3 Certification Process
10.3.1 Certification Requirements
1{
2 "CertificationProcess": {
3 "documentation": {
4 "required": ["architecture_document", "threat_model", "implementation_guide"],
5 "optional": ["penetration_test_report", "code_review_report"]
6 },
7 "testing": {
8 "self_assessment": {
9 "required": true,
10 "template": "certification_self_assessment.json"
11 },
12 "automated_tests": {
13 "required": true,
14 "minimum_coverage": "90%"
15 },
16 "independent_assessment": {
17 "required_for_level": [3],
18 "assessor_qualifications": ["security_certification", "relevant_experience"]
19 }
20 },
21 "maintenance": {
22 "recertification_period": "annual",
23 "continuous_monitoring": {
24 "required_for_level": [2, 3],
25 "monitoring_aspects": ["vulnerability_reports", "security_updates"]
26 }
27 }
28 }
29}
#11. Appendices
#Appendix A: Reference Implementation
A reference implementation of GUARDRAIL for MCP is available at github.com/guardrail/reference-implementation and includes:
- Core library components for all security layers
- Integration examples with MCP clients and servers
- Test suite for conformance verification
- Documentation and implementation guides
#Appendix B: Security Best Practices
B.1 Development Practices
- Follow secure coding guidelines
- Implement proper error handling
- Use static analysis tools
- Conduct regular code reviews
- Maintain dependency security
B.2 Operational Practices
- Implement secure deployment processes
- Establish incident response procedures
- Conduct regular security testing
- Maintain comprehensive monitoring
- Establish update and patch management
B.3 Integration Practices
- Use defense-in-depth approaches
- Implement proper authentication
- Apply principle of least privilege
- Validate all inputs
- Monitor and log security events
#Appendix C: Glossary
- Attestation: Process of verifying the integrity and identity of a system component
- Capability: Token representing permission to perform specific operations
- Classification: Security sensitivity level assigned to information
- Flow Control: Mechanisms governing the movement of information between security boundaries
- Sandboxing: Isolation techniques to contain code execution
- Tamper-Evidence: Ability to detect unauthorized modifications to data
- Trust Level: Measure of confidence in the security properties of a component
#Version History
