vet/api/json_report_spec.proto

syntax = "proto3";

option go_package = "github.com/safedep/vet/gen/jsonreportspec";

import "models.proto";
import "insights_models.proto";
import "violations.proto";

enum RemediationAdviceType {
  UnknownAdviceType = 0;
  UpgradePackage = 1;
  AlternatePopularPackage = 2;
  AlternateSecurePackage = 3;
}

message RemediationAdvice {
  RemediationAdviceType type = 1;
  Package package = 2;
  string target_package_name = 3;
  string target_package_version = 4;
  string target_alternate_package_name = 5;
  string target_alternate_package_version = 6;
}

// We are introducing the concept of Threat as a reporting entity so
// that we can report threats like lockfile poisoning using a standard schema.
// But why do we need threats? Why not just use vet's paradigm of policy over
// enriched packages? The reason is, there are threats that are applicable in
// an environment, against a manifest or other entities or even group of entities.
// Hence it is required to introduce a threat as a reporting entity so that external
// tools can consume vet's reports and take actions based on the threats.
message ReportThreat {
  enum Confidence {
    UnknownConfidence = 0;

    High = 1;
    Medium = 2;
    Low = 3;
  }

  enum Source {
    UnknownSource = 0;

    CWE = 1;
  }

  enum SubjectType {
    UnknownSubject = 0;

    Package = 1;
    Manifest = 2;
  }

  enum ReportThreatId {
    UnknownReportThreatId = 0;

    LockfilePoisoning = 1;
  }

  ReportThreatId id = 1;
  string instanceId = 2; // Unique threat instance ID per (ID, SubjectType, Subject) tuple
  string message = 3;
  SubjectType subject_type = 4;
  string subject = 5;
  Confidence confidence = 6;
  Source source = 7;
  string source_id = 8;
}

message PackageManifestReport {
  string id = 1;
  Ecosystem ecosystem = 2;
  string path = 3;
  repeated ReportThreat threats = 4;
  string display_path = 5;
  string source_type = 6;
  string namespace = 7;
}

// PackageReport represents the first class entity for which we have different type
// of reporting information
message PackageReport {
  Package package = 1;

  // The manifests identified by IDs where this package belongs to
  repeated string manifests = 2;

  repeated Violation violations = 3;
  repeated RemediationAdvice advices = 4;

  // Insights data
  repeated InsightVulnerability vulnerabilities = 5;
  repeated InsightLicenseInfo licenses = 6;
  repeated InsightProjectInfo projects = 8;

  // Threats
  repeated ReportThreat threats = 7;
}

message ReportMeta {
  string tool_name = 1;
  string tool_version = 2;
  string created_at = 3;
}

message Report {
  ReportMeta meta = 1;

  repeated PackageManifestReport manifests = 2;
  repeated PackageReport packages = 3;
}