@iflow-mcp/george-mellow-spotter-sast

v2.1.0

Published

11 days ago

Advanced SAST security analysis with multi-tool integration and comprehensive compliance verification

0High
0Medium
0Low

chatflowdev

qystart

security sast compliance hipaa gdpr pci-dss vulnerability-scanning mcp

🔍 Spotter-SAST v2.1.0: Enterprise Security Analysis Platform

A comprehensive Model Context Protocol (MCP) server providing enterprise-grade Static Application Security Testing (SAST) with advanced compliance verification, multi-tenant management, AI-powered analysis, and automated remediation workflows.

🚀 Overview

Spotter-SAST is an advanced security analysis platform that combines multiple industry-standard SAST tools with intelligent automation, continuous monitoring, comprehensive compliance verification, and enterprise-grade reporting. Built on the Model Context Protocol (MCP), it provides both real-time security analysis and long-term security posture management with support for 9 major compliance frameworks.

🎯 Core Features

🔧 Multi-Tool Integration: Seamlessly integrates Semgrep, Bandit, ESLint, and njsscan
🏛️ Compliance Verification: Support for HIPAA, GDPR, PCI DSS, ISO 27001, SOX, NIST CSF, CCPA, FISMA/FedRAMP
🔄 Compliance Drift Detection: Monitor compliance posture changes over time
🏢 Multi-Tenant Management: Manage multiple organizations with different compliance requirements
🔒 Evidence Collection: Cryptographically signed evidence with chain of custody
🤖 Automated Remediation: Framework-specific remediation workflows with SLA tracking
📊 Advanced Analytics: Predictive compliance analytics and executive dashboards
🤖 AI-Powered Fixes: Intelligent vulnerability remediation with confidence scoring
👁️ Continuous Monitoring: Real-time file system monitoring with automated alerts
📈 Enterprise Reporting: Multiple formats including HTML, JSON, Markdown, and SARIF
🛡️ Enterprise Security: OAuth 2.0, RBAC, audit logging, and session management

🏗️ Architecture

Core Components

MultiToolScanner: Orchestrates multiple SAST tools for comprehensive analysis
SecurityManager: Handles authentication, authorization, and audit logging
ContinuousMonitor: Provides real-time file monitoring and scheduled scans
AdvancedReporting: Generates comprehensive reports in multiple formats
AIAutoFixer: Intelligent vulnerability remediation with validation

Enhanced Compliance Components (v2.1.0)

ComplianceDriftDetector: Monitors compliance posture changes and detects degradation
MultiTenantComplianceManager: Manages compliance for multiple organizations/teams
ComplianceEvidenceCollector: Collects and secures compliance evidence with cryptographic integrity
ComplianceRemediationEngine: Automated remediation workflows with SLA tracking

📁 Project Structure

Supported Languages & Tools

| Language | Tools | Extensions | |----------|-------|------------| | JavaScript/TypeScript | Semgrep, ESLint, njsscan, Patterns | .js, .ts, .jsx, .tsx, .vue, .svelte | | Python | Semgrep, Bandit, Patterns | .py, .pyw | | Java/Kotlin | Semgrep, Patterns | .java, .kotlin | | C#/.NET | Semgrep, Patterns | .cs, .vb | | Go | Semgrep, Patterns | .go | | PHP | Semgrep, Patterns | .php, .phtml | | Ruby | Semgrep, Patterns | .rb, .erb | | C/C++ | Semgrep, Patterns | .c, .cpp, .h, .hpp | | Rust | Semgrep, Patterns | .rs |

🚀 Quick Start

1. Prerequisites

Node.js Dependencies:

npm install

Python Security Tools:

pip install -r requirements.txt

Required tools:

Semgrep - Multi-language static analysis
Bandit - Python security linter
ESLint - JavaScript/TypeScript security rules

2. Configuration

Create environment configuration:

cp .env.example .env

Key environment variables:

# Organization Configuration
ORGANIZATION_INDUSTRY=general          # healthcare, finance, ecommerce, government, general
ORGANIZATION_NAME=Your Organization
[email protected]

# Security Configuration
JWT_SECRET=your-secure-jwt-secret
ENABLE_RBAC=true
ENABLE_AUDIT_LOGGING=true

# Enhanced Compliance Features
ENABLE_ENHANCED_COMPLIANCE=true
ENABLE_COMPLIANCE_DRIFT_DETECTION=true
ENABLE_MULTI_TENANT_MANAGEMENT=true
ENABLE_EVIDENCE_COLLECTION=true
ENABLE_AUTOMATED_REMEDIATION=true
ENABLE_ADVANCED_ANALYTICS=true

# Framework-Specific (auto-enabled based on ORGANIZATION_INDUSTRY)
ENABLE_HIPAA=false
ENABLE_GDPR=false
ENABLE_PCI_DSS=false
ENABLE_ISO27001=false
ENABLE_SOX=false
ENABLE_NIST_CSF=true

3. Launch Server

npm start

The server will start with:

✅ 15+ MCP tools (8 core + 7 compliance tools)
✅ Multi-tool SAST capabilities (Semgrep, Bandit, ESLint, njsscan)
✅ Real-time compliance monitoring with drift detection
✅ Multi-tenant compliance management
✅ Cryptographic evidence collection with chain of custody
✅ Automated remediation workflows with SLA tracking
✅ AI-powered auto-fixes with validation
✅ Advanced analytics and executive dashboards

🔧 Available MCP Tools (15+ Tools)

Core Scanning Tools

`enhanced_scan_file`

Comprehensive multi-tool SAST scan for individual files with AI analysis

{
  "filepath": "/path/to/file.js",
  "tools": ["semgrep", "eslint"],
  "policies": ["owasp", "pci"],
  "includeFixSuggestions": true,
  "user_token": "jwt-token"
}

`enhanced_scan_directory`

Directory-wide security analysis with continuous monitoring

