🔒 European Parliament MCP Server — Security Architecture

Implemented Security Controls, Threat Model, and Compliance Mapping
Defense-in-depth security design for parliamentary data access

📋 Document Owner: Hack23 | 📄 Version: 1.2 | 📅 Last Updated: 2026-04-21 (UTC) 🔄 Review Cycle: Quarterly | ⏰ Next Review: 2026-07-21 🏷️ Classification: Public (Open Source MCP Server) ✅ ISMS Compliance: ISO 27001 (A.5.1, A.8.1, A.14.2), NIST CSF 2.0 (ID.AM, PR.DS), CIS Controls v8.1 (2.1, 16.1)

---

📑 Table of Contents

1. Security Documentation Map
2. Executive Summary
3. 4-Layer Security Architecture
4. Security Controls Inventory
5. Threat Mitigation Mapping (STRIDE)
6. Authentication and Authorization
7. Session and Action Tracking
8. Data Integrity and Auditing
9. Data Protection and GDPR
10. Network Security and Perimeter Protection
11. VPC Endpoints and Private Access
12. High Availability and Resilience
13. Threat Detection and Investigation
14. Vulnerability Management
15. Configuration and Compliance Management
16. Security Monitoring and Analytics
17. Automated Security Operations
18. Application Security Controls
19. Defense-in-Depth Strategy
20. Security Testing Requirements
21. Compliance Framework Mapping

---

🗺️ Security Documentation Map

Document	Current	Future	Description
Architecture	ARCHITECTURE.md	FUTURE_ARCHITECTURE.md	C4 model, containers, components, ADRs
Security Architecture	SECURITY_ARCHITECTURE.md	FUTURE_SECURITY_ARCHITECTURE.md	Security controls, threat model
Data Model	DATA_MODEL.md	FUTURE_DATA_MODEL.md	Entity relationships, branded types
Flowchart	FLOWCHART.md	FUTURE_FLOWCHART.md	Business process flows
State Diagram	STATEDIAGRAM.md	FUTURE_STATEDIAGRAM.md	System state transitions
Mind Map	MINDMAP.md	FUTURE_MINDMAP.md	System concepts and relationships
SWOT Analysis	SWOT.md	FUTURE_SWOT.md	Strategic positioning
Threat Model	THREAT_MODEL.md	FUTURE_THREAT_MODEL.md	STRIDE, MITRE ATT&CK, attack trees
CRA Assessment	CRA-ASSESSMENT.md	—	EU Cyber Resilience Act conformity
E2E Test Plan	E2ETestPlan.md	—	End-to-end test strategy and coverage matrix
Unit Test Plan	docs/UnitTestPlan.md	—	Unit test plan and coverage targets

---

🎯 Executive Summary

The EP MCP Server implements a 4-layer defense-in-depth security architecture aligned with OWASP best practices, ISO 27001, NIST CSF 2.0, and GDPR requirements. Since the server operates as an MCP stdio process (not a network-exposed server), the primary security concerns are:

1. Input validation — prevent malformed or malicious MCP tool arguments
2. API abuse prevention — protect EP Open Data Portal from overuse
3. Data privacy — GDPR-compliant handling of MEP personal data
4. Audit trail — full traceability of all data access

The server does not handle authentication tokens, passwords, or payment data, significantly reducing the attack surface.

---

🛡️ 4-Layer Security Architecture

