Spotter SAST

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

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

Enhanced Compliance Components (v2.1.0)

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

📁 Project Structure

Path	Description
src/	Contains the core application source code.
├── server.js	The main MCP server, integrating over 15 tools.
├── compliance/	Houses all compliance-related logic.
│  ├── compliance-verification.js	Contains the 4 core compliance verification classes.
│  ├── compliance-mcp-tools.js	Includes 10 compliance-specific MCP tools.
│  └── logs/	Stores detailed compliance audit logs.
└── logs/	Stores general application logs.
config/	All configuration files for the application.
├── compliance-frameworks.json	Definitions for 9 supported compliance frameworks.
├── compliance-settings.json	User-defined compliance configurations.
├── enhanced-compliance-config.json	Settings for advanced compliance features.
├── custom-compliance-rules.json	Organization-specific custom compliance rules.
├── custom-policies.json	Custom security policy definitions.
├── monitoring-config.json	Configuration for application monitoring.
├── roles.json	Role-Based Access Control (RBAC) role definitions.
└── tenants/	Configurations for multi-tenant deployments.
infra/	Infrastructure as Code (IaC) and related scripts.
├── docker/	Contains Docker configurations and Dockerfiles.
└── scripts/	Helper and management scripts.
├── compliance.sh	A script for managing compliance tasks.
└── docker-helper.sh	Utility script for Docker operations.
compliance-baselines/	Stores baseline configurations for drift detection.
compliance-evidence/	Contains cryptographically signed evidence for audits.
incident-reports/	Generated reports from the remediation workflow.
test/	Automated tests for the application.
└── test-compliance.js	The testing suite specifically for compliance features.
docs/	Comprehensive project documentation.

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

Register organization/team for multi-tenant compliance management

{
  "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

1. 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
   

2. 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

3. 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
   

4. 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

5. 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
   

6. 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
   

7. 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
   

8. 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:

1. Fork the Repository
2. Create Feature Branch: git checkout -b feature/amazing-feature
3. Add Tests: Ensure all new functionality is tested
4. Follow Code Style: Use existing patterns and conventions
5. Update Documentation: Include relevant documentation updates
6. 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)

• Enhanced Compliance Verification: 9 regulatory frameworks (HIPAA, GDPR, PCI DSS, etc.)
• Compliance Drift Detection: Baseline management and degradation monitoring
• Multi-Tenant Management: Industry-specific templates and risk tolerance levels
• Evidence Collection: Cryptographically signed evidence with chain of custody
• Automated Remediation: Framework-specific workflows with SLA tracking
• Advanced Analytics: Predictive compliance analytics and executive dashboards
• Docker Support: Containerized deployment with compliance features
• Enterprise RBAC: Role-based access control with compliance permissions
• 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.

Copyright (c) 2025 george-mellow

🚨 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