{
  "dirpath": "/path/to/project",
  "enableMonitoring": true,
  "schedule": "0 */6 * * *",
  "policies": ["owasp", "enterprise_security"]
}

Enhanced Compliance Tools (v2.1.0)

`compliance_scan`

Comprehensive compliance scanning with framework-specific analysis

{
  "filepath": "/path/to/code",
  "frameworks": ["hipaa", "gdpr", "pci_dss"],
  "industry": "healthcare",
  "include_recommendations": true
}

`compliance_frameworks_manage`

Manage compliance frameworks (enable/disable/configure)

{
  "action": "enable",
  "framework": "hipaa",
  "industry": "healthcare"
}

`compliance_drift_baseline`

Create compliance baselines for drift detection

{
  "project_path": "./src",
  "frameworks": ["hipaa", "gdpr"],
  "baseline_name": "production_baseline"
}

`compliance_drift_detect`

Detect compliance drift from established baselines

{
  "project_path": "./src",
  "frameworks": ["hipaa", "gdpr"]
}

`register_compliance_tenant`

{
  "tenant_id": "acme_healthcare",
  "tenant_config": {
    "name": "ACME Healthcare",
    "industry": "healthcare",
    "template": "healthcare_hipaa",
    "riskTolerance": "zero"
  }
}

`tenant_compliance_assessment`

Perform tenant-specific compliance assessment

{
  "tenant_id": "acme_healthcare",
  "project_path": "./patient_portal"
}

`collect_compliance_evidence`

Collect cryptographically signed compliance evidence

{
  "scan_path": "./src",
  "frameworks": ["hipaa", "pci"],
  "collector": "[email protected]",
  "notes": "Pre-deployment compliance scan"
}

`generate_compliance_audit_report`

Generate comprehensive audit reports with evidence chain

{
  "frameworks": ["hipaa", "pci"],
  "time_range": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-12-31T23:59:59Z"
  },
  "report_format": "detailed"
}

`trigger_compliance_remediation`

Trigger automated compliance remediation workflows

{
  "finding": {
    "type": "hardcoded_secrets",
    "severity": "Critical",
    "file": "./config/database.js"
  },
  "framework": "hipaa",
  "automation_level": "semi_automatic"
}

`compliance_analytics_dashboard`

Advanced compliance analytics with predictive insights

{
  "time_range": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-12-31T23:59:59Z"
  },
  "frameworks": ["hipaa", "gdpr", "pci"],
  "include_predictions": true
}

AI-Powered & Analytics Tools

`ai_enhanced_auto_fix`

Intelligent vulnerability remediation with validation

{
  "filepath": "/path/to/file.js",
  "strategy": "balanced",
  "validate_fixes": true,
  "create_backup": true
}

`start_continuous_monitoring`

Real-time security monitoring with automated alerts

{
  "project_path": "/path/to/project",
  "schedule": "0 */6 * * *",
  "alert_thresholds": {
    "critical": 0,
    "high": 5
  }
}

`security_dashboard`

Real-time security metrics and alerts dashboard

{
  "time_range": "24h",
  "include_trends": true,
  "include_alerts": true
}

Reporting & Policy Management

`generate_enhanced_report`

Comprehensive security reporting with executive summaries

{
  "scan_path": "/path/to/project",
  "report_dir": "./reports",
  "format": "sarif",
  "include_executive_summary": true,
  "include_compliance_matrix": true
}

`manage_security_policies`

Policy and compliance management

{
  "action": "check",
  "policy_name": "owasp",
  "scan_results": {...}
}

`get_enhanced_vulnerability_info`

Comprehensive vulnerability information with OWASP mapping

{
  "vuln_type": "sql_injection"
}

🛡️ Enhanced Security & Compliance Framework (v2.1.0)

Supported Compliance Frameworks (9 Frameworks)

| Framework | Industry | Auto-Enabled | SLA | Key Features | |-----------|----------|--------------|-----|--------------| | HIPAA | Healthcare | ✅ healthcare | 4 hours | PHI detection, breach notification | | GDPR | All | ✅ ecommerce | 72 hours | Data subject rights, privacy by design | | PCI DSS | Finance/Ecommerce | ✅ finance/ecommerce | 2 hours | Cardholder data protection | | ISO 27001 | Enterprise | ✅ general | - | Information security management | | SOX | Financial | ✅ finance | 8 hours | Financial reporting controls | | NIST CSF | All | ✅ all industries | - | Cybersecurity framework | | CCPA | All | ✅ ecommerce | - | California consumer privacy | | FISMA | Government | ✅ government | - | Federal information security | | FedRAMP | Government | ✅ government | - | Federal cloud security |

Enhanced Compliance Features (v2.1.0)

🔄 Compliance Drift Detection

Baseline Management: Cryptographic snapshots of compliance state
Change Detection: Configurable thresholds (5%, 15%, 25%)
Early Warning: Automated alerts on compliance degradation
Trend Analysis: Historical compliance trajectory tracking

🏢 Multi-Tenant Management

Industry Templates: Healthcare, Finance, Government, Enterprise
Risk Tolerance: Zero, Minimal, Low, Medium, High levels
Custom Frameworks: Per-tenant compliance requirements
Isolated Assessments: Tenant-specific compliance scoring

🔒 Evidence Collection & Chain of Custody

Cryptographic Integrity: SHA-256 hashing, digital signatures
Audit Trail: Tamper-proof evidence chain of custody
Legal Grade: Court-admissible compliance evidence
Automated Collection: Evidence from every compliance scan

🤖 Automated Remediation Workflows

Framework-Specific: HIPAA (4hr SLA), PCI DSS (2hr SLA), GDPR (72hr SLA)
Automation Levels: Automatic, Semi-automatic, Manual
Stakeholder Notification: Role-based alert distribution
SLA Tracking: Compliance violation response times

Vulnerability Detection (Enhanced Categories)