flowchart TD
    MCP_IN["MCP Tool Invocation\n(args: unknown)"]

    subgraph L1["Layer 1: Input Validation"]
        ZOD["Zod Schema Validation\nStrict type checking, format enforcement"]
        ZE["ZodError → MCP error response"]
    end

    subgraph L2["Layer 2: Rate Limiting"]
        RL["Token Bucket Rate Limiter\n100 tokens/minute"]
        RLE["Rate limit exceeded → 429 response"]
    end

    subgraph L3["Layer 3: Audit Logging"]
        AL["Audit Logger\nTool name, params (PII-stripped), timestamp, user context"]
    end

    subgraph L4["Layer 4: GDPR Compliance"]
        GDPR["Data Minimization\nPurpose Limitation\nStorage Limitation"]
    end

    EP_API["EP Open Data Portal API v2\n(HTTPS/TLS)"]
    RESULT["Tool Result → MCP Client"]

    MCP_IN --> ZOD
    ZOD -->|"invalid"| ZE
    ZOD -->|"valid"| RL
    RL -->|"exceeded"| RLE
    RL -->|"token available"| AL
    AL --> GDPR
    GDPR --> EP_API
    EP_API --> RESULT
Copy

---

🔐 Security Controls Inventory

Control ID	Control Name	Type	Implementation	Status
SC-001	Input Validation	Preventive	Zod schema per tool (62 schemas) with .refine() cross-field constraints, date range validation, and format-specific ID validation	✅ Implemented
SC-002	Rate Limiting	Preventive	Token bucket, 100 req/min	✅ Implemented
SC-003	Audit Logging	Detective	AuditLogger singleton, all invocations	✅ Implemented
SC-004	GDPR Data Minimization	Preventive	Field selection, no over-fetching	✅ Implemented
SC-005	TLS in Transit	Preventive	HTTPS to EP API, Node TLS defaults	✅ Implemented
SC-006	Dependency Scanning	Detective	Dependabot, npm audit	✅ Implemented
SC-007	Static Analysis	Preventive	ESLint, TypeScript strict mode	✅ Implemented
SC-008	Secret Detection	Preventive	No secrets in codebase; env vars only	✅ Implemented
SC-009	Error Sanitization	Preventive	Internal errors not leaked to MCP clients	✅ Implemented
SC-010	Health Monitoring	Detective	HealthService singleton	✅ Implemented
SC-011	Metrics Collection	Detective	MetricsService, rate/error tracking	✅ Implemented
SC-012	Branded Types	Preventive	Zod branded types for EP identifiers	✅ Implemented
SC-013	Data Quality Controls	Preventive	OSINT outputs standardize confidence level and quality warnings; data availability status is included where implemented	✅ Implemented

---

⚔️ Threat Mitigation Mapping (STRIDE)

Threat Category	Specific Threat	Likelihood	Impact	Mitigation
Spoofing	Fake MCP client identity	Low	Low	stdio transport — client is the spawning process
Tampering	Malicious tool arguments	Medium	Medium	SC-001: Zod validation rejects malformed input
Repudiation	Deny data access occurred	Medium	Medium	SC-003: Immutable audit log with timestamps
Information Disclosure	MEP PII over-exposure	Medium	High	SC-004: Data minimization, GDPR controls
Information Disclosure	Internal error details leaked	Low	Medium	SC-009: Error sanitization
Denial of Service	EP API flooding	Medium	High	SC-002: Rate limiter blocks bursts
Denial of Service	Memory exhaustion via cache	Low	Medium	LRU eviction (max 500 entries)
Elevation of Privilege	Unauthorized tool access	Low	Low	No auth layer needed — local stdio process
Elevation of Privilege	Prototype pollution via input	Low	Medium	SC-001: Zod validation with strict mode
Supply Chain	Malicious npm package	Medium	High	SC-006: Dependabot, npm audit, lockfile
MCP Protocol	Prompt injection, tool abuse (M-1…M-7)	Medium	High	See THREAT_MODEL.md §MCP Threats
LLM Integration	OWASP LLM Top 10 risks (L-01…L-10)	Medium	High	See THREAT_MODEL.md §OWASP LLM

---

🔑 Authentication and Authorization

Current Model (v1.1)

The EP MCP Server operates as a local stdio process spawned by the MCP client (e.g., Claude Desktop). The security model relies on OS-level process isolation:

• No network authentication — the server is not network-exposed
• No user credentials — the server does not handle user tokens
• Process isolation — only the spawning MCP client can communicate via stdio
• EP API access — public open data, no authentication required by EP

