MarketAlly.AIPlugin.Extensions/MarketAlly.AIPlugin.Security/README.md

# MarketAlly AI Plugin Security Toolkit

[![Version](https://img.shields.io/badge/version-2.2.0-blue.svg)](https://www.nuget.org/packages/MarketAlly.AIPlugin.Security)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.txt)
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](#)

Comprehensive security analysis and vulnerability detection framework for the MarketAlly AI Plugin ecosystem. Provides enterprise-grade security scanning with intelligent orchestration, parallel processing, and advanced analytics.

## 🚀 Features

### **Core Security Plugins**
- 🔍 **SecurityScanPlugin**: Detects hardcoded secrets, API keys, and security vulnerabilities
- 🛡️ **AuthenticationAnalyzerPlugin**: Reviews authentication and authorization logic with compliance scoring
- ⚡ **InputValidationPlugin**: Analyzes input validation and sanitization patterns for injection vulnerabilities
- 📦 **VulnerabilityAnalyzerPlugin**: Scans dependencies for known vulnerabilities across multiple ecosystems
- ⚙️ **SecureConfigurationPlugin**: Validates secure configuration practices and environment settings

### **Advanced Framework Features**
- 🎭 **Security Orchestration**: Unified analysis coordination across multiple plugins
- ⚡ **Parallel Processing**: High-performance analysis with configurable parallelism
- 🧠 **Advanced Pattern Engine**: Intelligent pattern matching with entropy-based secret detection
- 📊 **Comprehensive Telemetry**: Performance monitoring, analytics, and trend analysis
- ⚙️ **Central Configuration**: JSON-based configuration management with custom pattern support
- 🧪 **Testing Framework**: Complete unit and integration test coverage

## 📦 Quick Start

### Installation
```bash
dotnet add package MarketAlly.AIPlugin.Security
```

### Basic Usage (Legacy - Individual Plugins)
```csharp
// Register security plugins individually
registry.RegisterPlugin(new SecurityScanPlugin());
registry.RegisterPlugin(new VulnerabilityAnalyzerPlugin());

// Perform security scan
var result = await registry.CallFunctionAsync("SecurityScan", new Dictionary<string, object>
{
    ["path"] = "src/",
    ["scanSecrets"] = true,
    ["scanSqlInjection"] = true,
    ["severityLevel"] = "medium"
});
```

### **Recommended Usage (New - Orchestrated Analysis)**
```csharp
using MarketAlly.AIPlugin.Security.Core;
using MarketAlly.AIPlugin.Security.Configuration;

// Load configuration
var config = SecurityAnalysisConfiguration.LoadFromFile("security-config.json");

// Create orchestrator
var orchestrator = new SecurityAnalysisOrchestrator(config);

// Configure analysis options
var options = new SecurityAnalysisOptions
{
    ScanSecrets = true,
    ScanVulnerabilities = true,
    ScanAuthentication = true,
    ScanInputValidation = true,
    ScanConfiguration = true,
    ScanDependencies = true
};

// Run comprehensive analysis
var report = await orchestrator.RunFullSecurityAnalysis("./src", options);

// Access results
Console.WriteLine($"Overall Risk: {report.OverallRiskLevel}");
Console.WriteLine($"Issues Found: {report.TotalIssuesFound}");

foreach (var recommendation in report.OverallRecommendations)
{
    Console.WriteLine($"• {recommendation}");
}
```

## 🛡️ Security Checks

### **Comprehensive Coverage**
- **Secrets Detection**: API keys, passwords, tokens, certificates, encryption keys
- **Injection Vulnerabilities**: SQL injection, XSS, NoSQL injection, command injection
- **Authentication Issues**: Weak JWT secrets, plain text passwords, missing authorization
- **Configuration Security**: TLS settings, CORS policies, debug modes, environment leaks
- **Dependency Vulnerabilities**: Known CVEs, outdated packages, license compliance
- **Advanced Patterns**: Entropy-based secret detection, custom organizational patterns

### **Supported Technologies**
- **.NET**: C#, VB.NET, F#, ASP.NET Core
- **JavaScript/TypeScript**: Node.js, React, Angular, Vue
- **Python**: Django, Flask, FastAPI
- **Java**: Spring, Maven, Gradle
- **Configuration**: JSON, XML, YAML, INI, Environment files
- **Dependencies**: NuGet, npm, pip, Maven, Composer

## ⚙️ Configuration

### **Basic Configuration**
Create a `security-config.json` file:

```json
{
  "patterns": {
    "customSecretPatterns": [
      {
        "name": "custom_api_key",
        "pattern": "api[_-]?key\\s*[=:]\\s*['\"][a-zA-Z0-9]{32,}['\"]",
        "category": "Secret",
        "severity": "High",
        "description": "Custom API key pattern",
        "enabled": true
      }
    ],
    "enableEntropyBasedDetection": true,
    "entropyThreshold": 4.5
  },
  "scanSettings": {
    "defaultSeverityLevel": "medium",
    "maxFileSizeBytes": 10485760,
    "maxFilesPerScan": 10000
  },
  "performance": {
    "maxParallelism": 8,
    "enableCaching": true,
    "timeoutSeconds": 300
  },
  "reporting": {
    "outputFormats": ["json", "markdown", "sarif"],
    "includeRecommendations": true,
    "maskSensitiveValues": true
  }
}
```

### **Environment-Specific Settings**
```csharp
// Development configuration
var devConfig = SecurityAnalysisConfiguration.GetDefault();
devConfig.ScanSettings.DefaultSeverityLevel = "low";
devConfig.Performance.MaxParallelism = 4;

// Production configuration
var prodConfig = SecurityAnalysisConfiguration.LoadFromFile("security-config.prod.json");
prodConfig.Reporting.MaskSensitiveValues = true;
```

## 📊 Analytics and Monitoring

### **Enable Telemetry**
```csharp
using MarketAlly.AIPlugin.Security.Telemetry;

// Initialize telemetry
using var telemetry = new SecurityAnalyticsTelemetry("./telemetry", enabled: true);

// Track performance automatically
var orchestrator = new SecurityAnalysisOrchestrator(config, telemetry);

// Generate analytics reports
var report = await telemetry.GenerateAnalyticsReportAsync(
    DateTime.UtcNow.AddDays(-30), 
    DateTime.UtcNow);

// Get real-time metrics
var metrics = await telemetry.GetDashboardMetricsAsync();
Console.WriteLine($"Scans today: {metrics.TotalScansToday}");
Console.WriteLine($"Avg analysis time: {metrics.AverageAnalysisTime:F2}ms");
```

### **Performance Monitoring**
```csharp
// Track custom metrics
telemetry.TrackVulnerabilityDetection(new VulnerabilityMetrics
{
    VulnerabilityType = "SQL Injection",
    Severity = "High",
    FilePath = "UserController.cs",
    LineNumber = 42,
    PatternName = "sql_injection_concat"
});

telemetry.TrackPerformanceMetrics(new AnalysisPerformance
{
    OperationType = "FullSecurityScan",
    Duration = TimeSpan.FromSeconds(45),
    FilesAnalyzed = 150,
    Success = true
});
```

## 🧪 Testing

### **Run Tests**
```bash
# Run all tests
dotnet test

# Run specific categories
dotnet test --filter "Category=Unit"
dotnet test --filter "Category=Integration"
dotnet test --filter "Category=Performance"
```

### **Custom Test Scenarios**
```csharp
[Fact]
public async Task SecurityScan_DetectsHardcodedSecrets()
{
    var plugin = new SecurityScanPlugin();
    var tempFile = CreateTestFile("var apiKey = \"sk_live_1234567890\";");
    
    var result = await plugin.ExecuteAsync(new Dictionary<string, object>
    {
        ["path"] = tempFile,
        ["scanSecrets"] = true
    });
    
    Assert.True(result.Success);
    var scanResults = result.Data as SecurityScanResults;
    Assert.True(scanResults.Secrets.Count > 0);
}
```

## 🚀 Advanced Usage

### **Custom Pattern Engine**
```csharp
using MarketAlly.AIPlugin.Security.Core;

var patternEngine = new SecurityPatternEngine(config);

// Load custom patterns
patternEngine.LoadCustomPatterns("custom-patterns.json");

// Analyze with entropy detection
var results = await patternEngine.AnalyzeContentAsync(
    sourceCode, 
    PatternCategory.Secrets);

// High-entropy string detection
var entropyResults = await patternEngine.DetectHighEntropyStrings(sourceCode);
```

### **Parallel File Analysis**
```csharp
// Analyze multiple files in parallel
var files = Directory.GetFiles("./src", "*.cs", SearchOption.AllDirectories);
var results = await patternEngine.AnalyzeFilesAsync(
    files, 
    PatternCategory.All, 
    cancellationToken);

foreach (var fileResult in results)
{
    Console.WriteLine($"File: {fileResult.Key}");
    foreach (var match in fileResult.Value)
    {
        Console.WriteLine($"  Issue: {match.Description} (Line {match.LineNumber})");
    }
}
```

### **CI/CD Integration**

#### **GitHub Actions**
```yaml
name: Security Analysis
on: [push, pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup .NET
        uses: actions/setup-dotnet@v3
        with:
          dotnet-version: '8.0'
          
      - name: Install MarketAlly Security
        run: dotnet add package MarketAlly.AIPlugin.Security
        
      - name: Run Security Analysis
        run: |
          dotnet run --project SecurityAnalysis -- \
            --path ./src \
            --config security-config.json \
            --output security-report.sarif \
            --format sarif
                      
      - name: Upload SARIF results
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: security-report.sarif
```

#### **Azure DevOps**
```yaml
trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: DotNetCoreCLI@2
  displayName: 'Install Security Analyzer'
  inputs:
    command: 'custom'
    custom: 'add'
    arguments: 'package MarketAlly.AIPlugin.Security'

- task: DotNetCoreCLI@2
  displayName: 'Run Security Analysis'
  inputs:
    command: 'run'
    projects: 'SecurityAnalysis.csproj'
    arguments: '--path $(Build.SourcesDirectory) --format sarif'

- task: PublishTestResults@2
  displayName: 'Publish Security Results'
  inputs:
    testResultsFormat: 'VSTest'
    testResultsFiles: '**/*.sarif'
```

## 📚 Documentation

- **[API Reference](API_REFERENCE.md)**: Complete API documentation
- **[Configuration Guide](security-config.json)**: Detailed configuration options
- **[Implementation Report](IMPLEMENTATION_UPDATE_REPORT.md)**: Development and enhancement details
- **[Senior Analysis](SENIOR_DEVELOPER_ANALYSIS.md)**: Architectural analysis and recommendations

## 🤝 Contributing

### **Development Setup**
```bash
# Clone repository
git clone https://github.com/MarketAlly/MarketAlly.AIPlugin.git
cd MarketAlly.AIPlugin/MarketAlly.AIPlugin.Security

# Install dependencies
dotnet restore

# Run tests
dotnet test

# Build package
dotnet build --configuration Release
```

### **Adding Custom Patterns**
1. Create pattern definition in `security-config.json`
2. Add corresponding test cases
3. Update documentation
4. Submit pull request

## 📋 Requirements

- **.NET 8.0** or later
- **Memory**: 512MB+ recommended for large codebases
- **Disk Space**: 100MB+ for telemetry and caching
- **CPU**: Multi-core recommended for parallel processing

## 🔄 Version History

### **v2.2.0** (Latest)
- ✅ Added comprehensive testing infrastructure
- ✅ Implemented central configuration management
- ✅ Created SecurityAnalysisOrchestrator for unified analysis
- ✅ Added SecurityPatternEngine with parallel processing
- ✅ Integrated comprehensive telemetry and analytics
- ✅ Enhanced performance with intelligent caching
- ✅ Added entropy-based secret detection

### **v2.1.0**
- Initial release with core security plugins
- Basic vulnerability detection capabilities
- Individual plugin execution model

## 📄 License

This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.

## 🆘 Support

### **Community Support**
- **GitHub Issues**: [Report bugs and request features](https://github.com/MarketAlly/MarketAlly.AIPlugin/issues)
- **Discussions**: [Community discussions and Q&A](https://github.com/MarketAlly/MarketAlly.AIPlugin/discussions)

### **Enterprise Support**
For enterprise support, custom development, and consulting services, contact: [support@marketally.com](mailto:support@marketally.com)

### **Security Issues**
For security-related issues, please email: [security@marketally.com](mailto:security@marketally.com)

---

## 🌟 Related Projects

- **[MarketAlly.AIPlugin](../MarketAlly.AIPlugin/)**: Core AI Plugin framework
- **[MarketAlly.AIPlugin.Analysis](../MarketAlly.AIPlugin.Analysis/)**: Code analysis and metrics
- **[MarketAlly.AIPlugin.DevOps](../MarketAlly.AIPlugin.DevOps/)**: DevOps automation and CI/CD
- **[MarketAlly.AIPlugin.Refactoring](../MarketAlly.AIPlugin.Refactoring/)**: Code refactoring and optimization

---

*Built with ❤️ by the MarketAlly team for secure, reliable software development.*