| Category | OWASP Mapping | CWE | Severity | Compliance Impact | |----------|---------------|-----|----------|-------------------| | SQL Injection | A03_Injection | CWE-89 | Critical | HIPAA, GDPR, PCI DSS | | Cross-Site Scripting | A03_Injection | CWE-79 | High | All frameworks | | Hardcoded Secrets | A02_Cryptographic_Failures | CWE-798 | Critical | HIPAA, PCI DSS, GDPR | | Command Injection | A03_Injection | CWE-78 | Critical | All frameworks | | Weak Cryptography | A02_Cryptographic_Failures | CWE-327 | Medium | HIPAA, PCI DSS | | Path Traversal | A01_Broken_Access_Control | CWE-22 | High | All frameworks | | Insecure Random | A02_Cryptographic_Failures | CWE-338 | Medium | PCI DSS, HIPAA | | Debug Code | A09_Security_Logging_Monitoring_Failures | CWE-489 | Low | SOX, ISO 27001 | | Insecure Deserialization | A08_Software_Data_Integrity_Failures | CWE-502 | High | All frameworks |

Role-Based Access Control (Enhanced RBAC)

| Role | Level | Key Permissions | Compliance Access | |------|-------|----------------|-------------------| | Security Admin | 4 | Full administrative access (*) | All compliance tools | | Compliance Officer | 4 | Compliance management, audit reports | All compliance tools | | Security Analyst | 3 | Analysis, reporting, policy management | Read/execute compliance tools | | Developer | 2 | Scanning, fix suggestions, basic reporting | Limited compliance access | | Auditor | 1 | Read-only access to scans and compliance | Read-only compliance data | | Viewer | 0 | Basic dashboard and report viewing | Dashboard viewing only |

💼 Industry-Specific Usage Examples

Healthcare Organization Setup

# 1. Configure for healthcare industry
echo "ORGANIZATION_INDUSTRY=healthcare" >> .env
echo "ENABLE_HIPAA=true" >> .env
echo "ENABLE_NIST_CSF=true" >> .env

# 2. Register healthcare tenant
echo '{
  "tenant_id": "acme_medical",
  "tenant_config": {
    "name": "ACME Medical Center",
    "industry": "healthcare",
    "template": "healthcare_hipaa",
    "riskTolerance": "zero",
    "complianceOfficer": "Dr. Sarah Johnson",
    "contactEmail": "[email protected]"
  }
}' | node src/server.js register_compliance_tenant

# 3. Create compliance baseline
echo '{
  "project_path": "./patient-portal",
  "frameworks": ["hipaa", "nist"],
  "baseline_name": "patient_portal_baseline"
}' | node src/server.js compliance_drift_baseline

# 4. Perform HIPAA compliance scan
echo '{
  "tenant_id": "acme_medical",
  "project_path": "./patient-portal"
}' | node src/server.js tenant_compliance_assessment

Financial Services Setup

# Configure for financial industry
echo "ORGANIZATION_INDUSTRY=finance" >> .env
echo "ENABLE_PCI_DSS=true" >> .env
echo "ENABLE_SOX=true" >> .env

# Register financial tenant with strict controls
echo '{
  "tenant_id": "banking_corp",
  "tenant_config": {
    "name": "Banking Corporation",
    "industry": "finance", 
    "template": "financial_pci",
    "riskTolerance": "minimal"
  }
}' | node src/server.js register_compliance_tenant

E-commerce Platform Setup

# Configure for e-commerce
echo "ORGANIZATION_INDUSTRY=ecommerce" >> .env
echo "ENABLE_PCI_DSS=true" >> .env
echo "ENABLE_GDPR=true" >> .env
echo "ENABLE_CCPA=true" >> .env

Compliance Workflow Examples

Evidence Collection Workflow

# 1. Perform comprehensive scan
node src/server.js enhanced_scan_directory ./src

# 2. Collect cryptographic evidence
echo '{
  "scan_path": "./src",
  "frameworks": ["hipaa", "gdpr"],
  "collector": "[email protected]",
  "notes": "Quarterly compliance audit scan"
}' | node src/server.js collect_compliance_evidence

# 3. Generate audit report
echo '{
  "frameworks": ["hipaa", "gdpr"],
  "time_range": {"start": "2024-01-01T00:00:00Z", "end": "2024-12-31T23:59:59Z"},
  "report_format": "detailed"
}' | node src/server.js generate_compliance_audit_report

Automated Remediation Workflow

# Trigger HIPAA violation remediation
echo '{
  "finding": {
    "type": "hardcoded_secrets",
    "severity": "Critical",
    "file": "./config/database.js",
    "line": 15
  },
  "framework": "hipaa",
  "automation_level": "semi_automatic",
  "stakeholders": ["security-team", "compliance-officer"]
}' | node src/server.js trigger_compliance_remediation

Continuous Compliance Monitoring

# Start real-time monitoring with compliance checking
echo '{
  "project_path": "./production-app",
  "schedule": "0 */2 * * *",
  "alert_thresholds": {"critical": 0, "high": 1}
}' | node src/server.js start_continuous_monitoring

# Monitor compliance drift
echo '{
  "project_path": "./production-app",
  "frameworks": ["hipaa", "pci_dss"]
}' | node src/server.js compliance_drift_detect

📊 Enhanced Reporting & Analytics

Available Report Formats

HTML: Interactive reports with charts, compliance matrices, and executive summaries
JSON: Machine-readable structured data with compliance mappings
Markdown: Human-readable documentation format with compliance sections
SARIF: Industry-standard Static Analysis Results Interchange Format
Dashboard: Real-time web-based metrics, trends, and compliance analytics

Comprehensive Report Contents

Executive Summary

📈 Risk Scores: Overall risk assessment with compliance impact
🎯 Severity Distribution: Critical, High, Medium, Low vulnerability counts
🏛️ Compliance Status: Framework-by-framework compliance verification
💡 Action Items: Prioritized recommendations with timelines