Trust Boundaries

flowchart LR
    subgraph TrustHigh["High Trust Zone"]
        OS["Operating System"]
        User["Local User Account"]
    end

    subgraph TrustMedium["Medium Trust Zone"]
        MCP["MCP Client Process\n(Claude Desktop / Cursor)"]
        Server["EP MCP Server Process"]
    end

    subgraph TrustLow["Low Trust Zone"]
        Input["Tool Arguments\n(from AI-generated content)"]
    end

    subgraph External["Untrusted External"]
        EPAPI["EP Open Data Portal\n(public internet)"]
    end

    OS --> MCP
    MCP --> Server
    Server --> Input
    Input -->|"Zod validation"| Server
    Server -->|"HTTPS"| EPAPI
Copy

Key principle: Tool arguments are treated as untrusted input regardless of their origin, since AI models may generate unexpected parameter values.

---

📊 Session and Action Tracking

All user interactions with the MCP server are tracked through the integrated audit and metrics systems:

Session Tracking Model

flowchart LR
    subgraph SessionContext["Session Context"]
        STDIO["stdio Connection\n(1 session per process)"]
        TC["Tool Call Counter"]
        TS["Session Start Time"]
    end

    subgraph ActionTracking["Action Tracking"]
        AL["AuditLogger\n(every tool invocation)"]
        MS["MetricsService\n(aggregated counters)"]
        HS["HealthService\n(process health)"]
    end

    STDIO --> AL
    STDIO --> MS
    AL --> TC
    MS --> TS
    HS --> TC
Copy

Tracked Actions

Action Type	Tracked Fields	Storage	Purpose
Tool invocation	Tool name, sanitized params, timestamp, duration	stderr audit log	Full traceability
API request	URL, status, duration, cache hit/miss	MetricsService	Performance monitoring
Rate limit event	Token count, refill status, rejection	stderr audit log	Abuse detection
Error occurrence	Error type (no stack trace), tool context	stderr audit log	Incident response
Cache operation	Key, hit/miss, eviction	MetricsService	Efficiency tracking

Action Tracking Implementation

• No persistent session storage — session state is in-memory only (process-scoped)
• PII stripping — all logged parameters have personal data fields removed before logging
• Structured logging — JSON format on stderr for machine-parseable audit trail
• Per-tool metrics — invocation count, error count, average duration per tool

---

📜 Data Integrity and Auditing

Data Integrity Controls

Control	Implementation	Verification
Source integrity	All data sourced from official EP API over HTTPS/TLS	TLS certificate validation
Transport integrity	HTTPS with TLS 1.2+ for all API calls	Node.js default TLS verification
Cache integrity	In-memory LRU cache (no persistent storage) — no disk tampering risk	Process isolation
Cache key integrity	Deterministic cache key generation via sorted parameter keys	Prevents cache misses from property insertion order
Schema validation	Zod schemas validate all API responses before processing	TypeScript strict mode + runtime validation
Data quality integrity	OSINT outputs include DataAvailability and dataQualityWarnings (SC-013)	Consumers distinguish "zero" from "unavailable"
Audit immutability	Audit logs written to stderr (append-only within process)	No log modification API exposed
Package integrity	npm lockfile with exact versions, SLSA Level 3 provenance	Provenance attestations, Sigstore signing

Audit Trail Architecture

flowchart TD
    ToolCall["Tool Invocation"] --> AuditLog["AuditLogger.logToolCall()"]
    AuditLog --> PIIStrip["PII Stripping\n(remove personal data fields)"]
    PIIStrip --> Format["JSON Structured Format"]
    Format --> Stderr["stderr Output\n(append-only)"]
    Stderr --> External["External Log Collection\n(host-managed)"]
Copy

Audit Log Fields

