MarketAlly.AIPlugin.Extensions/MarketAlly.AIPlugin.Security/API_REFERENCE.md

# MarketAlly.AIPlugin.Security - API Reference

## Table of Contents

- [Core Orchestration](#core-orchestration)
- [Security Plugins](#security-plugins)
- [Configuration Management](#configuration-management)
- [Pattern Engine](#pattern-engine)
- [Telemetry and Analytics](#telemetry-and-analytics)
- [Data Models](#data-models)
- [Enumerations](#enumerations)

---

## Core Orchestration

### SecurityAnalysisOrchestrator

The central orchestrator for coordinating comprehensive security analysis across multiple plugins.

#### Constructor

```csharp
public SecurityAnalysisOrchestrator(
    SecurityAnalysisConfiguration configuration = null, 
    ILogger<SecurityAnalysisOrchestrator> logger = null)
```

**Parameters:**
- `configuration` - Security configuration settings (uses default if null)
- `logger` - Optional logger for operation tracking

#### Methods

##### RunFullSecurityAnalysis

```csharp
public async Task<ComprehensiveSecurityReport> RunFullSecurityAnalysis(
    string targetPath, 
    SecurityAnalysisOptions options,
    CancellationToken cancellationToken = default)
```

Executes comprehensive security analysis using all configured plugins.

**Parameters:**
- `targetPath` - Path to analyze (file or directory)
- `options` - Analysis configuration options
- `cancellationToken` - Cancellation token for operation control

**Returns:** `ComprehensiveSecurityReport` containing aggregated results

**Example:**
```csharp
var orchestrator = new SecurityAnalysisOrchestrator();
var options = new SecurityAnalysisOptions
{
    ScanSecrets = true,
    ScanVulnerabilities = true,
    ScanAuthentication = true
};

var report = await orchestrator.RunFullSecurityAnalysis("./src", options);
Console.WriteLine($"Total issues: {report.TotalIssuesFound}");
```

##### RunSpecificAnalysis<T>

```csharp
public async Task<AIPluginResult> RunSpecificAnalysis<T>(
    string targetPath,
    Dictionary<string, object> parameters,
    CancellationToken cancellationToken = default) where T : IAIPlugin, new()
```

Executes a specific security plugin with timeout protection.

**Parameters:**
- `targetPath` - Path to analyze
- `parameters` - Plugin-specific parameters
- `cancellationToken` - Cancellation token

**Returns:** `AIPluginResult` from the specific plugin

**Example:**
```csharp
var result = await orchestrator.RunSpecificAnalysis<SecurityScanPlugin>(
    "./src",
    new Dictionary<string, object>
    {
        ["path"] = "./src",
        ["scanSecrets"] = true,
        ["severityLevel"] = "high"
    });
```

---

## Security Plugins

### SecurityScanPlugin

Comprehensive security scanning for secrets, vulnerabilities, and configuration issues.

#### Properties

```csharp
[AIParameter("Full path to the file or directory to scan", required: true)]
public string Path { get; set; }

[AIParameter("Scan for hardcoded secrets (API keys, passwords)", required: false)]
public bool ScanSecrets { get; set; } = true;

[AIParameter("Scan for SQL injection vulnerabilities", required: false)]
public bool ScanSqlInjection { get; set; } = true;

[AIParameter("Scan for XSS vulnerabilities", required: false)]
public bool ScanXss { get; set; } = true;

[AIParameter("Scan for insecure configurations", required: false)]
public bool ScanConfigurations { get; set; } = true;

[AIParameter("Security scan severity level: low, medium, high, critical", required: false)]
public string SeverityLevel { get; set; } = "medium";
```

#### Supported Parameters

```csharp
public IReadOnlyDictionary<string, Type> SupportedParameters => new Dictionary<string, Type>
{
    ["path"] = typeof(string),
    ["scanSecrets"] = typeof(bool),
    ["scanSqlInjection"] = typeof(bool),
    ["scanXss"] = typeof(bool),
    ["scanConfigurations"] = typeof(bool),
    ["severityLevel"] = typeof(string)
};
```

#### Example Usage

```csharp
var plugin = new SecurityScanPlugin();
var result = await plugin.ExecuteAsync(new Dictionary<string, object>
{
    ["path"] = "./src",
    ["scanSecrets"] = true,
    ["scanSqlInjection"] = true,
    ["severityLevel"] = "medium"
});

var scanResults = result.Data as SecurityScanResults;
Console.WriteLine($"Found {scanResults.Secrets.Count} secrets");
```

### AuthenticationAnalyzerPlugin

Analyzes authentication and authorization patterns for security best practices.

#### Properties

```csharp
[AIParameter("Full path to the file or directory to analyze", required: true)]
public string Path { get; set; }

[AIParameter("Check JWT implementation", required: false)]
public bool CheckJwt { get; set; } = true;

[AIParameter("Check OAuth implementation", required: false)]
public bool CheckOAuth { get; set; } = true;

[AIParameter("Check session management", required: false)]
public bool CheckSessions { get; set; } = true;

[AIParameter("Check authorization patterns", required: false)]
public bool CheckAuthorization { get; set; } = true;

[AIParameter("Check password handling", required: false)]
public bool CheckPasswords { get; set; } = true;
```

#### Example Usage

```csharp
var plugin = new AuthenticationAnalyzerPlugin();
var result = await plugin.ExecuteAsync(new Dictionary<string, object>
{
    ["path"] = "./src",
    ["checkJwt"] = true,
    ["checkAuthorization"] = true
});

var authResults = result.Data as AuthenticationAnalysisResults;
Console.WriteLine($"Compliance Score: {authResults.ComplianceScore}");
```

### InputValidationPlugin

Analyzes input validation patterns and injection vulnerabilities.

#### Properties

```csharp
[AIParameter("Full path to the file to analyze", required: true)]
public string FilePath { get; set; }

[AIParameter("Check for SQL injection protection", required: false)]
public bool CheckSqlInjection { get; set; } = true;

[AIParameter("Check for XSS protection", required: false)]
public bool CheckXssProtection { get; set; } = true;

[AIParameter("Check for CSRF protection", required: false)]
public bool CheckCsrfProtection { get; set; } = true;

[AIParameter("Analyze sanitization patterns", required: false)]
public bool AnalyzeSanitization { get; set; } = true;

[AIParameter("Generate validation suggestions", required: false)]
public bool GenerateSuggestions { get; set; } = true;
```

### VulnerabilityAnalyzerPlugin

Scans project dependencies for known vulnerabilities.

#### Properties

```csharp
[AIParameter("Full path to the project file or directory", required: true)]
public string ProjectPath { get; set; }

[AIParameter("Include transitive dependencies in analysis", required: false)]
public bool IncludeTransitive { get; set; } = true;

[AIParameter("Check for outdated packages", required: false)]
public bool CheckOutdated { get; set; } = true;

[AIParameter("Vulnerability database source: nvd, github, snyk", required: false)]
public string VulnerabilitySource { get; set; } = "nvd";

[AIParameter("Generate upgrade recommendations", required: false)]
public bool GenerateRecommendations { get; set; } = true;
```

### SecureConfigurationPlugin

Validates configuration files for security best practices.

#### Properties

```csharp
[AIParameter("Full path to the configuration file or directory", required: true)]
public string ConfigPath { get; set; }

[AIParameter("Check for exposed secrets in config files", required: false)]
public bool CheckSecrets { get; set; } = true;

[AIParameter("Validate HTTPS/TLS configurations", required: false)]
public bool CheckTls { get; set; } = true;

[AIParameter("Check database connection security", required: false)]
public bool CheckDatabase { get; set; } = true;

[AIParameter("Validate CORS settings", required: false)]
public bool CheckCors { get; set; } = true;

[AIParameter("Check environment-specific configurations", required: false)]
public bool CheckEnvironments { get; set; } = true;
```

---

## Configuration Management

### SecurityAnalysisConfiguration

Central configuration management for all security analysis settings.

#### Properties

```csharp
public PatternConfiguration Patterns { get; set; }
public ScanConfiguration ScanSettings { get; set; }
public ReportingConfiguration Reporting { get; set; }
public PerformanceConfiguration Performance { get; set; }
```

#### Static Methods

##### LoadFromFile

```csharp
public static SecurityAnalysisConfiguration LoadFromFile(string configPath)
```

Loads configuration from JSON file.

**Example:**
```csharp
var config = SecurityAnalysisConfiguration.LoadFromFile("security-config.json");
```

##### GetDefault

```csharp
public static SecurityAnalysisConfiguration GetDefault()
```

Returns default configuration with sensible defaults.

#### Instance Methods

##### SaveToFile

```csharp
public void SaveToFile(string configPath)
```

Saves current configuration to JSON file.

##### Validate

```csharp
public ValidationResult Validate()
```

Validates configuration settings and returns validation result.

### PatternConfiguration

Configuration for custom security patterns and detection rules.

#### Properties

```csharp
public List<CustomPattern> CustomSecretPatterns { get; set; }
public List<CustomPattern> CustomVulnerabilityPatterns { get; set; }
public List<string> ExcludedPatterns { get; set; }
public bool EnableEntropyBasedDetection { get; set; }
public double EntropyThreshold { get; set; }
```

### ScanConfiguration

Configuration for scan behavior and file processing.

#### Properties

```csharp
public List<string> IncludedFileExtensions { get; set; }
public List<string> ExcludedDirectories { get; set; }
public List<string> ExcludedFiles { get; set; }
public long MaxFileSizeBytes { get; set; }
public int MaxFilesPerScan { get; set; }
public string DefaultSeverityLevel { get; set; }
public bool EnableContextAnalysis { get; set; }
public int ContextLineRadius { get; set; }
```

### PerformanceConfiguration

Configuration for performance optimization settings.

#### Properties

```csharp
public int MaxParallelism { get; set; }
public bool EnableCaching { get; set; }
public int CacheExpiryMinutes { get; set; }
public bool EnableIncrementalAnalysis { get; set; }
public int TimeoutSeconds { get; set; }
public int RateLimitDelayMs { get; set; }
```

### CustomPattern

Defines a custom security pattern for detection.

#### Properties

```csharp
public string Name { get; set; }
public string Pattern { get; set; }
public string Category { get; set; }
public string Severity { get; set; }
public string Description { get; set; }
public string Recommendation { get; set; }
public bool Enabled { get; set; }
```

#### Methods

##### ToRegex

```csharp
public Regex ToRegex()
```

Compiles the pattern to a Regex object with appropriate flags.

---

## Pattern Engine

### SecurityPatternEngine

Advanced pattern matching engine with parallel processing and caching.

#### Constructor

```csharp
public SecurityPatternEngine(SecurityAnalysisConfiguration configuration = null)
```

#### Methods

##### AnalyzeContentAsync

```csharp
public async Task<PatternMatchResult[]> AnalyzeContentAsync(
    string content, 
    PatternCategory category,
    CancellationToken cancellationToken = default)
```

Analyzes content for security patterns with parallel processing.

**Parameters:**
- `content` - Content to analyze
- `category` - Pattern category to filter by
- `cancellationToken` - Cancellation token

**Returns:** Array of pattern match results

**Example:**
```csharp
var engine = new SecurityPatternEngine();
var results = await engine.AnalyzeContentAsync(sourceCode, PatternCategory.Secrets);
foreach (var result in results)
{
    Console.WriteLine($"Found {result.Description} at line {result.LineNumber}");
}
```

##### AnalyzeFilesAsync

```csharp
public async Task<Dictionary<string, PatternMatchResult[]>> AnalyzeFilesAsync(
    IEnumerable<string> filePaths,
    PatternCategory category,
    CancellationToken cancellationToken = default)
```

Analyzes multiple files in parallel for security patterns.

##### LoadCustomPatterns

```csharp
public void LoadCustomPatterns(string configPath)
```

Loads custom patterns from configuration file.

##### CalculateEntropy

```csharp
public double CalculateEntropy(string input)
```

Calculates Shannon entropy for potential secret detection.

##### DetectHighEntropyStrings

```csharp
public async Task<PatternMatchResult[]> DetectHighEntropyStrings(
    string content,
    CancellationToken cancellationToken = default)
```

Detects high-entropy strings that might be secrets.

---

## Telemetry and Analytics

### SecurityAnalyticsTelemetry

Comprehensive telemetry and analytics for security operations.

#### Constructor

```csharp
public SecurityAnalyticsTelemetry(string telemetryPath = null, bool enabled = true)
```

#### Methods

##### TrackVulnerabilityDetection

```csharp
public void TrackVulnerabilityDetection(VulnerabilityMetrics metrics)
```

Tracks vulnerability detection events.

**Example:**
```csharp
telemetry.TrackVulnerabilityDetection(new VulnerabilityMetrics
{
    VulnerabilityType = "SQL Injection",
    Severity = "High",
    FilePath = "UserController.cs",
    LineNumber = 42,
    PatternName = "sql_injection_concat",
    IsConfirmed = true
});
```

##### TrackPerformanceMetrics

```csharp
public void TrackPerformanceMetrics(AnalysisPerformance performance)
```

Tracks analysis performance metrics.

##### TrackPluginUsage

```csharp
public void TrackPluginUsage(PluginUsageMetrics usage)
```

Tracks plugin usage statistics.

##### TrackScanSession

```csharp
public void TrackScanSession(ScanSessionMetrics session)
```

Tracks complete scan session metrics.

##### GenerateAnalyticsReportAsync

```csharp
public async Task<SecurityAnalyticsReport> GenerateAnalyticsReportAsync(
    DateTime? startDate = null, 
    DateTime? endDate = null)
```

Generates comprehensive analytics report for specified period.

##### GetDashboardMetricsAsync

```csharp
public async Task<DashboardMetrics> GetDashboardMetricsAsync()
```

Gets real-time dashboard metrics.

---

## Data Models

### ComprehensiveSecurityReport

Aggregated results from comprehensive security analysis.

#### Properties

```csharp
public string TargetPath { get; set; }
public DateTime AnalysisStartTime { get; set; }
public DateTime AnalysisEndTime { get; set; }
public TimeSpan AnalysisDuration { get; set; }
public SecurityAnalysisOptions Options { get; set; }

// Plugin Results
public SecurityScanResults SecurityScanResults { get; set; }
public AuthenticationAnalysisResults AuthenticationResults { get; set; }
public InputValidationResults InputValidationResults { get; set; }
public VulnerabilityAnalysisResults VulnerabilityResults { get; set; }
public SecureConfigurationResults ConfigurationResults { get; set; }

// Overall Metrics
public int TotalIssuesFound { get; set; }
public int OverallRiskScore { get; set; }
public string OverallRiskLevel { get; set; }
public List<string> OverallRecommendations { get; set; }
public List<string> AnalysisErrors { get; set; }
```

### SecurityScanResults

Results from SecurityScanPlugin analysis.

#### Properties

```csharp
public string ScannedPath { get; set; }
public int FilesScanned { get; set; }
public string SeverityLevel { get; set; }
public List<SecurityIssue> Secrets { get; set; }
public List<SecurityIssue> Vulnerabilities { get; set; }
public List<SecurityIssue> ConfigurationIssues { get; set; }
public List<string> Recommendations { get; set; }
public int OverallRiskScore { get; set; }
public string OverallRisk { get; set; }
```

#### Methods

```csharp
public int GetTotalIssues() => Secrets.Count + Vulnerabilities.Count + ConfigurationIssues.Count;
```

### SecurityIssue

Represents a single security issue.

#### Properties

```csharp
public string Type { get; set; }
public string Severity { get; set; }
public string Description { get; set; }
public string File { get; set; }
public int LineNumber { get; set; }
public string Code { get; set; }
public string Recommendation { get; set; }
```

### AuthenticationAnalysisResults

Results from AuthenticationAnalyzerPlugin analysis.

#### Properties

```csharp
public string AnalyzedPath { get; set; }
public int FilesAnalyzed { get; set; }
public List<AuthenticationIssue> AuthenticationIssues { get; set; }
public List<AuthorizationIssue> AuthorizationIssues { get; set; }
public List<string> GoodPractices { get; set; }
public List<string> SecurityRecommendations { get; set; }
public int ComplianceScore { get; set; }
```

#### Methods

```csharp
public int GetTotalIssues() => AuthenticationIssues.Count + AuthorizationIssues.Count;
```

### InputValidationResults

Results from InputValidationPlugin analysis.

#### Properties

```csharp
public string FilePath { get; set; }
public string FileName { get; set; }
public string FileType { get; set; }
public List<ValidationIssue> ValidationIssues { get; set; }
public List<MissingProtection> MissingProtections { get; set; }
public List<string> GoodPractices { get; set; }
public List<string> Suggestions { get; set; }
public int SecurityScore { get; set; }
```

### VulnerabilityAnalysisResults

Results from VulnerabilityAnalyzerPlugin analysis.

#### Properties

```csharp
public string ProjectPath { get; set; }
public int ProjectFilesAnalyzed { get; set; }
public string VulnerabilitySource { get; set; }
public List<PackageDependency> Dependencies { get; set; }
public List<VulnerablePackage> VulnerablePackages { get; set; }
public List<OutdatedPackage> OutdatedPackages { get; set; }
public List<string> Recommendations { get; set; }
public List<string> AnalysisErrors { get; set; }
public int RiskScore { get; set; }
```

### SecurityAnalysisOptions

Configuration options for orchestrated security analysis.

#### Properties

```csharp
public bool ScanSecrets { get; set; } = true;
public bool ScanVulnerabilities { get; set; } = true;
public bool ScanAuthentication { get; set; } = true;
public bool ScanInputValidation { get; set; } = true;
public bool ScanConfiguration { get; set; } = true;
public bool ScanDependencies { get; set; } = true;
public bool GenerateRecommendations { get; set; } = true;
public string SeverityFilter { get; set; } = "low";
```

### PatternMatchResult

Result from pattern engine analysis.

#### Properties

```csharp
public string PatternName { get; set; }
public Match Match { get; set; }
public string Content { get; set; }
public string FilePath { get; set; }
public PatternCategory Category { get; set; }
public int LineNumber { get; set; }
public string Severity { get; set; }
public string Description { get; set; }
public double Entropy { get; set; }
public string ErrorMessage { get; set; }
```

### VulnerabilityMetrics

Metrics for tracking vulnerability detection.

#### Properties

```csharp
public string VulnerabilityType { get; set; }
public string Severity { get; set; }
public string FilePath { get; set; }
public int LineNumber { get; set; }
public string PatternName { get; set; }
public bool IsConfirmed { get; set; }
public bool IsFalsePositive { get; set; }
```

### AnalysisPerformance

Performance metrics for analysis operations.

#### Properties

```csharp
public string OperationType { get; set; }
public TimeSpan Duration { get; set; }
public int FilesAnalyzed { get; set; }
public long TotalFileSize { get; set; }
public double MemoryUsedMB { get; set; }
public int ParallelismLevel { get; set; }
public double CacheHitRatio { get; set; }
public bool Success { get; set; }
public string ErrorMessage { get; set; }
```

---

## Enumerations

### PatternCategory

Categories for security pattern classification.

```csharp
public enum PatternCategory
{
    All,
    Secrets,
    Vulnerabilities,
    Authentication,
    Configuration,
    Other
}
```

**Usage:**
```csharp
var secretsOnly = await patternEngine.AnalyzeContentAsync(content, PatternCategory.Secrets);
var allPatterns = await patternEngine.AnalyzeContentAsync(content, PatternCategory.All);
```

---

## Error Handling

### Common Exceptions

#### SecurityAnalysisException

Custom exception for security analysis errors.

```csharp
public class SecurityAnalysisException : Exception
{
    public SecurityAnalysisException(string message) : base(message) { }
    public SecurityAnalysisException(string message, Exception innerException) : base(message, innerException) { }
}
```

#### ConfigurationException

Exception for configuration-related errors.

```csharp
public class ConfigurationException : Exception
{
    public ValidationResult ValidationResult { get; }
    
    public ConfigurationException(ValidationResult validationResult) 
        : base($"Configuration validation failed: {string.Join(", ", validationResult.Errors)}")
    {
        ValidationResult = validationResult;
    }
}
```

### Error Handling Best Practices

```csharp
try
{
    var config = SecurityAnalysisConfiguration.LoadFromFile("config.json");
    var validationResult = config.Validate();
    
    if (!validationResult.IsValid)
    {
        throw new ConfigurationException(validationResult);
    }
    
    var orchestrator = new SecurityAnalysisOrchestrator(config);
    var report = await orchestrator.RunFullSecurityAnalysis(targetPath, options);
}
catch (ConfigurationException ex)
{
    Console.WriteLine($"Configuration error: {ex.Message}");
    foreach (var error in ex.ValidationResult.Errors)
    {
        Console.WriteLine($"- {error}");
    }
}
catch (SecurityAnalysisException ex)
{
    Console.WriteLine($"Analysis error: {ex.Message}");
}
catch (TimeoutException ex)
{
    Console.WriteLine($"Analysis timed out: {ex.Message}");
}
```

---

## Performance Considerations

### Parallel Processing

The framework supports configurable parallel processing:

```csharp
var config = SecurityAnalysisConfiguration.GetDefault();
config.Performance.MaxParallelism = Environment.ProcessorCount * 2;
config.Performance.EnableCaching = true;
config.Performance.TimeoutSeconds = 600; // 10 minutes for large codebases
```

### Caching Strategy

Results are cached based on content hash and configuration:

```csharp
// Cache settings
config.Performance.EnableCaching = true;
config.Performance.CacheExpiryMinutes = 60;

// Cache is automatically managed by the pattern engine
var engine = new SecurityPatternEngine(config);
// First analysis - computed and cached
var results1 = await engine.AnalyzeContentAsync(content, PatternCategory.All);
// Second analysis - retrieved from cache
var results2 = await engine.AnalyzeContentAsync(content, PatternCategory.All);
```

### Memory Management

For large codebases, consider streaming analysis:

```csharp
var config = SecurityAnalysisConfiguration.GetDefault();
config.ScanSettings.MaxFileSizeBytes = 5 * 1024 * 1024; // 5MB limit
config.ScanSettings.MaxFilesPerScan = 5000; // Limit files per scan

// Process in batches for very large codebases
var allFiles = Directory.GetFiles(path, "*", SearchOption.AllDirectories);
var batches = allFiles.Chunk(1000); // Process 1000 files at a time

foreach (var batch in batches)
{
    var batchResults = await engine.AnalyzeFilesAsync(batch, PatternCategory.All);
    // Process batch results...
}
```

---

## Integration Examples

### ASP.NET Core Integration

```csharp
// Startup.cs or Program.cs
public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<SecurityAnalysisConfiguration>(provider =>
        SecurityAnalysisConfiguration.LoadFromFile("appsettings.security.json"));
    
    services.AddScoped<SecurityAnalysisOrchestrator>();
    services.AddSingleton<SecurityAnalyticsTelemetry>(provider =>
        new SecurityAnalyticsTelemetry("./telemetry", enabled: true));
}

// Controller
[ApiController]
[Route("api/[controller]")]
public class SecurityController : ControllerBase
{
    private readonly SecurityAnalysisOrchestrator _orchestrator;

    public SecurityController(SecurityAnalysisOrchestrator orchestrator)
    {
        _orchestrator = orchestrator;
    }

    [HttpPost("analyze")]
    public async Task<IActionResult> AnalyzeCode([FromBody] AnalysisRequest request)
    {
        var options = new SecurityAnalysisOptions
        {
            ScanSecrets = request.ScanSecrets,
            ScanVulnerabilities = request.ScanVulnerabilities
        };

        var report = await _orchestrator.RunFullSecurityAnalysis(request.Path, options);
        return Ok(report);
    }
}
```

### Console Application Integration

```csharp
class Program
{
    static async Task Main(string[] args)
    {
        var config = SecurityAnalysisConfiguration.LoadFromFile("security-config.json");
        
        using var telemetry = new SecurityAnalyticsTelemetry("./telemetry");
        var orchestrator = new SecurityAnalysisOrchestrator(config);

        var options = new SecurityAnalysisOptions
        {
            ScanSecrets = true,
            ScanVulnerabilities = true,
            ScanAuthentication = true
        };

        Console.WriteLine("Starting security analysis...");
        var report = await orchestrator.RunFullSecurityAnalysis("./src", options);

        Console.WriteLine($"Analysis completed in {report.AnalysisDuration.TotalSeconds:F2} seconds");
        Console.WriteLine($"Found {report.TotalIssuesFound} issues");
        Console.WriteLine($"Overall risk level: {report.OverallRiskLevel}");

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

---

*This API reference covers version 2.2.0 of the MarketAlly.AIPlugin.Security framework. For the latest updates and examples, visit the [GitHub repository](https://github.com/MarketAlly/MarketAlly.AIPlugin).*