Detailed Analysis

🔍 Line-by-Line Findings: Vulnerability analysis with remediation guidance
🧪 Multi-Tool Correlation: Cross-tool validation and confidence scoring
🏛️ Compliance Mapping: Framework-specific control mapping (HIPAA, GDPR, etc.)
🔧 AI-Powered Fixes: Intelligent remediation suggestions with confidence levels

Compliance Matrix

✅ Framework Status: PASS/FAIL status for each enabled framework
📋 Control Mapping: Specific regulatory control violations
🎯 Risk Assessment: Compliance-weighted risk scoring
📊 Trend Analysis: Compliance posture over time

Advanced Analytics

📈 Predictive Insights: Forecast compliance risks and trends
🎯 Risk Hotspots: Identify high-risk code areas and patterns
📊 Tool Effectiveness: SAST tool performance and coverage analysis
🔄 Drift Detection: Compliance baseline comparison and degradation alerts

Sample Compliance Report Output

🛡️ Enhanced SAST Compliance Report
📂 Scanned: /healthcare-app
🏛️ Frameworks: hipaa, gdpr, nist_csf
📊 Overall Status: NON_COMPLIANT  
🎯 Average Score: 73.5%

📋 Framework Results:
   ❌ HIPAA: FAIL (65.2%)
      Violations: 164.312(a)(2)(i) - Hardcoded PHI credentials
                  164.312(e)(2)(ii) - Unencrypted PHI transmission
      SLA: 4 hours remaining
   
   ✅ GDPR: PASS (89.3%)
      Status: All data protection requirements met
   
   ⚠️ NIST CSF: PARTIAL (71.0%)
      Issues: PR.DS-1 - Data security controls need enhancement

💡 Immediate Actions Required:
   1. [CRITICAL] Fix hardcoded PHI credentials (4 hours)
   2. [HIGH] Implement TLS 1.3 for PHI transmission (24 hours)
   3. [MEDIUM] Enhance NIST data security controls (7 days)

🔒 Evidence Collected:
   Evidence ID: EVD_20240815_ABC123
   Integrity Hash: sha256:a1b2c3d4...
   Chain of Custody: 3 entries

🔄 Enhanced CI/CD Integration

GitHub Actions with Compliance Verification

name: Enhanced SAST Security & Compliance Scan
on: [push, pull_request]

