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

MarketAlly.AIPlugin.Security - API Reference

Table of Contents

• Core Orchestration
• Security Plugins
• Configuration Management
• Pattern Engine
• Telemetry and Analytics
• Data Models
• Enumerations

---

Core Orchestration

SecurityAnalysisOrchestrator

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

Constructor

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

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:

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

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:

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

[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

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

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

[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

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

[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

[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

[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

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

Static Methods

LoadFromFile

public static SecurityAnalysisConfiguration LoadFromFile(string configPath)

Loads configuration from JSON file.

Example:

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

GetDefault

public static SecurityAnalysisConfiguration GetDefault()

Returns default configuration with sensible defaults.

Instance Methods

SaveToFile

public void SaveToFile(string configPath)

Saves current configuration to JSON file.

Validate

public ValidationResult Validate()

Validates configuration settings and returns validation result.

PatternConfiguration

Configuration for custom security patterns and detection rules.

Properties

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

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

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

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

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

public SecurityPatternEngine(SecurityAnalysisConfiguration configuration = null)

Methods

AnalyzeContentAsync

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:

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

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

Analyzes multiple files in parallel for security patterns.

LoadCustomPatterns

public void LoadCustomPatterns(string configPath)

Loads custom patterns from configuration file.

CalculateEntropy

public double CalculateEntropy(string input)

Calculates Shannon entropy for potential secret detection.

DetectHighEntropyStrings

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

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

Methods

TrackVulnerabilityDetection

public void TrackVulnerabilityDetection(VulnerabilityMetrics metrics)

Tracks vulnerability detection events.

Example:

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

TrackPerformanceMetrics

public void TrackPerformanceMetrics(AnalysisPerformance performance)

Tracks analysis performance metrics.

TrackPluginUsage

public void TrackPluginUsage(PluginUsageMetrics usage)

Tracks plugin usage statistics.

TrackScanSession

public void TrackScanSession(ScanSessionMetrics session)

Tracks complete scan session metrics.

GenerateAnalyticsReportAsync

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

Generates comprehensive analytics report for specified period.

GetDashboardMetricsAsync

public async Task<DashboardMetrics> GetDashboardMetricsAsync()

Gets real-time dashboard metrics.

---

Data Models

ComprehensiveSecurityReport

Aggregated results from comprehensive security analysis.

Properties

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

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

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

SecurityIssue

Represents a single security issue.

Properties

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

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

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

InputValidationResults

Results from InputValidationPlugin analysis.

Properties

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

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

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

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

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

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.

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

Usage:

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.

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.

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

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:

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:

// 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:

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

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

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.