Field	Type	Description
timestamp	ISO 8601	Event occurrence time
toolName	string	MCP tool identifier
parameters	object	Sanitized input parameters (PII removed)
resultStatus	enum	success, error, rate_limited
durationMs	number	Execution duration
errorType	string?	Error category (no stack traces)
cacheHit	boolean?	Whether result came from cache

---

🛡️ Data Protection and GDPR

Personal Data Inventory

Data Category	EP API Endpoint	GDPR Basis	Retention in Cache	Minimization Applied
MEP Names	/meps/{id}	Public role (Art. 6.1.e)	15 min TTL	Name, group only
MEP Contact	/meps/{id}	Legitimate interest	15 min TTL	Official EP address only
MEP Votes	/votes	Public interest	15 min TTL	Vote record, no commentary
MEP Attendance	/plenary-sessions	Public interest	15 min TTL	Session data only
MEP Declarations	/meps/{id}/declarations	Public role	15 min TTL	Official declarations only

GDPR Principles Implementation

Principle	Implementation
Lawfulness	Processing public parliamentary records per Art. 6.1.e (public interest)
Purpose Limitation	Data used solely for parliamentary intelligence queries
Data Minimization	Field selection queries — only request needed attributes
Accuracy	Data sourced directly from official EP API
Storage Limitation	LRU cache with 15-min TTL; no persistent storage
Integrity and Confidentiality	HTTPS transport, no local file system writes
Accountability	Audit logging of all data access requests

---

🌐 Network Security and Perimeter Protection

Outbound Connections

Destination	Protocol	Port	TLS	Purpose
data.europarl.europa.eu	HTTPS	443	TLS 1.2+	EP Open Data Portal API v2
EP Vocabulary endpoints	HTTPS	443	TLS 1.2+	AT4EU taxonomy lookups

Security Headers (Outbound Requests)

// Applied to all EP API requests
headers: {
  'Accept': 'application/json',
  'User-Agent': 'European-Parliament-MCP-Server/1.1',
  'Accept-Encoding': 'gzip, deflate, br'
}
Copy

No Inbound Network Exposure

• Server operates exclusively via stdio (no listening sockets)
• No HTTP server, no WebSocket server in current v1.1
• No ports bound, no firewall rules required

---

📊 Audit and Monitoring

Audit Log Schema

interface AuditLogEntry {
  timestamp: string;        // ISO 8601
  toolName: string;         // e.g., "get_mep_details"
  parameters: Record<string, unknown>;  // PII-stripped
  resultStatus: 'success' | 'error' | 'rate_limited';
  durationMs: number;
  errorType?: string;       // Error category (no stack traces)
}
Copy

Metrics Collected

Metric	Type	Purpose
tool.invocations.total	Counter	Usage tracking per tool
tool.invocations.errors	Counter	Error rate monitoring
cache.hits	Counter	Cache efficiency
cache.misses	Counter	Cache efficiency
ratelimit.tokens.used	Gauge	Rate limit consumption
api.request.duration_ms	Histogram	EP API latency
api.request.errors	Counter	EP API error rates

Health Checks

The HealthService singleton monitors:

• EP API reachability (periodic ping)
• Cache memory utilization
• Rate limiter token availability
• Error rate thresholds

---

🔌 VPC Endpoints and Private Access

Current Architecture (stdio-based)

The EP MCP Server operates as a local process using stdio transport, which means:

• No VPC deployment — the server runs on the local machine as a child process of the MCP client
• No cloud networking — no VPC, subnets, or security groups required
• Direct internet access — outbound HTTPS to EP API via the host's network stack
• Process-level isolation — OS process boundaries provide access control

Network Access Pattern

flowchart LR
    subgraph LocalMachine["Local Machine"]
        MCPClient["MCP Client\n(Claude/Cursor)"]
        MCPServer["EP MCP Server\n(child process)"]
    end

    subgraph Internet["Public Internet"]
        EPAPI["EP Open Data Portal\n(data.europarl.europa.eu)"]
    end

    MCPClient -->|"stdio pipe"| MCPServer
    MCPServer -->|"HTTPS/TLS 1.2+"| EPAPI
