syntax = "proto3";

package charybdis.core;

import "google/protobuf/timestamp.proto";

// FindingMetadata represents identifying information for a security finding
message FindingMetadata {
  // Required: Title of the finding (e.g., "SQL Injection in login handler")
  string title = 1;

  // Optional: Namespace (default: "default")
  string namespace = 2;

  // Optional: Detailed description of the vulnerability
  string description = 3;

  // Optional: Labels for categorization and filtering
  map<string, string> labels = 4;

  // Optional: Tags (e.g., "owasp-top-10", "cwe-89")
  repeated string tags = 5;
}

// FindingSpec contains the security-relevant data for a finding
message FindingSpec {
  // Required: Reference to the component this finding belongs to (entity name or UUID)
  string component_ref = 1;

  // Required: Lifecycle/environment scope (e.g., "production", "integration", "development")
  string lifecycle = 2;

  // Required: Severity level
  Severity severity = 3;

  // Required: Current state of the finding
  FindingState state = 4;

  // Required: Scanner that produced this finding
  string scanner = 5;

  // Required: Rule/check identifier from the scanner (e.g., "CWE-89", "RUSTSEC-2024-001")
  string rule_id = 6;

  // Computed: Fingerprint for deduplication (set by reconciliation engine)
  string fingerprint = 7;

  // Optional: File path where the vulnerability was found
  string file_path = 8;

  // Optional: Line number in the file
  uint32 line_start = 9;

  // Optional: End line number (for multi-line findings)
  uint32 line_end = 10;

  // Optional: CWE identifier (e.g., "CWE-89")
  string cwe = 11;

  // Optional: CVE identifier (e.g., "CVE-2024-1234")
  string cve = 12;

  // Optional: CVSS score (0.0 - 10.0)
  float cvss_score = 13;

  // Optional: Affected package/dependency name
  string package_name = 14;

  // Optional: Affected package version
  string package_version = 15;

  // Optional: Fixed version (if known)
  string fixed_version = 16;

  // Optional: URL to more details (advisory, documentation)
  string details_url = 17;

  // Timestamp of first detection
  google.protobuf.Timestamp first_seen = 18;

  // Timestamp of most recent detection
  google.protobuf.Timestamp last_seen = 19;

  // Optional: Timestamp when the finding was resolved
  google.protobuf.Timestamp resolved_at = 20;

  // Optional: Scan identifier that produced this finding (for tracing back to CI run)
  string scan_id = 21;
}

// Severity levels aligned with CVSS qualitative ratings
enum Severity {
  SEVERITY_UNSPECIFIED = 0;
  SEVERITY_INFO = 1;
  SEVERITY_LOW = 2;
  SEVERITY_MEDIUM = 3;
  SEVERITY_HIGH = 4;
  SEVERITY_CRITICAL = 5;
}

// Finding lifecycle states
enum FindingState {
  FINDING_STATE_UNSPECIFIED = 0;
  // Active: currently detected by scanner
  FINDING_STATE_ACTIVE = 1;
  // Resolved: no longer detected by scanner (auto-closed on reimport)
  FINDING_STATE_RESOLVED = 2;
  // Accepted: risk accepted by human decision
  FINDING_STATE_ACCEPTED = 3;
  // False positive: marked as not a real issue
  FINDING_STATE_FALSE_POSITIVE = 4;
  // Reopened: was resolved but detected again
  FINDING_STATE_REOPENED = 5;
}