git.stella-ops.org/src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Layer3/ILayer3Analyzer.cs

// SPDX-License-Identifier: BUSL-1.1
// Copyright (c) StellaOps


using StellaOps.Scanner.Reachability.Stack;
using System.Collections.Immutable;

namespace StellaOps.Scanner.Reachability.Layer3;

/// <summary>
/// Layer 3 analyzer: Runtime gating detection.
/// Determines if any feature flag, configuration, or environment condition
/// blocks execution of the vulnerable code path.
/// </summary>
public interface ILayer3Analyzer
{
    /// <summary>
    /// Analyzes whether runtime conditions gate (block) execution of a call path.
    /// </summary>
    /// <param name="path">The call path to analyze for gating conditions</param>
    /// <param name="context">Runtime context (config, env vars, etc.)</param>
    /// <param name="ct">Cancellation token</param>
    /// <returns>Layer 3 gating analysis result</returns>
    Task<ReachabilityLayer3> AnalyzeAsync(
        CallPath path,
        RuntimeContext context,
        CancellationToken ct = default);

    /// <summary>
    /// Analyzes gating for multiple paths and aggregates results.
    /// </summary>
    /// <param name="paths">Call paths to analyze</param>
    /// <param name="context">Runtime context</param>
    /// <param name="ct">Cancellation token</param>
    /// <returns>Aggregated Layer 3 result</returns>
    Task<ReachabilityLayer3> AnalyzeMultipleAsync(
        ImmutableArray<CallPath> paths,
        RuntimeContext context,
        CancellationToken ct = default);
}

/// <summary>
/// Runtime context - configuration and environment affecting execution.
/// </summary>
public sealed record RuntimeContext
{
    /// <summary>Environment variables</summary>
    public ImmutableDictionary<string, string> EnvironmentVariables { get; init; } =
        ImmutableDictionary<string, string>.Empty;

    /// <summary>Configuration values from files/services</summary>
    public ImmutableDictionary<string, ConfigValue> Configuration { get; init; } =
        ImmutableDictionary<string, ConfigValue>.Empty;

    /// <summary>Feature flags and their states</summary>
    public ImmutableDictionary<string, FeatureFlag> FeatureFlags { get; init; } =
        ImmutableDictionary<string, FeatureFlag>.Empty;

    /// <summary>Build/compile-time configuration</summary>
    public BuildConfiguration? BuildConfig { get; init; }

    /// <summary>Platform information</summary>
    public PlatformInfo? Platform { get; init; }

    /// <summary>Process capabilities/privileges</summary>
    public ImmutableArray<string> Capabilities { get; init; } = [];
}

/// <summary>
/// A configuration value.
/// </summary>
public sealed record ConfigValue(
    string Key,
    string? Value,
    ConfigValueSource Source,
    bool IsSecret
);

/// <summary>
/// Source of a configuration value.
/// </summary>
public enum ConfigValueSource
{
    EnvironmentVariable,
    ConfigFile,
    CommandLine,
    RemoteService,
    Default,
    Unknown
}

/// <summary>
/// A feature flag.
/// </summary>
public sealed record FeatureFlag(
    string Name,
    bool IsEnabled,
    FeatureFlagSource Source,
    string? Description
);

/// <summary>
/// Source of a feature flag.
/// </summary>
public enum FeatureFlagSource
{
    CompileTime,
    ConfigFile,
    RemoteService,
    EnvironmentVariable,
    Default,
    Unknown
}

/// <summary>
/// Build/compile-time configuration.
/// </summary>
public sealed record BuildConfiguration
{
    /// <summary>Whether this is a debug build</summary>
    public bool IsDebugBuild { get; init; }

    /// <summary>Defined preprocessor symbols</summary>
    public ImmutableArray<string> DefineConstants { get; init; } = [];

    /// <summary>Target framework</summary>
    public string? TargetFramework { get; init; }

    /// <summary>Build mode (Debug, Release, etc.)</summary>
    public string? BuildMode { get; init; }
}

/// <summary>
/// Platform information.
/// </summary>
public sealed record PlatformInfo
{
    /// <summary>Operating system</summary>
    public required string OS { get; init; }

    /// <summary>OS version</summary>
    public string? OSVersion { get; init; }

    /// <summary>Architecture (x64, arm64, etc.)</summary>
    public required string Architecture { get; init; }

    /// <summary>Whether running in container</summary>
    public bool IsContainer { get; init; }

    /// <summary>Container runtime if applicable</summary>
    public string? ContainerRuntime { get; init; }
}

/// <summary>
/// Input for Layer 3 analysis.
/// </summary>
public sealed record Layer3AnalysisInput
{
    public required CallPath Path { get; init; }
    public required RuntimeContext Context { get; init; }
    public Layer3AnalysisOptions? Options { get; init; }
}

/// <summary>
/// Options for Layer 3 analysis.
/// </summary>
public sealed record Layer3AnalysisOptions
{
    /// <summary>Detect feature flag patterns in code</summary>
    public bool DetectFeatureFlags { get; init; } = true;

    /// <summary>Detect environment variable checks</summary>
    public bool DetectEnvVarChecks { get; init; } = true;

    /// <summary>Detect configuration value checks</summary>
    public bool DetectConfigChecks { get; init; } = true;

    /// <summary>Detect platform checks</summary>
    public bool DetectPlatformChecks { get; init; } = true;

    /// <summary>Detect capability/privilege checks</summary>
    public bool DetectCapabilityChecks { get; init; } = true;

    /// <summary>Feature flag patterns to detect (regex)</summary>
    public ImmutableArray<string> FeatureFlagPatterns { get; init; } = [
        @"FeatureFlags?\.",
        @"IsFeatureEnabled",
        @"Feature\.IsEnabled",
        @"LaunchDarkly",
        @"Unleash",
        @"ConfigCat"
    ];

    /// <summary>Known blocking conditions</summary>
    public ImmutableArray<KnownGatingPattern> KnownPatterns { get; init; } = [];
}

/// <summary>
/// A known gating pattern to detect.
/// </summary>
public sealed record KnownGatingPattern(
    string Pattern,
    GatingType Type,
    string Description,
    bool IsBlockingByDefault
);