risk_evaluation.proto

Risk scoring and assessment — action context, score decomposition, gRPC service

risk_evaluation.proto

Defines the risk evaluation contract between the proxy/API and the scoring engine. Includes the full action context schema, 4-layer score decomposition, and gRPC service definition.

Enums

RiskLevel

enum RiskLevel {
  NONE = 0;      // Score 1-10
  LOW = 1;       // Score 11-30
  MEDIUM = 2;    // Score 31-55
  HIGH = 3;      // Score 56-80
  CRITICAL = 4;  // Score 81-100
}

Context Messages

ActionContext

Full action context submitted for risk evaluation. Supports both canonical nested fields and legacy flat fields.

message ActionContext {
  // Canonical fields
  string action = 1;                       // domain:scope:verb
  AgentInfo agent = 2;
  SessionInfo session = 3;
  TargetInfo target = 4;
  MCPContext mcp_context = 5;
  repeated ClassifiedField data_fields = 6;
  string user_context = 7;
  repeated string conversation_history = 8;
  bytes parameters = 9;                    // JSON-encoded
  map<string, string> metadata = 10;
  repeated string preceding_actions = 11;
  string timestamp = 12;                   // ISO-8601

  // Legacy flat fields (backward compatibility)
  string tool_name = 20;
  string tool_input = 21;
  string resource = 22;
  string user_id = 23;
  repeated string legacy_data_fields = 24;
}

AgentInfo

message AgentInfo {
  string agent_id = 1;
  string agent_type = 2;        // e.g., "code_review", "support"
  string framework = 3;         // e.g., "langchain", "crewai"
  string model = 4;             // e.g., "claude-sonnet-4-5-20250929"
}

SessionInfo

message SessionInfo {
  string session_id = 1;
  string user_id = 2;
  string started_at = 3;        // ISO-8601
}

TargetInfo

message TargetInfo {
  string resource_type = 1;     // e.g., "repository", "database"
  string resource_id = 2;       // e.g., "org/repo-name"
  int32 sensitivity_level = 3;  // 0-4 (public to restricted)
}

MCPContext

message MCPContext {
  string server_name = 1;
  string server_id = 2;
  MCPTransport transport = 3;
  bool is_verified = 4;
  string tool_name = 5;
}

ClassifiedField

message ClassifiedField {
  string field = 1;
  DataClassification classification = 2;  // Optional
}

Score Decomposition

The 4-layer scoring breakdown returned in every risk assessment.

message ScoreDecomposition {
  // Layer 1: Intrinsic action risk (deterministic, 0-100)
  float intrinsic_score = 1;

  // Layer 2: Structural GNN score (learned, 0-100)
  float gnn_score = 2;

  // Layer 3: Policy violation score (forward-chaining, 0-100)
  float policy_score = 3;

  // Layer 4: Temporal anomaly modifier (0.5-2.0)
  float temporal_modifier = 4;

  // Composite
  float raw_weighted = 5;      // Before temporal modifier
  float w1 = 6;                // Intrinsic weight (default 0.15)
  float w2 = 7;                // GNN weight (default 0.45)
  float w3 = 8;                // Policy weight (default 0.40)

  // Confidence
  float gnn_confidence = 9;    // Max class probability
  float overall_confidence = 10;
}

RiskAssessment

Full evaluation result.

message RiskAssessment {
  RiskLevel level = 1;
  float confidence = 2;                     // 0.0-1.0
  string reasoning = 3;
  repeated string mitigations = 4;
  string justification = 5;                 // Max 3 sentences
  int32 score = 6;                          // 0-100
  repeated string violations = 7;
  repeated string compliance_refs = 8;
  string scoring_source = 9;               // "graph_reasoner" | "graph_reasoner+llm"
  repeated string behavioral_flags = 10;
  int32 graph_score = 11;
  int32 llm_score = 12;
  bool llm_fallback = 13;
  ScoreDecomposition score_decomposition = 14;
}

gRPC Service

service RiskEvaluationService {
  // Single event evaluation
  rpc EvaluateRisk(EvaluateRiskRequest) returns (EvaluateRiskResponse);

  // Batch evaluation
  rpc BatchEvaluateRisk(BatchEvaluateRiskRequest) returns (BatchEvaluateRiskResponse);

  // Streaming evaluation
  rpc StreamEvaluateRisk(stream StreamEvaluateRiskRequest)
      returns (stream StreamEvaluateRiskResponse);
}

Request/Response

message EvaluateRiskRequest {
  ActionContext context = 1;
  string customer_id = 2;
}

message EvaluateRiskResponse {
  RiskAssessment assessment = 1;
  string event_id = 2;
}

message BatchEvaluateRiskRequest {
  repeated ActionContext contexts = 1;
  string customer_id = 2;
}

message BatchEvaluateRiskResponse {
  repeated RiskAssessment assessments = 1;
}