jobs:
  security-compliance-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
          
      - name: Install Dependencies
        run: |
          npm install
          pip install -r requirements.txt
          
      - name: Create Compliance Baseline (if not exists)
        run: |
          echo '{"project_path": "./src", "frameworks": ["owasp", "nist"]}' | \\
            node src/server.js compliance_drift_baseline || true
          
      - name: Enhanced Security Scan with Compliance
        run: |
          echo '{"dirpath": "./", "policies": ["owasp", "nist"]}' | \\
            node src/server.js enhanced_scan_directory
            
      - name: Collect Compliance Evidence
        run: |
          echo '{
            "scan_path": "./src",
            "frameworks": ["owasp", "nist"],
            "collector": "github-actions",
            "notes": "CI/CD pipeline compliance scan"
          }' | node src/server.js collect_compliance_evidence
          
      - name: Detect Compliance Drift
        run: |
          echo '{"project_path": "./src", "frameworks": ["owasp", "nist"]}' | \\
            node src/server.js compliance_drift_detect
            
      - name: Generate Enhanced SARIF Report
        run: |
          echo '{
            "scan_path": "./",
            "report_dir": "./reports",
            "format": "sarif",
            "include_compliance_matrix": true
          }' | node src/server.js generate_enhanced_report
          
      - name: Upload SARIF Results
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: reports/enhanced-sast-report-*.sarif
          
      - name: Check Compliance Gate
        run: |
          # Fail build if critical compliance violations found
          if grep -q '"status": "FAIL"' reports/*.json; then
            echo "❌ Compliance gate failed - critical violations found"
            exit 1
          fi

Docker Integration with Compliance

# Enhanced Dockerfile with compliance features
FROM node:18-alpine

WORKDIR /app

# Install Python and security tools
RUN apk add --no-cache python3 py3-pip
COPY requirements.txt .
RUN pip install -r requirements.txt

# Install Node.js dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy application code
COPY src/ ./src/
COPY config/ ./config/
COPY infra/ ./infra/

# Create compliance directories
RUN mkdir -p compliance-baselines compliance-evidence incident-reports logs

# Compliance environment variables
ENV ENABLE_ENHANCED_COMPLIANCE=true
ENV ORGANIZATION_INDUSTRY=general
ENV DEFAULT_COMPLIANCE_FRAMEWORKS=owasp,nist_csf
ENV EVIDENCE_RETENTION_YEARS=7

# Expose health check port
EXPOSE 3000 3001

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \\
  CMD curl -f http://localhost:3001/health || exit 1

# Start with compliance initialization
CMD ["node", "src/server.js"]

Docker Compose with Compliance Services

version: '3.8'
services:
  spotter-sast:
    build: .
    ports:
      - "3000:3000"
      - "3001:3001"
    environment:
      - ORGANIZATION_INDUSTRY=healthcare
      - ENABLE_HIPAA=true
      - ENABLE_EVIDENCE_COLLECTION=true
    volumes:
      - ./code-to-scan:/scan-target:ro
      - ./compliance-reports:/app/reports
      - ./compliance-evidence:/app/compliance-evidence
      - ./compliance-baselines:/app/compliance-baselines
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: compliance_db
      POSTGRES_USER: compliance_user
      POSTGRES_PASSWORD: secure_password
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

Pre-commit Hooks with Compliance

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: spotter-sast-security
        name: Spotter-SAST Security Scan
        entry: node src/server.js enhanced_scan_file
        language: system
        files: \\.(js|ts|py|java|go|php|rb|rs)$
      
      - id: spotter-sast-compliance
        name: Spotter-SAST Compliance Check
        entry: ./infra/scripts/compliance.sh quick-scan
        language: system
        pass_filenames: false
        always_run: true

🚨 Enhanced Monitoring & Alerting

Real-time Monitoring

File System Watching: Instant detection of code changes with compliance impact assessment
Automated Scanning: Triggered on file modifications with framework-specific checks
Smart Filtering: Focuses on security-relevant file types and compliance-critical areas
Performance Optimized: Efficient resource usage with intelligent caching and batching
Compliance Drift Detection: Continuous monitoring of compliance posture changes

Enhanced Alert Channels

Console Logging: Immediate terminal notifications with compliance context
File Logging: Structured logging to src/logs/ and src/compliance/logs/
Security Events: Comprehensive audit trail with chain of custody
Webhook Support: Slack, Teams, and custom webhook integrations
Email Notifications: SMTP-based alerts for compliance violations
SMS Alerts: Emergency notifications for critical compliance breaches

Alert Types & Escalation

🔴 Critical Vulnerabilities: Immediate attention required (0 tolerance)
🟠 High Severity Issues: Address within framework SLA (2-72 hours)
⚖️ Compliance Violations: Policy threshold breaches with stakeholder notification
📊 Compliance Drift: Baseline degradation alerts (5%, 15%, 25% thresholds)
🔄 Monitoring Failures: System health and evidence collection notifications
🏢 Multi-Tenant Alerts: Tenant-specific notifications with custom escalation

Escalation Matrix

Critical → Immediate: Compliance Officer, CISO, CEO
        → 1 hour: Legal Team, Board Chair  
        → 4 hours: External Counsel

High    → 1 hour: Compliance Officer, Security Team
        → 4 hours: Department Heads
        → 24 hours: Executive Team

Medium  → 4 hours: Security Team
        → 24 hours: Compliance Officer  
        → Weekly: Management Team

⚙️ Comprehensive Configuration

Industry-Specific Auto-Configuration

When you set ORGANIZATION_INDUSTRY in your .env file, the system automatically enables appropriate compliance frameworks:

# Healthcare Organizations
ORGANIZATION_INDUSTRY=healthcare
# Auto-enables: HIPAA + NIST CSF
# Features: PHI detection, HIPAA breach workflows, medical data patterns

# Financial Services  
ORGANIZATION_INDUSTRY=finance
# Auto-enables: PCI DSS + SOX + NIST CSF
# Features: Payment data protection, financial controls, audit trails

# E-commerce Platforms
ORGANIZATION_INDUSTRY=ecommerce  
# Auto-enables: PCI DSS + GDPR + CCPA
# Features: Customer data protection, payment security, privacy rights

# Government Agencies
ORGANIZATION_INDUSTRY=government
# Auto-enables: FISMA + FedRAMP + NIST CSF
# Features: Government security standards, federal compliance

# General/Enterprise
ORGANIZATION_INDUSTRY=general
# Auto-enables: OWASP + NIST CSF + ISO 27001
# Features: General security best practices, enterprise standards

Enhanced Environment Variables

# Organization Configuration
ORGANIZATION_NAME=Your Organization
ORGANIZATION_INDUSTRY=general
ORGANIZATION_SIZE=medium
[email protected]

# Security Configuration
JWT_SECRET=your-256-bit-secret-key
ENABLE_RBAC=true
TOKEN_EXPIRY=24h
ENABLE_AUDIT_LOGGING=true

# Enhanced Compliance Features (v2.1.0)
ENABLE_ENHANCED_COMPLIANCE=true
ENABLE_COMPLIANCE_DRIFT_DETECTION=true
ENABLE_MULTI_TENANT_MANAGEMENT=true
ENABLE_EVIDENCE_COLLECTION=true
ENABLE_AUTOMATED_REMEDIATION=true
ENABLE_ADVANCED_ANALYTICS=true

# Framework Configuration
DEFAULT_COMPLIANCE_FRAMEWORKS=owasp,nist_csf
AUTO_ENABLE_INDUSTRY_FRAMEWORKS=true

# Individual framework controls
ENABLE_HIPAA=false
ENABLE_GDPR=false
ENABLE_PCI_DSS=false
ENABLE_ISO27001=false
ENABLE_SOX=false
ENABLE_NIST_CSF=true

# Monitoring Configuration
DEFAULT_SCAN_SCHEDULE=0 */6 * * *
COMPLIANCE_SCAN_FREQUENCY=daily
ALERT_THRESHOLD_CRITICAL=0
ALERT_THRESHOLD_HIGH=5

# Evidence & Audit Configuration
EVIDENCE_RETENTION_YEARS=7
EVIDENCE_CRYPTOGRAPHIC_SIGNING=true
COMPLIANCE_EVIDENCE_RETENTION_DAYS=2555
AUDIT_TRAIL_IMMUTABLE=true

Multi-Tenant Configuration

Create tenant-specific configurations in config/tenants/:

{
  "tenant_id": "healthcare_division",
  "config": {
    "name": "Healthcare Division", 
    "industry": "healthcare",
    "riskTolerance": "zero",
    "enabledFrameworks": ["hipaa", "nist"],
    "customRules": ["phi_detection", "encryption_required"],
    "contactEmail": "[email protected]",
    "complianceOfficer": "Dr. Sarah Johnson",
    "escalationMatrix": {
      "critical": ["[email protected]", "[email protected]"],
      "high": ["[email protected]", "[email protected]"]
    }
  }
}

Advanced Security Policies

Customize security policies in config/custom-policies.json:

{
  "healthcare_strict": {
    "name": "Healthcare Strict Security Policy",
    "requiredChecks": ["hardcoded_secrets", "weak_crypto", "phi_exposure"],
    "failThresholds": {
      "critical": 0,
      "high": 0,
      "medium": 2
    },
    "complianceFrameworks": ["hipaa", "nist"],
    "automatedRemediation": true,
    "evidenceCollection": true
  },
  "enterprise_standard": {
    "name": "Enterprise Standard Policy",
    "requiredChecks": ["owasp_top_10"],
    "failThresholds": {
      "critical": 0,
      "high": 5,
      "medium": 20
    }
  }
}