Copy

Future Cloud Deployment Considerations

When deployed as a hosted service (v2.0+), VPC architecture will include:

• Private subnets for MCP server instances
• NAT Gateway for outbound EP API access
• VPC endpoints for AWS services (CloudWatch, KMS)
• Security groups restricting inbound to MCP protocol only

See FUTURE_SECURITY_ARCHITECTURE.md for planned VPC architecture.

---

🏗️ High Availability and Resilience

Current Resilience Model

Aspect	Implementation	Recovery
Process crash	MCP client auto-restarts server process	Instant restart, cold cache
EP API unavailable	Graceful error responses to MCP client	Cached data served if available
Rate limit exceeded	Token bucket rejects requests with clear error	Auto-recovery after window reset
Memory exhaustion	LRU cache eviction (max 500 entries)	Automatic eviction of oldest entries
Network timeout	Configurable timeout (default 30s) per request	Retry with exponential backoff

Fault Tolerance Architecture

flowchart TD
    subgraph Resilience["Resilience Controls"]
        RC["Rate Limiter\n(100 req/min)"]
        CA["LRU Cache\n(500 entries, 15-min TTL)"]
        TO["Request Timeout\n(30s default)"]
        EH["Error Handler\n(graceful degradation)"]
    end

    subgraph Recovery["Recovery Mechanisms"]
        AR["Auto-restart\n(MCP client managed)"]
        CE["Cache eviction\n(LRU policy)"]
        TR["Token refill\n(1-minute window)"]
    end

    RC --> TR
    CA --> CE
    TO --> EH
    EH --> AR
Copy

Data Durability

• No persistent state — all state is in-memory (cache, metrics, rate limiter tokens)
• Stateless design — server can be restarted at any time without data loss
• Cache warm-up — first requests after restart may be slower (cold cache)
• npm package integrity — SLSA Level 3 provenance ensures package authenticity

---

⚡ Threat Detection and Investigation

Detection Capabilities

Detection Method	Implementation	Threats Detected
Rate limit monitoring	Token bucket algorithm logs rejection events	API abuse, DoS attempts
Error rate tracking	MetricsService tracks per-tool error rates	Injection attempts, API anomalies
Input validation logging	Zod validation failures logged with sanitized input	Malformed input, fuzzing attempts
Health check alerts	HealthService monitors EP API reachability	Network issues, EP API outages
Dependency scanning	Dependabot + npm audit in CI/CD	Supply chain vulnerabilities
Static analysis	CodeQL + ESLint in GitHub Actions	Code-level security issues

Investigation Workflow

flowchart TD
    Alert["Security Alert\n(error spike, validation failure)"] --> Triage["Triage\n(review audit logs)"]
    Triage --> Analyze["Analyze\n(correlate metrics + logs)"]
    Analyze --> Classify{"Classify"}
    Classify -->|"False Positive"| Document["Document & Close"]
    Classify -->|"True Positive"| Respond["Incident Response"]
    Respond --> Contain["Contain\n(rate limit, block input)"]
    Contain --> Remediate["Remediate\n(patch, update schema)"]
    Remediate --> Verify["Verify Fix"]
    Verify --> Document
Copy

---

🔍 Vulnerability Management

Vulnerability Scanning Pipeline

Scanner	Scope	Frequency	Integration
Dependabot	npm dependencies	Continuous	GitHub automatic PRs
npm audit	Direct + transitive deps	Every CI run	Build gate
CodeQL	Source code (TypeScript)	Every PR + scheduled	GitHub code scanning
ESLint security rules	Code patterns	Every commit	Pre-commit + CI
License compliance	Dependency licenses	Every CI run	test:licenses script
SLSA provenance	Package supply chain	Every release	Sigstore attestation

Remediation SLAs

