git.stella-ops.org/src/__Libraries/StellaOps.Spdx3/Model/Security/Spdx3Vulnerability.cs

// <copyright file="Spdx3Vulnerability.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under the AGPL-3.0-or-later.
// </copyright>

using System.Collections.Immutable;
using System.ComponentModel.DataAnnotations;
using System.Text.Json.Serialization;

namespace StellaOps.Spdx3.Model.Security;

/// <summary>
/// SPDX 3.0.1 Vulnerability element representing a security vulnerability.
/// Sprint: SPRINT_20260107_004_004 Task SP-001
/// </summary>
public sealed record Spdx3Vulnerability : Spdx3Element
{
    /// <summary>
    /// Gets the JSON-LD type for Vulnerability elements.
    /// </summary>
    public const string TypeName = "security_Vulnerability";

    /// <summary>
    /// Gets or sets the published date of the vulnerability.
    /// </summary>
    [JsonPropertyName("security_publishedTime")]
    public DateTimeOffset? PublishedTime { get; init; }

    /// <summary>
    /// Gets or sets the last modified date of the vulnerability.
    /// </summary>
    [JsonPropertyName("security_modifiedTime")]
    public DateTimeOffset? ModifiedTime { get; init; }

    /// <summary>
    /// Gets or sets the withdrawn date (if applicable).
    /// </summary>
    [JsonPropertyName("security_withdrawnTime")]
    public DateTimeOffset? WithdrawnTime { get; init; }

    /// <summary>
    /// Gets or sets external references (CVE, GHSA, etc.).
    /// </summary>
    [JsonPropertyName("externalRef")]
    public ImmutableArray<Spdx3ExternalRef> ExternalRefs { get; init; } = ImmutableArray<Spdx3ExternalRef>.Empty;

    /// <summary>
    /// Gets or sets external identifiers (CVE ID, etc.).
    /// </summary>
    [JsonPropertyName("externalIdentifier")]
    public ImmutableArray<Spdx3ExternalIdentifier> ExternalIdentifiers { get; init; } = ImmutableArray<Spdx3ExternalIdentifier>.Empty;
}

/// <summary>
/// Base class for SPDX 3.0.1 vulnerability assessment relationships.
/// Sprint: SPRINT_20260107_004_004 Task SP-001
/// </summary>
public abstract record Spdx3VulnAssessmentRelationship : Spdx3Relationship
{
    /// <summary>
    /// Gets or sets the element being assessed (Package, File, etc.).
    /// </summary>
    [Required]
    [JsonPropertyName("security_assessedElement")]
    public required string AssessedElement { get; init; }

    /// <summary>
    /// Gets or sets the agent that supplied this assessment.
    /// </summary>
    [JsonPropertyName("security_suppliedBy")]
    public string? SuppliedBy { get; init; }

    /// <summary>
    /// Gets or sets when the assessment was published.
    /// </summary>
    [JsonPropertyName("security_publishedTime")]
    public DateTimeOffset? PublishedTime { get; init; }

    /// <summary>
    /// Gets or sets when the assessment was last modified.
    /// </summary>
    [JsonPropertyName("security_modifiedTime")]
    public DateTimeOffset? ModifiedTime { get; init; }

    /// <summary>
    /// Gets or sets when the assessment was withdrawn (if applicable).
    /// </summary>
    [JsonPropertyName("security_withdrawnTime")]
    public DateTimeOffset? WithdrawnTime { get; init; }
}

/// <summary>
/// SPDX 3.0.1 VEX Affected vulnerability assessment relationship.
/// Sprint: SPRINT_20260107_004_004 Task SP-001
/// </summary>
public sealed record Spdx3VexAffectedVulnAssessmentRelationship : Spdx3VulnAssessmentRelationship
{
    /// <summary>
    /// Gets the JSON-LD type for VEX Affected assessment.
    /// </summary>
    public const string TypeName = "security_VexAffectedVulnAssessmentRelationship";

    /// <summary>
    /// Gets or sets the VEX version.
    /// </summary>
    [JsonPropertyName("security_vexVersion")]
    public string? VexVersion { get; init; }

    /// <summary>
    /// Gets or sets the status notes.
    /// </summary>
    [JsonPropertyName("security_statusNotes")]
    public string? StatusNotes { get; init; }