Compliance Framework Configuration

Detailed framework settings in config/compliance-frameworks.json:

{
  "hipaa": {
    "version": "2013_final_rule",
    "enabled": true,
    "riskTolerance": "zero",
    "requiredControls": ["164.312(a)", "164.312(c)", "164.312(e)"],
    "patterns": {
      "phi_patterns": [
        "(?i)(ssn|social\\\\s*security)\\\\s*[:=]?\\\\s*\\\\d{3}-?\\\\d{2}-?\\\\d{4}",
        "(?i)(patient|medical)\\\\s*id\\\\s*[:=]?\\\\s*\\\\d+"
      ]
    },
    "slaHours": 4,
    "automatedWorkflows": ["phi_exposure", "audit_trail"]
  }
}

Performance & Scalability Configuration

# Performance Tuning
MAX_CONCURRENT_COMPLIANCE_SCANS=3
COMPLIANCE_SCAN_TIMEOUT=1800
CACHE_COMPLIANCE_RESULTS=true
COMPLIANCE_CACHE_EXPIRATION=60
SCAN_PARALLEL_WORKERS=4
EVIDENCE_BATCH_SIZE=100
ANALYTICS_QUERY_TIMEOUT_SECONDS=30

# Scalability Settings
MAX_TENANTS_PER_INSTANCE=100
BASELINE_COMPARISON_CACHE_SIZE=1000
ANALYTICS_HISTORICAL_RETENTION_MONTHS=24
EVIDENCE_RETENTION_YEARS=7

🛠️ Advanced Usage & Enterprise Features

Compliance Management Script

Use the enhanced compliance script for comprehensive management:

# Setup & Configuration
./infra/scripts/compliance.sh setup                    # Initialize compliance system
./infra/scripts/compliance.sh configure-industry healthcare  # Configure for industry
./infra/scripts/compliance.sh enable hipaa            # Enable specific framework
./infra/scripts/compliance.sh list                    # List available frameworks

# Scanning & Analysis  
./infra/scripts/compliance.sh quick-scan ./src        # Quick compliance scan
./infra/scripts/compliance.sh scan ./project hipaa,gdpr html  # Full scan with frameworks
./infra/scripts/compliance.sh baseline ./src hipaa   # Create compliance baseline

# Monitoring & Reporting
./infra/scripts/compliance.sh start-monitoring ./src "0 */6 * * *"  # Start monitoring
./infra/scripts/compliance.sh report ./project html   # Generate comprehensive report
./infra/scripts/compliance.sh status                  # Check system status
./infra/scripts/compliance.sh validate               # Validate configuration

Enterprise Database Integration

For large-scale deployments, configure database backend:

# Database Configuration
USE_DATABASE_STORAGE=true
DATABASE_TYPE=postgresql
DATABASE_HOST=your-db-host
DATABASE_PORT=5432
DATABASE_NAME=compliance_db
DATABASE_USER=compliance_user
DATABASE_PASS=your-secure-password
DATABASE_SSL=true
DATABASE_CONNECTION_POOL_SIZE=10

# Redis Caching
REDIS_ENABLED=true
REDIS_HOST=your-redis-host
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password
REDIS_CACHE_TTL_SECONDS=3600

Custom Vulnerability Patterns

Add organization-specific patterns to vulnerability detection:

// In config/custom-compliance-rules.json
{
  "custom_patterns": {
    "company_api_leak": {
      "patterns": ["(?i)ACME-API-KEY-[A-Za-z0-9]{32}"],
      "severity": "Critical",
      "owaspCategory": "A02_Cryptographic_Failures",
      "description": "Company API key detected in code",
      "complianceMapping": {
        "hipaa": ["164.312(a)(2)(i)"],
        "pci_dss": ["3.4"]
      }
    },
    "internal_service_creds": {
      "patterns": ["(?i)(internal[_-]?service)[_-]?(key|token|secret)\\\\s*[:=]\\\\s*[\"'][^\"'\\\\s]{10,}"],
      "severity": "High",
      "description": "Internal service credentials detected"
    }
  }
}

Webhook Integration Examples

Slack Integration

# Configure Slack webhook in .env
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK
NOTIFICATION_CHANNELS=email,slack
IMMEDIATE_NOTIFY_SEVERITIES=critical,high

Microsoft Teams Integration

# Configure Teams webhook in .env
TEAMS_WEBHOOK_URL=https://outlook.office.com/webhook/YOUR/TEAMS/WEBHOOK
WEBHOOK_RETRY_ATTEMPTS=3
WEBHOOK_TIMEOUT_SECONDS=30

Performance Optimization for Large Codebases

# For repositories with 100,000+ files
SCAN_PARALLEL_WORKERS=8
MAX_CONCURRENT_COMPLIANCE_SCANS=5
COMPLIANCE_SCAN_TIMEOUT=3600
EVIDENCE_BATCH_SIZE=500

# Memory optimization
NODE_OPTIONS=--max-old-space-size=8192

# Caching optimization
CACHE_COMPLIANCE_RESULTS=true
COMPLIANCE_CACHE_EXPIRATION=120
BASELINE_COMPARISON_CACHE_SIZE=5000

Integration Examples

CLI Usage with Compliance

# Single file scan with compliance frameworks
echo '{"filepath": "/path/to/file.js", "policies": ["hipaa", "gdpr"]}' | \\
  node src/server.js enhanced_scan_file

# Directory scan with compliance evidence collection
echo '{"dirpath": "/path/to/project", "enableMonitoring": true}' | \\
  node src/server.js enhanced_scan_directory

# Generate compliance report
echo '{"scan_path": "/path/to/project", "report_dir": "./reports", "format": "html"}' | \\
  node src/server.js generate_enhanced_report

