# Enterprise Compliance Specification
**Version**: 1.0.0
**Date**: 2025-12-16
**Standards**: GDPR, SOC2 Type II, CSSF (Luxembourg)
**Status**: Draft
---
## Table of Contents
1. [Overview](#overview)
2. [Phase 1: Core Compliance Infrastructure](#phase-1-core-compliance-infrastructure)
3. [Phase 2: Data Subject Rights](#phase-2-data-subject-rights-gdpr)
4. [Phase 3: Security Monitoring & Incident Response](#phase-3-security-monitoring--incident-response)
5. [Phase 4: Compliance Reporting & Documentation](#phase-4-compliance-reporting--documentation)
6. [Configuration Reference](#configuration-reference)
7. [File Structure](#file-structure)
---
## Overview
### Current State
The NotebookLM MCP Server already implements strong security foundations:
| Existing Feature | Implementation |
|-----------------|----------------|
| Audit Logging | Hash-chained JSONL with tamper detection |
| Encryption at Rest | ML-KEM-768 + ChaCha20-Poly1305 (post-quantum) |
| Encryption in Transit | TLS with certificate pinning |
| PII Protection | Auto-sanitization in all logs |
| Access Control | Token-based auth with rate limiting |
| Session Security | Hard timeout (8h) + inactivity (30m) |
| Secrets Detection | 50+ patterns, auto-redaction |
| Memory Security | Secure wiping, auto-expiry credentials |
| Data Retention | 30-day audit log rotation |
### Compliance Gaps
| Gap | GDPR | SOC2 | CSSF | Priority |
|-----|------|------|------|----------|
| Consent Management | Required | - | Required | P1 |
| Data Subject Rights (DSAR) | Required | - | Required | P1 |
| Data Export/Portability | Required | - | Required | P1 |
| Right to Erasure | Required | - | Required | P1 |
| Data Classification | - | Required | Required | P1 |
| SIEM Integration | - | Required | Required | P2 |
| Breach Detection | Required | Required | Required | P2 |
| Incident Response | - | Required | Required | P2 |
| Compliance Reporting | - | Required | Required | P3 |
| Change Management | - | Required | Required | P3 |
---
## Phase 1: Core Compliance Infrastructure
### 1.1 Compliance Logger
**File**: `src/utils/compliance-logger.ts`
**Purpose**: Structured logging specifically for compliance events, separate from operational audit logs.
**Event Categories**:
```typescript
type ComplianceEventCategory =
| "consent" // Consent granted/revoked
| "data_access" // Data access requests
| "data_export" // Data portability requests
| "data_deletion" // Erasure requests
| "data_processing" // Processing activities
| "security_incident" // Security events
| "policy_change" // Configuration changes
| "access_control" // Auth events
| "retention" // Data retention events
| "breach"; // Breach notifications
```
**Event Structure**:
```typescript
interface ComplianceEvent {
// Required fields
id: string; // UUID v4
timestamp: string; // ISO 8601
category: ComplianceEventCategory;
event_type: string; // Specific event (e.g., "consent_granted")
// Actor information
actor: {
type: "user" | "system" | "admin";
id?: string; // User/session ID if applicable
ip?: string; // Masked IP (last octet zeroed)
};
// Event details
resource?: {
type: string; // e.g., "notebook", "session", "audit_log"
id?: string;
};
// Compliance metadata
legal_basis?: string; // GDPR legal basis
data_categories?: string[]; // Types of data involved
retention_days?: number; // How long to retain this event
// Outcome
outcome: "success" | "failure" | "pending";
failure_reason?: string;
// Integrity
hash: string;
previous_hash: string;
}
```
**Storage**:
- Location: `<data_dir>/compliance/events-YYYY-MM.jsonl`
- Retention: Configurable, default 7 years (CSSF requirement)
- Format: JSONL with hash chain
- Encryption: Post-quantum encrypted
**Configuration**:
```bash
NLMCP_COMPLIANCE_ENABLED=true
NLMCP_COMPLIANCE_DIR=/path/to/compliance
NLMCP_COMPLIANCE_RETENTION_YEARS=7
NLMCP_COMPLIANCE_ENCRYPTION=true
```
---
### 1.2 Data Classification System
**File**: `src/utils/data-classification.ts`
**Purpose**: Tag all data by sensitivity level for appropriate handling.
**Classification Levels**:
```typescript
enum DataClassification {
PUBLIC = "public", // No restrictions
INTERNAL = "internal", // Internal use only
CONFIDENTIAL = "confidential", // Restricted access
RESTRICTED = "restricted", // Highly sensitive (PII, credentials)
REGULATED = "regulated" // Subject to regulatory requirements
}
interface ClassifiedData {
classification: DataClassification;
data_categories: DataCategory[];
retention_policy: string;
encryption_required: boolean;
audit_required: boolean;
exportable: boolean;
erasable: boolean;
}
type DataCategory =
| "personal_data" // GDPR personal data
| "sensitive_data" // GDPR special categories
| "credentials" // Auth tokens, passwords
| "session_data" // Browser session state
| "usage_data" // Analytics, telemetry
| "configuration" // Settings, preferences
| "audit_logs" // Compliance logs
| "notebook_metadata"; // Notebook URLs, descriptions
```
**Data Inventory**:
| Data Type | Classification | Categories | Retention | Encrypted |
|-----------|---------------|------------|-----------|-----------|
| Auth tokens | RESTRICTED | credentials | Session | Yes |
| Browser cookies | RESTRICTED | session_data, personal_data | 24h | Yes |
| Notebook library | CONFIDENTIAL | notebook_metadata | Indefinite | Yes |
| Audit logs | REGULATED | audit_logs | 7 years | Yes |
| Compliance events | REGULATED | audit_logs | 7 years | Yes |
| User settings | INTERNAL | configuration | Indefinite | No |
| Session data | CONFIDENTIAL | session_data | 8h max | Yes |
| PQ encryption keys | RESTRICTED | credentials | Indefinite | Yes |
---
### 1.3 Consent Manager
**File**: `src/compliance/consent-manager.ts`
**Purpose**: Track and manage user consent for data processing activities.
**Consent Types**:
```typescript
interface ConsentRecord {
id: string; // UUID
version: string; // Consent version (e.g., "1.0.0")
granted_at: string; // ISO 8601
expires_at?: string; // Optional expiry
// What was consented to
purposes: ConsentPurpose[];
data_categories: DataCategory[];
// Legal basis (GDPR Article 6)
legal_basis: LegalBasis;
// Consent metadata
method: "explicit" | "implicit" | "contractual";
evidence?: string; // How consent was obtained
// Revocation
revoked?: boolean;
revoked_at?: string;
revocation_reason?: string;
}
type ConsentPurpose =
| "service_provision" // Core service functionality
| "session_management" // Browser session handling
| "security_logging" // Security audit logging
| "error_diagnostics" // Error logging for debugging
| "usage_analytics"; // Optional usage tracking
type LegalBasis =
| "consent" // User explicitly consented
| "contract" // Necessary for contract performance
| "legal_obligation" // Required by law
| "vital_interests" // Protect vital interests
| "public_interest" // Public interest task
| "legitimate_interest"; // Legitimate business interest
```
**Default Legal Bases**:
| Processing Activity | Legal Basis | Requires Explicit Consent |
|--------------------|-------------|---------------------------|
| Browser session for NotebookLM access | Contract | No |
| Security audit logging | Legitimate Interest | No |
| Credential encryption | Legal Obligation | No |
| Error logging | Legitimate Interest | No |
| Compliance logging | Legal Obligation | No |
**Storage**:
- Location: `<config_dir>/consent.json.pqenc`
- Encrypted: Yes (post-quantum)
- Backed up: Yes (with compliance events)
**API**:
```typescript
class ConsentManager {
// Record new consent
async grantConsent(purposes: ConsentPurpose[], legalBasis: LegalBasis): Promise<ConsentRecord>;
// Revoke consent
async revokeConsent(consentId: string, reason?: string): Promise<void>;
// Check if consent exists for purpose
hasConsent(purpose: ConsentPurpose): boolean;
// Get all active consents
getActiveConsents(): ConsentRecord[];
// Get consent history (for DSAR)
getConsentHistory(): ConsentRecord[];
// Check if first run (needs consent prompt)
isFirstRun(): boolean;
// Export consent records (for DSAR)
exportConsents(): string; // JSON
}
```
---
### 1.4 Privacy Notice Display
**File**: `src/compliance/privacy-notice.ts`
**Purpose**: Display privacy notice on first run and track acceptance.
**Notice Content** (stored in `src/compliance/privacy-notice-text.ts`):
```typescript
interface PrivacyNotice {
version: string;
effective_date: string;
sections: {
data_controller: string;
data_collected: string[];
purposes: string[];
legal_basis: string[];
retention: string;
rights: string[];
contact: string;
};
// Short summary for CLI display
summary: string;
}
```
**Display Behavior**:
1. **First Run**: Display full privacy notice, require acknowledgment
2. **Notice Updated**: Display changes, require re-acknowledgment
3. **On Demand**: Available via `get_privacy_notice` MCP tool
**CLI Display Example**:
```
╔══════════════════════════════════════════════════════════════════╗
║ PRIVACY NOTICE v1.0.0 ║
╠══════════════════════════════════════════════════════════════════╣
║ ║
║ This tool processes the following data locally on your device: ║
║ ║
║ • Browser session data (cookies, local storage) ║
║ • NotebookLM URLs and metadata ║
║ • Query history (for session context) ║
║ • Security audit logs ║
║ ║
║ All data is: ║
║ ✓ Stored locally only (no cloud sync) ║
║ ✓ Encrypted with post-quantum cryptography ║
║ ✓ Subject to automatic retention policies ║
║ ║
║ Your rights: Access, Export, Erasure, Portability ║
║ ║
║ Full policy: https://github.com/Pantheon-Security/... ║
║ ║
╠══════════════════════════════════════════════════════════════════╣
║ By continuing, you acknowledge this privacy notice. ║
║ ║
║ [Press Enter to continue, or Ctrl+C to exit] ║
╚══════════════════════════════════════════════════════════════════╝
```
---
### 1.5 Enhanced Audit Events
**File**: Update `src/utils/audit-logger.ts`
**New Event Types**:
```typescript
// Add to existing AuditEventType
type AuditEventType =
| "tool" // Existing
| "auth" // Existing
| "session" // Existing
| "security" // Existing
| "system" // Existing
| "compliance" // NEW: Compliance events
| "data_access" // NEW: Data access events
| "configuration" // NEW: Config changes
| "retention"; // NEW: Data retention events
// New compliance-specific logging methods
interface AuditLogger {
// Existing methods...
// NEW: Compliance event logging
logComplianceEvent(
event: string,
category: ComplianceEventCategory,
details: Record<string, unknown>
): Promise<void>;
// NEW: Data access logging (for DSAR)
logDataAccess(
action: "view" | "export" | "delete",
dataType: string,
details: Record<string, unknown>
): Promise<void>;
// NEW: Configuration change logging
logConfigChange(
setting: string,
oldValue: unknown,
newValue: unknown,
changedBy: string
): Promise<void>;
// NEW: Retention event logging
logRetentionEvent(
action: "cleanup" | "archive" | "delete",
dataType: string,
count: number,
details: Record<string, unknown>
): Promise<void>;
}
```
---
## Phase 2: Data Subject Rights (GDPR)
### 2.1 Data Export Tool
**File**: `src/compliance/data-export.ts`
**Purpose**: Export all user data in machine-readable format (GDPR Article 20).
**Export Format**:
```typescript
interface DataExport {
export_metadata: {
version: string;
exported_at: string;
format: "json";
encryption: "none" | "password";
checksum: string;
};
data: {
// User identity
consent_records: ConsentRecord[];
// Notebooks
notebook_library: NotebookEntry[];
// Settings
user_settings: Settings;
// Session history (if retained)
session_history?: SessionSummary[];
// Audit logs (user's own activity)
activity_log: AuditEvent[];
// Compliance events
compliance_events: ComplianceEvent[];
};
data_inventory: {
category: string;
count: number;
date_range: { from: string; to: string };
}[];
}
```
**Export Options**:
```typescript
interface ExportOptions {
// What to include
include_notebooks: boolean; // Default: true
include_settings: boolean; // Default: true
include_sessions: boolean; // Default: true
include_audit_logs: boolean; // Default: true
include_compliance_events: boolean; // Default: true
// Date range
from_date?: string;
to_date?: string;
// Security
encrypt_export: boolean; // Default: false
export_password?: string;
// Format
format: "json" | "json_pretty";
// Delivery
output_path?: string; // Default: stdout
}
```
**MCP Tool**:
```typescript
// New MCP tool: export_user_data
{
name: "export_user_data",
description: "Export all user data (GDPR Article 20 - Right to Data Portability)",
inputSchema: {
type: "object",
properties: {
include_audit_logs: { type: "boolean", default: true },
from_date: { type: "string", format: "date" },
to_date: { type: "string", format: "date" },
format: { type: "string", enum: ["json", "json_pretty"], default: "json_pretty" }
}
}
}
```
---
### 2.2 Right to Erasure
**File**: `src/compliance/data-erasure.ts`
**Purpose**: Complete deletion of user data (GDPR Article 17).
**Erasure Scope**:
```typescript
interface ErasureRequest {
request_id: string;
requested_at: string;
// What to delete
scope: ErasureScope;
// Verification
confirmed: boolean;
confirmation_method: "explicit" | "timeout";
// Execution
executed_at?: string;
items_deleted: ErasureResult[];
// Retention (we must keep the erasure record itself)
erasure_record_retention_days: number; // Default: 2555 (7 years)
}
interface ErasureScope {
// Data types to delete
notebooks: boolean; // Notebook library
settings: boolean; // User settings
browser_data: boolean; // Browser profiles, cookies
audit_logs: boolean; // User activity logs
compliance_events: boolean; // Keep erasure record only
encryption_keys: boolean; // PQ keys (careful!)
// Or delete everything
complete_erasure: boolean;
}
interface ErasureResult {
data_type: string;
path: string;
items_deleted: number;
size_bytes: number;
method: "overwrite" | "delete" | "crypto_shred";
verified: boolean;
}
```
**Secure Deletion Methods**:
1. **Overwrite**: 3-pass overwrite with random data
2. **Delete**: Standard file deletion
3. **Crypto Shred**: Delete encryption keys (data unrecoverable)
**Retention Exceptions** (data that cannot be deleted):
- Erasure request record itself (legal requirement)
- Security incident logs (if applicable)
- Data required for legal proceedings
**MCP Tool**:
```typescript
// New MCP tool: request_data_erasure
{
name: "request_data_erasure",
description: "Request deletion of all user data (GDPR Article 17 - Right to Erasure)",
inputSchema: {
type: "object",
properties: {
scope: {
type: "string",
enum: ["complete", "notebooks", "sessions", "audit_logs"],
default: "complete"
},
confirm: {
type: "boolean",
description: "Explicit confirmation required"
}
},
required: ["confirm"]
}
}
```
---
### 2.3 Data Access Request Handler
**File**: `src/compliance/dsar-handler.ts`
**Purpose**: Handle Data Subject Access Requests (GDPR Article 15).
**DSAR Response**:
```typescript
interface DSARResponse {
request_id: string;
submitted_at: string;
completed_at: string;
// Identity confirmation
subject_verified: boolean;
// Data provided
personal_data: {
category: string;
data: unknown;
source: string;
retention_period: string;
}[];
// Processing information
processing_purposes: string[];
legal_bases: string[];
data_recipients: string[]; // Empty for local-only
// Rights information
available_rights: string[];
// Metadata
format: "json";
encrypted: boolean;
}
```
**MCP Tool**:
```typescript
// New MCP tool: submit_data_access_request
{
name: "submit_data_access_request",
description: "Submit a Data Subject Access Request (GDPR Article 15)",
inputSchema: {
type: "object",
properties: {
include_processing_info: { type: "boolean", default: true },
format: { type: "string", enum: ["json", "summary"], default: "summary" }
}
}
}
```
---
### 2.4 Data Inventory
**File**: `src/compliance/data-inventory.ts`
**Purpose**: Maintain inventory of all personal data stored.
**Inventory Structure**:
```typescript
interface DataInventoryEntry {
id: string;
// What
data_type: string;
description: string;
classification: DataClassification;
data_categories: DataCategory[];
// Where
storage_location: string;
encrypted: boolean;
// How long
retention_policy: string;
retention_days: number | "indefinite";
// Legal
legal_basis: LegalBasis;
processing_purposes: string[];
// Access
who_can_access: string[];
exportable: boolean;
erasable: boolean;
// Metadata
last_updated: string;
}
```
**Auto-Discovery**:
- Scan data directories on startup
- Register new data types automatically
- Track data lifecycle
---
### 2.5 Retention Policy Engine
**File**: `src/compliance/retention-engine.ts`
**Purpose**: Enforce data retention policies automatically.
**Policy Configuration**:
```typescript
interface RetentionPolicy {
id: string;
name: string;
// What it applies to
data_types: string[];
classifications?: DataClassification[];
// How long to keep
retention_days: number;
// What to do after expiry
action: "delete" | "archive" | "anonymize";
// When to run
schedule: "daily" | "weekly" | "monthly";
// Exceptions
exceptions?: {
condition: string;
extended_retention_days: number;
}[];
// Compliance
regulatory_requirement?: string; // e.g., "CSSF Circular 20/750"
}
```
**Default Policies**:
| Data Type | Retention | Action | Regulation |
|-----------|-----------|--------|------------|
| Audit logs | 7 years | Archive | CSSF |
| Compliance events | 7 years | Archive | CSSF |
| Session data | 24 hours | Delete | - |
| Browser cache | 7 days | Delete | - |
| Error logs | 30 days | Delete | - |
| Consent records | 7 years | Archive | GDPR |
| Erasure records | 7 years | Archive | GDPR |
---
## Phase 3: Security Monitoring & Incident Response
### 3.1 SIEM Integration
**File**: `src/compliance/siem-exporter.ts`
**Purpose**: Export logs to external Security Information and Event Management systems.
**Supported Formats**:
```typescript
type SIEMFormat =
| "json" // Raw JSON
| "cef" // Common Event Format (ArcSight)
| "leef" // Log Event Extended Format (IBM QRadar)
| "syslog" // RFC 5424 syslog
| "splunk_hec"; // Splunk HTTP Event Collector
interface SIEMConfig {
enabled: boolean;
format: SIEMFormat;
// Destination
endpoint?: string; // For HTTP-based (Splunk HEC)
syslog_host?: string; // For syslog
syslog_port?: number;
// Authentication
api_key?: string;
// Filtering
min_severity: "info" | "warning" | "error" | "critical";
event_types: string[]; // Which events to export
// Batching
batch_size: number; // Default: 100
flush_interval_ms: number; // Default: 5000
// Reliability
retry_attempts: number; // Default: 3
queue_max_size: number; // Default: 10000
}
```
**CEF Format Example**:
```
CEF:0|Pantheon Security|NotebookLM MCP|1.5.1|auth_failed|Authentication Failed|7|src=192.168.1.100 suser=unknown outcome=failure reason=invalid_token
```
**Configuration**:
```bash
NLMCP_SIEM_ENABLED=true
NLMCP_SIEM_FORMAT=cef
NLMCP_SIEM_ENDPOINT=https://siem.example.com/api/events
NLMCP_SIEM_API_KEY=xxx
NLMCP_SIEM_MIN_SEVERITY=warning
```
---
### 3.2 Breach Detection
**File**: `src/compliance/breach-detection.ts`
**Purpose**: Detect potential security breaches and policy violations.
**Detection Rules**:
```typescript
interface BreachRule {
id: string;
name: string;
description: string;
severity: "low" | "medium" | "high" | "critical";
// Detection
event_pattern: string; // Regex or event type
threshold?: number; // Count threshold
window_seconds?: number; // Time window
// Response
actions: BreachAction[];
// Regulatory
notification_required: boolean;
notification_deadline_hours?: number; // e.g., 72 for GDPR
}
type BreachAction =
| "log" // Log to compliance events
| "alert" // Send alert
| "block" // Block further access
| "notify_admin" // Email/webhook notification
| "create_incident"; // Create incident record
```
**Default Rules**:
| Rule | Trigger | Severity | Actions |
|------|---------|----------|---------|
| Brute Force | 10 failed auth in 5 min | High | block, alert, log |
| Secrets Leaked | Secrets detected in output | Critical | alert, log, create_incident |
| Cert Pinning Violation | TLS cert mismatch | Critical | block, alert, log |
| Unusual Access Pattern | Access outside normal hours | Medium | alert, log |
| Mass Data Export | Large export request | Medium | log, notify_admin |
| Encryption Failure | Encryption operation failed | High | alert, log |
---
### 3.3 Incident Response Log
**File**: `src/compliance/incident-manager.ts`
**Purpose**: Track and manage security incidents.
**Incident Structure**:
```typescript
interface SecurityIncident {
id: string;
// Classification
type: IncidentType;
severity: "low" | "medium" | "high" | "critical";
status: "open" | "investigating" | "contained" | "resolved" | "closed";
// Timeline
detected_at: string;
reported_at?: string;
contained_at?: string;
resolved_at?: string;
closed_at?: string;
// Details
title: string;
description: string;
affected_data: string[];
affected_systems: string[];
// Response
actions_taken: IncidentAction[];
root_cause?: string;
remediation?: string;
// Notification
notification_required: boolean;
notification_sent?: boolean;
notification_deadline?: string;
// Evidence
related_events: string[]; // Event IDs from audit log
}
type IncidentType =
| "unauthorized_access"
| "data_breach"
| "malware"
| "dos_attack"
| "policy_violation"
| "data_loss"
| "configuration_error"
| "other";
interface IncidentAction {
timestamp: string;
action: string;
performed_by: string;
notes?: string;
}
```
---
### 3.4 Alert System
**File**: `src/compliance/alert-manager.ts`
**Purpose**: Send alerts for security and compliance events.
**Alert Channels**:
```typescript
interface AlertConfig {
enabled: boolean;
channels: {
// Console (always available)
console: boolean;
// File-based alerts
file?: {
path: string;
format: "json" | "text";
};
// Webhook (Slack, Teams, etc.)
webhook?: {
url: string;
headers?: Record<string, string>;
template?: string;
};
// Email (via external service)
email?: {
smtp_host: string;
smtp_port: number;
from: string;
to: string[];
use_tls: boolean;
};
};
// Filtering
min_severity: "info" | "warning" | "error" | "critical";
event_types?: string[];
// Rate limiting
cooldown_seconds: number; // Don't repeat same alert within
max_alerts_per_hour: number;
}
```
**Configuration**:
```bash
NLMCP_ALERTS_ENABLED=true
NLMCP_ALERTS_WEBHOOK_URL=https://hooks.slack.com/xxx
NLMCP_ALERTS_MIN_SEVERITY=warning
NLMCP_ALERTS_COOLDOWN=300
```
---
### 3.5 Health Monitoring
**File**: `src/compliance/health-monitor.ts`
**Purpose**: Monitor system health and availability (SOC2 requirement).
**Health Metrics**:
```typescript
interface HealthMetrics {
timestamp: string;
// System health
status: "healthy" | "degraded" | "unhealthy";
uptime_seconds: number;
// Component status
components: {
name: string;
status: "up" | "down" | "degraded";
last_check: string;
response_time_ms?: number;
error?: string;
}[];
// Resource usage
resources: {
memory_used_mb: number;
memory_limit_mb: number;
disk_used_mb: number;
disk_available_mb: number;
};
// Security status
security: {
encryption_enabled: boolean;
auth_enabled: boolean;
cert_pinning_enabled: boolean;
last_security_scan?: string;
open_incidents: number;
};
// Compliance status
compliance: {
consent_valid: boolean;
retention_policies_active: number;
pending_erasure_requests: number;
last_compliance_check: string;
};
}
```
**MCP Tool Enhancement**:
```typescript
// Enhance existing get_health tool
{
name: "get_health",
description: "Get server health including compliance status",
// Add compliance metrics to response
}
```
---
## Phase 4: Compliance Reporting & Documentation
### 4.1 Compliance Dashboard
**File**: `src/compliance/dashboard.ts`
**Purpose**: Generate compliance status overview.
**Dashboard Output**:
```typescript
interface ComplianceDashboard {
generated_at: string;
// Overall status
overall_status: "compliant" | "non_compliant" | "needs_attention";
// By regulation
regulations: {
name: "GDPR" | "SOC2" | "CSSF";
status: "compliant" | "non_compliant" | "partial";
requirements_met: number;
requirements_total: number;
issues: ComplianceIssue[];
}[];
// Key metrics
metrics: {
active_consents: number;
pending_dsars: number;
pending_erasures: number;
open_incidents: number;
audit_log_integrity: "verified" | "issues_found";
encryption_status: "enabled" | "disabled" | "partial";
retention_compliance: number; // Percentage
};
// Recent events
recent_compliance_events: ComplianceEvent[];
// Upcoming deadlines
deadlines: {
type: string;
deadline: string;
days_remaining: number;
}[];
}
interface ComplianceIssue {
severity: "critical" | "high" | "medium" | "low";
regulation: string;
requirement: string;
description: string;
remediation: string;
}
```
**MCP Tool**:
```typescript
// New MCP tool: get_compliance_status
{
name: "get_compliance_status",
description: "Get compliance dashboard showing status across GDPR, SOC2, CSSF",
inputSchema: {
type: "object",
properties: {
regulations: {
type: "array",
items: { type: "string", enum: ["GDPR", "SOC2", "CSSF"] },
default: ["GDPR", "SOC2", "CSSF"]
},
include_events: { type: "boolean", default: true }
}
}
}
```
---
### 4.2 Audit Report Generator
**File**: `src/compliance/report-generator.ts`
**Purpose**: Generate compliance audit reports.
**Report Types**:
```typescript
type ReportType =
| "compliance_summary" // High-level compliance status
| "audit_trail" // Detailed audit log report
| "access_report" // Who accessed what
| "retention_report" // Data retention status
| "incident_report" // Security incident summary
| "dsar_report" // Data subject request summary
| "consent_report"; // Consent status report
interface ReportConfig {
type: ReportType;
// Time range
from_date: string;
to_date: string;
// Format
format: "json" | "html" | "pdf" | "csv";
// Filters
regulations?: string[];
severity_min?: string;
// Output
output_path?: string;
include_evidence?: boolean;
}
```
---
### 4.3 Policy Documentation
**File**: `src/compliance/policy-docs.ts`
**Purpose**: Machine-readable policy documentation.
**Policies**:
```typescript
interface PolicyDocument {
id: string;
type: PolicyType;
version: string;
effective_date: string;
// Content
title: string;
description: string;
full_text: string;
// Applicability
regulations: string[];
data_types: string[];
// Enforcement
enforced: boolean;
enforcement_method: "automatic" | "manual" | "audit";
// Review
last_reviewed: string;
next_review: string;
approved_by: string;
}
type PolicyType =
| "privacy_policy"
| "data_retention"
| "access_control"
| "encryption"
| "incident_response"
| "acceptable_use";
```
---
### 4.4 Change Log
**File**: `src/compliance/change-log.ts`
**Purpose**: Track all configuration changes (SOC2 requirement).
**Change Record**:
```typescript
interface ChangeRecord {
id: string;
timestamp: string;
// What changed
component: string;
setting: string;
old_value: unknown;
new_value: unknown;
// Who/how
changed_by: "user" | "system" | "admin";
method: "cli" | "env" | "api" | "config_file";
// Approval (for sensitive changes)
requires_approval: boolean;
approved_by?: string;
approved_at?: string;
// Impact
impact: "low" | "medium" | "high";
affected_compliance: string[];
}
```
---
### 4.5 Evidence Collection
**File**: `src/compliance/evidence-collector.ts`
**Purpose**: Automated collection of compliance evidence for audits.
**Evidence Types**:
```typescript
interface EvidencePackage {
id: string;
generated_at: string;
// What it's for
audit_type: "SOC2" | "GDPR" | "CSSF" | "internal";
period: { from: string; to: string };
// Contents
items: EvidenceItem[];
// Integrity
checksum: string;
signed_by?: string;
}
interface EvidenceItem {
id: string;
type: EvidenceType;
description: string;
// Content
content: string | object;
format: "json" | "text" | "screenshot" | "log";
// Metadata
collected_at: string;
source: string;
// Compliance mapping
controls: string[]; // e.g., ["SOC2-CC6.1", "GDPR-Art32"]
}
type EvidenceType =
| "policy_document"
| "configuration"
| "audit_log_sample"
| "access_review"
| "encryption_status"
| "retention_proof"
| "consent_records"
| "incident_response";
```
---
## Configuration Reference
### All New Environment Variables
```bash
# ============================================
# COMPLIANCE CONFIGURATION
# ============================================
# Core Compliance
NLMCP_COMPLIANCE_ENABLED=true # Enable compliance features
NLMCP_COMPLIANCE_MODE=full # full | minimal | audit_only
NLMCP_COMPLIANCE_REGULATIONS=GDPR,SOC2,CSSF # Which regulations to enforce
# Compliance Logging
NLMCP_COMPLIANCE_DIR=/path/to/compliance # Compliance event directory
NLMCP_COMPLIANCE_RETENTION_YEARS=7 # Retention for compliance events
NLMCP_COMPLIANCE_ENCRYPTION=true # Encrypt compliance logs
# Consent Management
NLMCP_CONSENT_REQUIRED=true # Require consent on first run
NLMCP_CONSENT_VERSION=1.0.0 # Current consent version
NLMCP_PRIVACY_NOTICE_URL=https://... # Link to full privacy policy
# Data Subject Rights
NLMCP_DSAR_ENABLED=true # Enable DSAR handling
NLMCP_ERASURE_ENABLED=true # Enable right to erasure
NLMCP_EXPORT_ENABLED=true # Enable data export
NLMCP_EXPORT_ENCRYPT=false # Encrypt exports by default
# Retention Policies
NLMCP_RETENTION_AUDIT_DAYS=2555 # 7 years for audit logs
NLMCP_RETENTION_SESSION_HOURS=24 # Session data retention
NLMCP_RETENTION_BROWSER_DAYS=7 # Browser cache retention
NLMCP_RETENTION_CHECK_SCHEDULE=daily # When to run retention cleanup
# SIEM Integration
NLMCP_SIEM_ENABLED=false # Enable SIEM export
NLMCP_SIEM_FORMAT=cef # cef | leef | syslog | json | splunk_hec
NLMCP_SIEM_ENDPOINT=https://... # SIEM endpoint URL
NLMCP_SIEM_API_KEY=xxx # SIEM API key
NLMCP_SIEM_BATCH_SIZE=100 # Events per batch
NLMCP_SIEM_FLUSH_INTERVAL_MS=5000 # Flush interval
# Breach Detection
NLMCP_BREACH_DETECTION=true # Enable breach detection
NLMCP_BREACH_NOTIFICATION=true # Auto-notify on breach
NLMCP_BREACH_WEBHOOK=https://... # Breach notification webhook
# Incident Response
NLMCP_INCIDENT_TRACKING=true # Enable incident tracking
NLMCP_INCIDENT_AUTO_CREATE=true # Auto-create incidents on breach
# Alerts
NLMCP_ALERTS_ENABLED=true # Enable alerts
NLMCP_ALERTS_WEBHOOK_URL=https://... # Slack/Teams webhook
NLMCP_ALERTS_EMAIL_TO=security@example.com # Alert email recipients
NLMCP_ALERTS_MIN_SEVERITY=warning # Minimum alert severity
NLMCP_ALERTS_COOLDOWN=300 # Seconds between repeated alerts
# Health Monitoring
NLMCP_HEALTH_MONITORING=true # Enable health monitoring
NLMCP_HEALTH_CHECK_INTERVAL=60 # Seconds between health checks
# Reporting
NLMCP_REPORTS_DIR=/path/to/reports # Report output directory
NLMCP_REPORTS_AUTO_GENERATE=false # Auto-generate periodic reports
NLMCP_REPORTS_SCHEDULE=monthly # Report generation schedule
```
---
## File Structure
```
src/
├── compliance/
│ ├── index.ts # Module exports
│ ├── compliance-logger.ts # Phase 1.1
│ ├── data-classification.ts # Phase 1.2
│ ├── consent-manager.ts # Phase 1.3
│ ├── privacy-notice.ts # Phase 1.4
│ ├── privacy-notice-text.ts # Privacy notice content
│ ├── data-export.ts # Phase 2.1
│ ├── data-erasure.ts # Phase 2.2
│ ├── dsar-handler.ts # Phase 2.3
│ ├── data-inventory.ts # Phase 2.4
│ ├── retention-engine.ts # Phase 2.5
│ ├── siem-exporter.ts # Phase 3.1
│ ├── breach-detection.ts # Phase 3.2
│ ├── incident-manager.ts # Phase 3.3
│ ├── alert-manager.ts # Phase 3.4
│ ├── health-monitor.ts # Phase 3.5
│ ├── dashboard.ts # Phase 4.1
│ ├── report-generator.ts # Phase 4.2
│ ├── policy-docs.ts # Phase 4.3
│ ├── change-log.ts # Phase 4.4
│ ├── evidence-collector.ts # Phase 4.5
│ └── types.ts # Shared types
├── utils/
│ └── audit-logger.ts # Enhanced (Phase 1.5)
└── tools/
└── compliance-tools.ts # New MCP tools
```
---
## Implementation Order
### Phase 1 (Foundation) - Implement First
1. `types.ts` - Shared types
2. `compliance-logger.ts` - Core logging
3. `data-classification.ts` - Classification system
4. `consent-manager.ts` - Consent tracking
5. `privacy-notice.ts` + `privacy-notice-text.ts` - Privacy display
6. Update `audit-logger.ts` - Enhanced events
### Phase 2 (GDPR Rights) - Implement Second
1. `data-inventory.ts` - Data catalog
2. `retention-engine.ts` - Retention enforcement
3. `data-export.ts` - Export functionality
4. `data-erasure.ts` - Erasure functionality
5. `dsar-handler.ts` - DSAR handling
### Phase 3 (Monitoring) - Implement Third
1. `alert-manager.ts` - Alert system
2. `breach-detection.ts` - Breach detection
3. `incident-manager.ts` - Incident tracking
4. `siem-exporter.ts` - SIEM integration
5. `health-monitor.ts` - Health monitoring
### Phase 4 (Reporting) - Implement Last
1. `change-log.ts` - Change tracking
2. `policy-docs.ts` - Policy documentation
3. `dashboard.ts` - Compliance dashboard
4. `report-generator.ts` - Report generation
5. `evidence-collector.ts` - Evidence collection
6. `compliance-tools.ts` - MCP tools
---
## Approval
- [ ] Phase 1 Specification Approved
- [ ] Phase 2 Specification Approved
- [ ] Phase 3 Specification Approved
- [ ] Phase 4 Specification Approved
**Approved By**: ___________________
**Date**: ___________________
