SECURITY_ARCHITECTURE.md

April 28, 2026 · View on GitHub

🔒 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

Security Documentation Map
Executive Summary
4-Layer Security Architecture
Security Controls Inventory
Threat Mitigation Mapping (STRIDE)
Authentication and Authorization
Session and Action Tracking
Data Integrity and Auditing
Data Protection and GDPR
Network Security and Perimeter Protection
VPC Endpoints and Private Access
High Availability and Resilience
Threat Detection and Investigation
Vulnerability Management
Configuration and Compliance Management
Security Monitoring and Analytics
Automated Security Operations
Application Security Controls
Defense-in-Depth Strategy
Security Testing Requirements
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:

Input validation — prevent malformed or malicious MCP tool arguments
API abuse prevention — protect EP Open Data Portal from overuse
Data privacy — GDPR-compliant handling of MEP personal data
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

🔐 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

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

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)"]

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

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

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'
}

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)
}

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

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

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

🔍 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

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)"]

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

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

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
Rate Limiting Tests
- Burst requests (> 100 in 60s window)
- Token recovery after window reset
- Concurrent request handling
Data Privacy Tests
- Verify PII fields are stripped from audit logs
- Verify data minimization (no extra fields returned)
- Verify 15-min cache TTL enforcement
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.