Programmatic Usage with MCP Client

import { McpClient } from "@modelcontextprotocol/sdk/client/mcp.js";

const client = new McpClient();
await client.connect();

// Enhanced scan with compliance
const result = await client.callTool("enhanced_scan_file", {
  filepath: "/path/to/file.js",
  policies: ["hipaa", "gdpr"],
  includeFixSuggestions: true
});

// Multi-tenant compliance assessment
const assessment = await client.callTool("tenant_compliance_assessment", {
  tenant_id: "healthcare_division",
  project_path: "./patient-portal"
});

// Collect compliance evidence
const evidence = await client.callTool("collect_compliance_evidence", {
  scan_path: "./src",
  frameworks: ["hipaa", "gdpr"],
  collector: "[email protected]",
  notes: "Quarterly audit scan"
});

📈 Performance & Scalability

Enhanced Optimization Features

Parallel Tool Execution: Multiple SAST tools run concurrently with compliance analysis
Intelligent Caching: Scan result caching for repeated analyses with compliance state
Incremental Scanning: Only scan changed files in monitoring mode with drift detection
Resource Management: Memory and CPU optimization for large codebases and compliance workloads
Batched Processing: Efficient handling of large directory structures with evidence collection
Multi-Tenant Isolation: Performance isolation between tenant assessments
Compliance Baseline Caching: Fast drift detection through optimized baseline comparisons

Performance Metrics

Scan Speed: ~100-500 files/minute (depending on file size, complexity, and compliance frameworks)
Memory Usage: ~50-200MB base + ~1-5MB per concurrent file scan + ~10-50MB for compliance features
Tool Detection: Sub-second tool availability checking with compliance framework validation
Report Generation: ~1-10 seconds for comprehensive reports, ~5-30 seconds for compliance reports
Evidence Collection: ~100-500ms per scan for cryptographic evidence generation
Baseline Creation: ~1-5 seconds for project baseline snapshot creation
Drift Detection: ~500ms-2s for baseline comparison and drift analysis

Scalability Benchmarks

Concurrent Scans: Up to 8 parallel compliance scans per instance
Multi-Tenant Support: 100+ tenants per instance with isolation
Evidence Storage: Handles millions of evidence records with integrity verification
Baseline Management: 1000+ project baselines with efficient comparison algorithms
Large Repositories: Tested with 100,000+ files and multiple compliance frameworks
Real-Time Monitoring: Supports monitoring 10+ projects simultaneously

Resource Requirements

Minimum Requirements

CPU: 2 cores, 2.0 GHz
Memory: 4 GB RAM
Storage: 10 GB (including logs and evidence)
Node.js: 18.0.0+
Python: 3.9+

Recommended for Enterprise

CPU: 4+ cores, 3.0 GHz
Memory: 8+ GB RAM
Storage: 50+ GB SSD (for evidence and baseline storage)
Database: PostgreSQL 15+ (for enterprise evidence storage)
Cache: Redis 7+ (for performance optimization)

🔍 Troubleshooting

Common Issues

Security Tools Not Found

# Install missing SAST tools
pip install semgrep bandit
npm install -g eslint
   
# Verify tool installation
semgrep --version
bandit --version
eslint --version

Permission Denied
- Check RBAC configuration in config/roles.json
- Verify JWT token validity and expiration
- Ensure user has required permissions for compliance operations
- Check file system permissions for evidence collection

Memory Issues with Large Codebases

# Increase Node.js heap size
node --max-old-space-size=4096 src/server.js
   
# Optimize compliance scanning
export MAX_CONCURRENT_COMPLIANCE_SCANS=2
export SCAN_PARALLEL_WORKERS=2

Authentication Failed
- Verify JWT_SECRET environment variable is set
- Check token expiration settings in configuration
- Review user role assignments in config/roles.json
- Ensure compliance officer permissions are configured

Compliance Framework Issues

# Validate compliance configuration
./infra/scripts/compliance.sh validate
   
# Check framework status
echo '{"action": "list"}' | node src/server.js compliance_frameworks_manage
   
# Reset compliance configuration
./infra/scripts/compliance.sh setup

Evidence Collection Failures

# Check evidence directory permissions
mkdir -p compliance-evidence
chmod 755 compliance-evidence
   
# Verify cryptographic signing capability
echo '{"test": "evidence"}' | openssl dgst -sha256

Baseline Creation/Drift Detection Issues

# Check baseline directory
ls -la compliance-baselines/
   
# Recreate baseline if corrupted
echo '{
  "project_path": "./src",
  "frameworks": ["owasp", "nist"]
}' | node src/server.js compliance_drift_baseline

Multi-Tenant Configuration Issues

# Validate tenant configuration
node -c config/tenants/tenant_id.json
   
# Check tenant permissions
ls -la config/tenants/

Debug Mode

Enable comprehensive debug logging:

# Debug mode with compliance details
export LOG_LEVEL=debug
export DEBUG_COMPLIANCE_ENGINE=true
export COMPLIANCE_DEBUG_MODE=true
npm start

# Monitor compliance logs
tail -f src/compliance/logs/compliance.log

Health Checks

# Check system health
curl http://localhost:3001/health

# Validate compliance components
./infra/scripts/compliance.sh status

# Test compliance frameworks
echo '{"action": "list"}' | node src/server.js compliance_frameworks_manage

Performance Diagnostics

# Monitor resource usage during scans
top -p $(pgrep -f "node src/server.js")

# Check compliance scan performance
time echo '{"dirpath": "./src"}' | node src/server.js enhanced_scan_directory

# Analyze evidence collection performance
time echo '{
  "scan_path": "./src",
  "frameworks": ["owasp"],
  "collector": "[email protected]"
}' | node src/server.js collect_compliance_evidence

Support Resources