Severity	CVSS Score	Remediation Timeline	Escalation
Critical	9.0–10.0	24 hours	Immediate patch release
High	7.0–8.9	7 days	Next patch release
Medium	4.0–6.9	30 days	Next minor release
Low	0.1–3.9	90 days	Scheduled maintenance

Dependency Update Strategy

• Automated PRs via Dependabot for all dependency updates
• Lockfile pinning — exact versions in package-lock.json
• Minimal dependencies — only 4 runtime dependencies (SDK, LRU cache, undici, zod)
• Provenance verification — SLSA Level 3 for published npm package

---

⚙️ Configuration and Compliance Management

Configuration Management

Configuration	Source	Validation	Default
Rate limit	EP_RATE_LIMIT env var	Numeric > 0	100 req/min
Cache size	Hardcoded	N/A	500 entries
Cache TTL	EP_CACHE_TTL env var	Numeric (ms)	900,000 ms (15 min)
EP API base URL	EP_API_URL env var	URL format	https://data.europarl.europa.eu/api/v2/
Request timeout	EP_REQUEST_TIMEOUT_MS env var	Numeric (ms)	10,000 ms

Infrastructure as Code

• TypeScript strict mode — all configuration types are compile-time checked
• Zod runtime validation — environment variables validated at startup
• No secrets in code — all sensitive values via environment variables
• Reproducible builds — npm ci with lockfile for deterministic installs

Compliance Drift Detection

Check	Tool	Frequency	Action on Drift
Dependency versions	Dependabot	Continuous	Auto-PR
Code quality	ESLint + TypeScript	Every commit	Build failure
Security findings	CodeQL	Every PR	PR blocked
License compliance	license-compliance	Every CI	Build failure
Unused code	Knip	Every CI	Build warning
Package integrity	SLSA provenance	Every release	Release blocked

---

📈 Security Monitoring and Analytics

Metrics Dashboard

Metric Category	Metrics	Collection Method
Tool usage	Invocations per tool, error rate per tool	MetricsService counters
API performance	Request duration, response status codes	MetricsService histograms
Rate limiting	Tokens used, rejections, peak usage	Token bucket state
Cache efficiency	Hit rate, miss rate, eviction count	LRU cache stats
Error analysis	Error types, error frequency, error trends	AuditLogger + MetricsService

Security Alerting Thresholds

Alert	Threshold	Action
Error rate spike	> 10% of requests in 5-min window	Log warning, investigate
Rate limit saturation	> 90% token usage	Log warning, potential abuse
EP API connectivity loss	3 consecutive failures	Health check degraded
Validation failure spike	> 5 failures in 1 minute	Potential injection attempt

Analytics for Threat Intelligence

• Tool usage patterns — detect anomalous tool call sequences
• Parameter analysis — identify suspicious parameter patterns (logged after PII stripping)
• Error correlation — correlate error spikes with external events
• Rate limit patterns — identify API abuse patterns

---

🤖 Automated Security Operations

CI/CD Security Automation

flowchart LR
    subgraph CI["GitHub Actions CI/CD"]
        Lint["ESLint\n+ TypeScript"]
        Test["Vitest\n(1130+ unit + 71 E2E tests)"]
        Scan["CodeQL\n+ npm audit"]
        License["License\nCompliance"]
        Build["TypeScript\nBuild"]
        Publish["npm Publish\n+ SLSA Provenance"]
    end

    Commit["Git Commit"] --> Lint --> Test --> Scan --> License --> Build --> Publish
Copy

Automated Security Controls

Automation	Trigger	Action	Outcome
Dependabot PRs	New vulnerability	Auto-create update PR	Dependency patched
CodeQL scanning	Every PR/push	Static analysis	Vulnerabilities flagged
npm audit	Every CI run	Dependency audit	Build gate enforced
License check	Every CI run	License validation	Non-compliant deps blocked
Knip	Every CI run	Unused code detection	Dead code flagged
SLSA provenance	npm publish	Provenance attestation	Supply chain verified
Branch protection	PR merge	Required reviews + checks	Quality gate enforced

