rsvcmodel

README

rsvcmodel

rsvcmodel provides a standardized, normalized data contract for cross-cloud security, observability, and finops findings. It serves as one of the core schema library for the rtifact ecosystem.

Usage

This package provides standard Segment and Severity enums alongside the Finding struct. It is designed to be easily serialized to JSON across multiple microservices or CLI tools.

package main

import (
	"encoding/json"
	"fmt"
	
	"github.com/cipherops-io/rsvcmodel"
)

func main() {
	// Create a new normalized finding
	finding := rsvcmodel.NewFinding(
		rsvcmodel.SegmentSecurity,
		"S3 Bucket Public Access",
		"security",
		[]string{"my-public-bucket"},
	)
	
	finding.Severity = rsvcmodel.SeverityCritical
	finding.Provider = "aws"
	
	// Convert to JSON
	bytes, _ := json.MarshalIndent(finding, "", "  ")
	fmt.Println(string(bytes))
}

Data Types

Segments

• SegmentSecurity
• SegmentFinOps
• SegmentObservability

Severities

• SeverityInfo
• SeverityLow
• SeverityMedium
• SeverityHigh
• SeverityCritical

Documentation

Overview

Package rsvcmodel provides a normalized data contract for cloud findings. It defines the core structures used across various cloud providers to represent security, finops, and observability issues in a unified way.

Index

• type AssetKey
• type AssetRow
• type CostSummary
• type Domain
• type DomainStatus
• type Finding
  • func NewFinding(segment Segment, title, category string, items []string) *Finding
• type RunMetadata
  • func StartRunMetadata(tenantID, projectID, discoveryType string, now time.Time) RunMetadata
  • func (m *RunMetadata) Complete(now time.Time)
• type Segment
• type Severity

Types

type AssetKey

type AssetKey string

AssetKey is the canonical key for an asset row in the UI.

const (
	AssetEC2            AssetKey = "ec2"
	AssetS3             AssetKey = "s3"
	AssetVPC            AssetKey = "vpc"
	AssetSecurityGroups AssetKey = "securitygroups"
	AssetIAM            AssetKey = "iam"
	AssetKMS            AssetKey = "kms"
	AssetCloudTrail     AssetKey = "cloudtrail"
	AssetGuardDuty      AssetKey = "guardduty"
	AssetRoute53        AssetKey = "route53"
	AssetEKS            AssetKey = "eks"
	AssetELB            AssetKey = "elb"
	AssetRDS            AssetKey = "rds"
	AssetLambda         AssetKey = "lambda"
	AssetECR            AssetKey = "ecr"
	AssetSecretsManager AssetKey = "secretsmanager"
	AssetAccount        AssetKey = "account"
)

type AssetRow

type AssetRow struct {
	Key           AssetKey                `json:"key"`
	DisplayName   string                  `json:"displayName"`
	Subtitle      string                  `json:"subtitle,omitempty"`
	EntityCounts  map[string]int          `json:"entityCounts,omitempty"`
	Cost          CostSummary             `json:"cost"`
	DomainStatus  map[Domain]DomainStatus `json:"domainStatus,omitempty"`
	Findings      []*Finding              `json:"findings,omitempty"`
	FindingsCount int                     `json:"findingsCount"`
}

AssetRow is the primary unit the UI renders in “Impacted Assets”.

type CostSummary

type CostSummary struct {
	WindowDays     int                `json:"windowDays"`
	TotalUSD       float64            `json:"totalUsd"`
	AnnualizedUSD  float64            `json:"annualizedUsd,omitempty"`
	ByServiceLabel map[string]float64 `json:"byServiceLabel,omitempty"`
}

type Domain

type Domain string

Domain is the UI column grouping for a finding.

const (
	DomainFinOps        Domain = "finops"
	DomainObservability Domain = "observability"
	DomainCompliance    Domain = "compliance"
)

type DomainStatus

type DomainStatus string

const (
	StatusAct  DomainStatus = "Act"
	StatusGood DomainStatus = "Good"
	StatusNA   DomainStatus = "-NA-"
)

type Finding

type Finding struct {
	// ID is a unique identifier for this specific finding output.
	ID string `json:"id,omitempty"`
	// Title is the human-readable name of the check or rule that triggered this finding.
	Title string `json:"title"`
	// Category is the provider-specific sub-category of the finding.
	Category string `json:"category"`
	// Segment maps the finding to a high-level domain (e.g., finops, security).
	Segment Segment `json:"segment"`
	// Severity is the standardized threat or urgency level of the finding.
	Severity Severity `json:"severity,omitempty"`
	// Provider indicates the source of the finding (e.g., aws, gcp, azure).
	Provider string `json:"provider,omitempty"`
	// Summary provides a brief description or context of what the finding means.
	Summary string `json:"summary,omitempty"`
	// Count represents the total number of resources flagged in this finding.
	Count int `json:"count,omitempty"`
	// Items contains human-readable names or pretty identifiers for the flagged resources.
	Items []string `json:"items,omitempty"`
	// ResourceIDs contains the exact native cloud IDs (e.g., ARNs, UUIDs) for the flagged resources.
	ResourceIDs []string `json:"resourceIds,omitempty"`
	// Metadata holds arbitrary key-value pairs for additional context, such as deep links or native properties.
	Metadata map[string]any `json:"metadata,omitempty"`
}

Finding is the normalized output unit across all clouds and segments. It aggregates flagged resources and their metadata for a specific check or rule.

func NewFinding

func NewFinding(segment Segment, title, category string, items []string) *Finding

NewFinding creates a new Finding with the basic required fields initialized. It automatically sets the Count field based on the length of the provided items slice.

type RunMetadata

type RunMetadata struct {
	TenantID        string    `json:"tenant_id"`
	ProjectID       string    `json:"project_id"`
	DiscoveryType   string    `json:"discovery_type"`
	Mode            string    `json:"mode,omitempty"`
	Region          string    `json:"region,omitempty"`
	StartedAt       time.Time `json:"started_at"`
	CompletedAt     time.Time `json:"completed_at,omitempty"`
	DurationSeconds int64     `json:"duration_seconds,omitempty"`
	CompletenessPct int       `json:"completeness_pct,omitempty"`
}

RunMetadata captures top-level information about a discovery execution.

func StartRunMetadata

func StartRunMetadata(tenantID, projectID, discoveryType string, now time.Time) RunMetadata

func (*RunMetadata) Complete

func (m *RunMetadata) Complete(now time.Time)

type Segment

type Segment string

const (
	// SegmentObservability indicates findings related to performance, reliability, and tracing.
	SegmentObservability Segment = "observability"
	// SegmentSecurity indicates findings related to vulnerabilities, access control, and compliance.
	SegmentSecurity Segment = "security"
	// SegmentFinOps indicates findings related to cost optimization and resource waste.
	SegmentFinOps Segment = "finops"
)

type Severity

type Severity string

Severity indicates the urgency and critical nature of a finding.

const (
	// SeverityInfo indicates informational items that require no immediate action.
	SeverityInfo Severity = "info"
	// SeverityLow indicates low-priority issues that can be addressed when time permits.
	SeverityLow Severity = "low"
	// SeverityMedium indicates moderate issues that should be addressed in standard planning cycles.
	SeverityMedium Severity = "medium"
	// SeverityHigh indicates significant issues that require prompt attention.
	SeverityHigh Severity = "high"
	// SeverityCritical indicates severe issues that pose immediate risks and require emergency remediation.
	SeverityCritical Severity = "critical"
)