📖 Documentation:
- docs/COMPLIANCE_FEATURES.md - User guide for compliance features
- docs/ENHANCED_COMPLIANCE_FEATURES.md - Technical documentation
- docs/COMPLIANCE_MODULE_SUMMARY.md - Implementation overview
🐛 Issues: GitHub Issues for bug reports and feature requests
💬 Discussions: GitHub Discussions for community support
📧 Compliance Support: [email protected]
🔧 Technical Support: Maintainer contact via GitHub profile

🤝 Contributing

We welcome contributions! Please see our contributing guidelines:

Fork the Repository
Create Feature Branch: git checkout -b feature/amazing-feature
Add Tests: Ensure all new functionality is tested
Follow Code Style: Use existing patterns and conventions
Update Documentation: Include relevant documentation updates
Submit Pull Request: Clear description of changes and impact

Development Setup

# Clone repository
git clone https://github.com/george-mellow/spotter-sast.git
cd spotter-sast

# Install dependencies
npm install
pip install -r requirements.txt

# Run in development mode
LOG_LEVEL=debug npm start

Testing

# Run security scan on test files
npm test

# Run compliance-specific tests
node test/test-compliance.js

# Test individual compliance features
./infra/scripts/compliance.sh validate

📋 Roadmap

✅ Completed Features (v2.1.0)

[x] Enhanced Compliance Verification: 9 regulatory frameworks (HIPAA, GDPR, PCI DSS, etc.)
[x] Compliance Drift Detection: Baseline management and degradation monitoring
[x] Multi-Tenant Management: Industry-specific templates and risk tolerance levels
[x] Evidence Collection: Cryptographically signed evidence with chain of custody
[x] Automated Remediation: Framework-specific workflows with SLA tracking
[x] Advanced Analytics: Predictive compliance analytics and executive dashboards
[x] Docker Support: Containerized deployment with compliance features
[x] Enterprise RBAC: Role-based access control with compliance permissions
[x] Advanced Reporting: HTML, JSON, Markdown, SARIF with compliance matrices

🚧 In Progress (v2.2.0)

[ ] Web Dashboard: Browser-based security and compliance dashboard
[ ] Slack/Teams Integration: Enhanced real-time alert notifications
[ ] API Gateway: RESTful API for external compliance integrations
[ ] Mobile Dashboard: Mobile app for compliance monitoring
[ ] Enhanced ML Features: Advanced vulnerability prediction with compliance context

🔮 Future Features (v3.0.0+)

[ ] Cloud-Native Integration: AWS/Azure/GCP native compliance integrations
[ ] Compliance Automation Platform: No-code compliance workflow builder
[ ] Advanced Threat Modeling: AI-powered threat modeling with compliance mapping
[ ] Regulatory Intelligence: Automatic updates for changing compliance requirements
[ ] Cross-Platform CLI: Enhanced CLI tools for compliance management
[ ] Enterprise SSO: SAML/OIDC integration for enterprise authentication
[ ] Compliance Marketplace: Third-party compliance plugin ecosystem

Long-term Vision (v4.0.0+)

🤖 AI Compliance Officer: Fully automated compliance management and reporting
🌐 Global Compliance Hub: Multi-region compliance management platform
📊 Compliance Intelligence: Machine learning-powered compliance insights
🔗 Ecosystem Integration: Deep integration with popular enterprise security tools
📱 Executive Mobile App: C-suite mobile dashboard for compliance oversight
🎯 Predictive Compliance: AI-powered prediction of regulatory changes and impacts

📄 License

MIT License - see LICENSE file for details.

🚨 Security Notice

Important: This tool performs security analysis but does not guarantee complete security. Always complement automated scanning with:

👥 Manual Security Reviews: Expert human analysis
🎯 Penetration Testing: Real-world attack simulation
🔄 Dynamic Analysis (DAST): Runtime vulnerability testing
📦 Dependency Scanning: Third-party library security
🐳 Container Security: Docker/Kubernetes security scanning
🔐 Infrastructure Security: Cloud and network security assessment

📊 Project Stats (v2.1.0)

Core Statistics

Version: v2.1.0 (Enterprise-grade with Enhanced Compliance)
Languages: JavaScript/Node.js, Python
Dependencies: 12+ Node.js packages, 8+ Python packages
SAST Tools: 4 integrated tools (Semgrep, Bandit, ESLint, njsscan)
MCP Tools: 15+ tools (8 core + 7 compliance-specific)
File Types: 20+ supported file extensions across 9 programming languages

Compliance & Security

Compliance Frameworks: 9 major regulatory frameworks (HIPAA, GDPR, PCI DSS, ISO 27001, SOX, NIST CSF, CCPA, FISMA, FedRAMP)
Vulnerability Categories: 9+ categories with comprehensive OWASP Top 10 2021 mapping
Industry Templates: 5 industry-specific compliance templates
Risk Tolerance Levels: 5 configurable levels (Zero, Minimal, Low, Medium, High)
Report Formats: 5 formats (HTML, JSON, Markdown, SARIF, Dashboard)

Advanced Features

Multi-Tenant Support: 100+ tenants per instance with isolation
Evidence Management: Cryptographically signed evidence with chain of custody
Baseline Management: 1000+ project baselines for drift detection
Automated Workflows: Framework-specific remediation with SLA tracking
Analytics Engine: Predictive compliance analytics with trend analysis
Performance Optimization: Parallel processing with intelligent caching

Enterprise Capabilities

Role-Based Access: 6 predefined roles with granular permissions
Audit Logging: Comprehensive audit trail with compliance evidence
Real-Time Monitoring: Continuous file system monitoring with alerts
Integration Ready: CI/CD, Docker, webhook, and API integrations
Scalability: Tested with enterprise-scale codebases (100,000+ files)
Security: Enterprise-grade authentication, authorization, and encryption

🎯 Elevate your security posture with enterprise-grade SAST analysis powered by AI and comprehensive compliance verification.

Built with ❤️ for secure software development and regulatory compliance