Self-Healing Capabilities

• Automatic cache eviction — LRU policy prevents memory exhaustion
• Rate limit recovery — token bucket auto-refills after window expiry
• Graceful degradation — tools return structured errors when EP API is unavailable
• Process restart — MCP client automatically restarts crashed server processes

---

🛡️ Application Security Controls

Input Validation Architecture

flowchart TD
    Input["Raw MCP Input\n(unknown type)"] --> ZodParse["Zod Schema.parse()"]
    ZodParse -->|"Valid"| TypeSafe["Type-Safe Parameters"]
    ZodParse -->|"Invalid"| ZodError["ZodError\n(structured rejection)"]
    TypeSafe --> BrandedTypes["Branded Type Enforcement\n(MEPId, ProcedureId, etc.)"]
    BrandedTypes --> Handler["Tool Handler\n(type-safe execution)"]
    ZodError --> ErrorResponse["MCP Error Response\n(no internal details)"]
Copy

Validation Controls per Layer

Layer	Control	Implementation
Input parsing	Zod schema validation	Every tool has a dedicated schema
Type enforcement	Branded types via Zod	MEPId, ProcedureId, SessionId prevent type confusion
Cross-field validation	.refine() constraints	Date range ordering, mutual exclusivity, conditional requirements
String sanitization	Max length limits, pattern matching	Zod .max(), .regex() constraints
Numeric bounds	Range validation	.min(), .max(), .int() constraints
Enum restriction	Allowed value sets	.enum() for country codes, group names
Output encoding	JSON serialization	JSON.stringify() prevents injection in responses
Data quality	OSINT output validation	dataQualityWarnings, confidenceLevel, DataAvailability fields (SC-013)

Error Handling Security

All tool errors are reported via the ToolError class which carries toolName, operation, isRetryable, and optional cause — ensuring structured error reporting without leaking internal implementation details. Success responses use buildToolResponse() for consistent JSON formatting.

Error Type	Response to Client	Logged Internally
Zod validation error	Structured field errors	Full error details
EP API error (4xx)	Generic "API error" message	Status code, URL, response body
EP API error (5xx)	Generic "service unavailable"	Full error details
Network timeout	"Request timeout"	URL, timeout duration
Rate limit exceeded	"Rate limit exceeded"	Token state, request details
Unexpected error	"Internal error"	Full stack trace (internal only)

---

🏆 Defense-in-Depth Strategy

Security Layer Architecture

flowchart TD
    subgraph Layer1["Layer 1: Process Isolation"]
        OS["OS Process Boundaries"]
        STDIO["stdio Transport\n(no network exposure)"]
    end

    subgraph Layer2["Layer 2: Input Validation"]
        ZOD["Zod Schema Validation\n(62 tool schemas)"]
        BT["Branded Types\n(type-safe identifiers)"]
    end

    subgraph Layer3["Layer 3: Rate Limiting & Caching"]
        RL["Token Bucket Rate Limiter"]
        LRU["LRU Cache\n(bounded memory)"]
    end

    subgraph Layer4["Layer 4: Transport Security"]
        TLS["HTTPS/TLS 1.2+\n(to EP API)"]
        CERT["Certificate Validation\n(Node.js defaults)"]
    end

    subgraph Layer5["Layer 5: Audit & Monitoring"]
        AUDIT["Audit Logger\n(PII-stripped)"]
        METRICS["MetricsService\n(performance + errors)"]
        HEALTH["HealthService\n(availability)"]
    end

    subgraph Layer6["Layer 6: Supply Chain Security"]
        SLSA["SLSA Level 3 Provenance"]
        DEPS["Minimal Dependencies (4)"]
        LOCK["Lockfile Pinning"]
        SCAN["Dependabot + CodeQL"]
    end

    Layer1 --> Layer2 --> Layer3 --> Layer4 --> Layer5 --> Layer6
Copy