    /// <summary>
    /// Gets or sets the action statement for remediation.
    /// </summary>
    [JsonPropertyName("security_actionStatement")]
    public string? ActionStatement { get; init; }

    /// <summary>
    /// Gets or sets the deadline for taking action.
    /// </summary>
    [JsonPropertyName("security_actionStatementTime")]
    public DateTimeOffset? ActionStatementTime { get; init; }
}

/// <summary>
/// SPDX 3.0.1 VEX Not Affected vulnerability assessment relationship.
/// Sprint: SPRINT_20260107_004_004 Task SP-001
/// </summary>
public sealed record Spdx3VexNotAffectedVulnAssessmentRelationship : Spdx3VulnAssessmentRelationship
{
    /// <summary>
    /// Gets the JSON-LD type for VEX Not Affected assessment.
    /// </summary>
    public const string TypeName = "security_VexNotAffectedVulnAssessmentRelationship";

    /// <summary>
    /// Gets or sets the VEX version.
    /// </summary>
    [JsonPropertyName("security_vexVersion")]
    public string? VexVersion { get; init; }

    /// <summary>
    /// Gets or sets the status notes.
    /// </summary>
    [JsonPropertyName("security_statusNotes")]
    public string? StatusNotes { get; init; }

    /// <summary>
    /// Gets or sets the justification for not affected status.
    /// </summary>
    [JsonPropertyName("security_justificationType")]
    public Spdx3VexJustificationType? JustificationType { get; init; }

    /// <summary>
    /// Gets or sets the impact statement.
    /// </summary>
    [JsonPropertyName("security_impactStatement")]
    public string? ImpactStatement { get; init; }

    /// <summary>
    /// Gets or sets the impact statement time.
    /// </summary>
    [JsonPropertyName("security_impactStatementTime")]
    public DateTimeOffset? ImpactStatementTime { get; init; }
}

/// <summary>
/// SPDX 3.0.1 VEX Fixed vulnerability assessment relationship.
/// Sprint: SPRINT_20260107_004_004 Task SP-001
/// </summary>
public sealed record Spdx3VexFixedVulnAssessmentRelationship : Spdx3VulnAssessmentRelationship
{
    /// <summary>
    /// Gets the JSON-LD type for VEX Fixed assessment.
    /// </summary>
    public const string TypeName = "security_VexFixedVulnAssessmentRelationship";

    /// <summary>
    /// Gets or sets the VEX version.
    /// </summary>
    [JsonPropertyName("security_vexVersion")]
    public string? VexVersion { get; init; }

    /// <summary>
    /// Gets or sets the status notes.
    /// </summary>
    [JsonPropertyName("security_statusNotes")]
    public string? StatusNotes { get; init; }
}

/// <summary>
/// SPDX 3.0.1 VEX Under Investigation vulnerability assessment relationship.
/// Sprint: SPRINT_20260107_004_004 Task SP-001
/// </summary>
public sealed record Spdx3VexUnderInvestigationVulnAssessmentRelationship : Spdx3VulnAssessmentRelationship
{
    /// <summary>
    /// Gets the JSON-LD type for VEX Under Investigation assessment.
    /// </summary>
    public const string TypeName = "security_VexUnderInvestigationVulnAssessmentRelationship";

    /// <summary>
    /// Gets or sets the VEX version.
    /// </summary>
    [JsonPropertyName("security_vexVersion")]
    public string? VexVersion { get; init; }

    /// <summary>
    /// Gets or sets the status notes.
    /// </summary>
    [JsonPropertyName("security_statusNotes")]
    public string? StatusNotes { get; init; }
}

/// <summary>
/// SPDX 3.0.1 VEX justification types (from spec).
/// Sprint: SPRINT_20260107_004_004 Task SP-001
/// </summary>
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum Spdx3VexJustificationType
{
    /// <summary>Component is not present.</summary>
    ComponentNotPresent,

    /// <summary>Vulnerable code is not present.</summary>
    VulnerableCodeNotPresent,

    /// <summary>Vulnerable code cannot be controlled by adversary.</summary>
    VulnerableCodeCannotBeControlledByAdversary,

    /// <summary>Vulnerable code is not in execute path.</summary>
    VulnerableCodeNotInExecutePath,

    /// <summary>Inline mitigations already exist.</summary>
    InlineMitigationsAlreadyExist
}