Defense-in-Depth Summary

Layer	Controls	Threats Mitigated
Process Isolation	stdio transport, no network listener	Remote access, network attacks
Input Validation	Zod schemas, branded types, strict TypeScript	Injection, type confusion, malformed input
Rate Limiting	Token bucket (100/min), cache bounds (500)	DoS, API abuse, memory exhaustion
Transport Security	HTTPS/TLS 1.2+, certificate validation	MITM, data interception
Audit & Monitoring	Structured logging, metrics, health checks	Repudiation, undetected abuse
Supply Chain	SLSA L3, Dependabot, lockfile, minimal deps	Dependency hijacking, package tampering

---

🧪 Security Testing Requirements

Coverage Requirements

Component	Minimum Coverage	Focus Areas
Zod validators	95%	Edge cases, injection attempts
Rate limiter	90%	Boundary conditions, token exhaustion
Audit logger	90%	PII stripping, log format
EP API clients	80%	Error handling, timeout behavior
Tool handlers	80%	Happy path + error paths

Security Test Categories

1. Input Validation Tests

   • Oversized strings (> 10,000 chars)
   • Special characters in identifiers
   • Prototype pollution attempts: {"__proto__": {...}}
   • Type confusion: passing objects where strings expected
   • Boundary values: negative IDs, zero values, MAX_SAFE_INTEGER

2. Rate Limiting Tests

   • Burst requests (> 100 in 60s window)
   • Token recovery after window reset
   • Concurrent request handling

3. Data Privacy Tests

   • Verify PII fields are stripped from audit logs
   • Verify data minimization (no extra fields returned)
   • Verify 15-min cache TTL enforcement

4. Error Handling Tests

   • EP API 429 (rate limited) — graceful handling
   • EP API 500 — error message sanitization
   • Network timeout — no credential leakage
   • ZodError — structured error response

---

📋 Compliance Framework Mapping

Control	Standard	Clause	Implementation
Information Security Policies	ISO 27001	A.5.1	SECURITY.md, SECURITY_ARCHITECTURE.md, THREAT_MODEL.md
Asset Management	ISO 27001	A.8.1	62 tools + 9 resources inventoried
Access Control	ISO 27001	A.9.1	stdio isolation, no network exposure
Cryptography	ISO 27001	A.10.1	TLS 1.2+ for all EP API calls
Secure Development	ISO 27001	A.14.2	TypeScript strict, Zod validation, ESLint
Vulnerability Management	ISO 27001	A.12.6	Dependabot, npm audit, CodeQL
Audit Logging	ISO 27001	A.12.4	AuditLogger, all invocations logged
Change Management	ISO 27001	A.12.1	Git-based change tracking, PR reviews
Privacy by Design	GDPR	Art. 25	Data minimization, purpose limitation
Data Protection	GDPR	Art. 32	TLS transport, no persistent PII storage
Identify: Assets	NIST CSF 2.0	ID.AM	Full tool and component inventory
Protect: Data Security	NIST CSF 2.0	PR.DS	TLS, cache TTL, data minimization
Detect: Anomalies	NIST CSF 2.0	DE.AE	MetricsService, error rate monitoring
Respond: Planning	NIST CSF 2.0	RS.RP	Incident response via GitHub Security Advisories
Recover: Planning	NIST CSF 2.0	RC.RP	Stateless design enables instant recovery
Software Inventory	CIS Controls v8.1	2.1	package.json with locked versions, SBOM
Secure Configuration	CIS Controls v8.1	4.1	TypeScript strict, no dangerous defaults
Audit Log Management	CIS Controls v8.1	8.2	AuditLogger singleton
Application Security	CIS Controls v8.1	16.1	Zod validation, branded types, CodeQL
Penetration Testing	CIS Controls v8.1	18.1	Security test categories in CI

---

See FUTURE_SECURITY_ARCHITECTURE.md for the planned security evolution including OAuth 2.0, RBAC, and zero-trust architecture.