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 libraries for the rtifact ecosystem.

Features

• Normalized Findings: A unified structure (Finding) to represent issues across different cloud providers (AWS, GCP, Azure).
• Execution Metadata: Tracking structures (RunMetadata) for discovery and scanning jobs.
• Asset Reporting: Standardized UI models (AssetRow, CostSummary, DomainStatus) to render impacted assets consistently.

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.

Example: Creating a Finding

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

Core Models

• Finding: The normalized output unit across all clouds and segments.
• RunMetadata: Captures top-level information about a discovery execution (e.g., duration, tenant, region).
• AssetRow: The primary unit used to render "Impacted Assets" in the UI, combining findings, cost, and domain status.

Segments

• SegmentSecurity
• SegmentFinOps
• SegmentObservability

Severities

• SeverityInfo
• SeverityLow
• SeverityMedium
• SeverityHigh
• SeverityCritical

Domains

• DomainFinOps
• DomainObservability
• DomainCompliance

Asset Keys

Canonical keys for asset types: AssetEC2, AssetS3, AssetVPC, AssetIAM, etc.

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 represents an Amazon EC2 instance.
	AssetEC2 AssetKey = "ec2"
	// AssetS3 represents an Amazon S3 bucket.
	AssetS3 AssetKey = "s3"
	// AssetVPC represents an Amazon Virtual Private Cloud.
	AssetVPC AssetKey = "vpc"
	// AssetSecurityGroups represents AWS Security Groups.
	AssetSecurityGroups AssetKey = "securitygroups"
	// AssetIAM represents AWS Identity and Access Management resources.
	AssetIAM AssetKey = "iam"
	// AssetKMS represents AWS Key Management Service resources.
	AssetKMS AssetKey = "kms"
	// AssetCloudTrail represents AWS CloudTrail resources.
	AssetCloudTrail AssetKey = "cloudtrail"
	// AssetGuardDuty represents AWS GuardDuty findings or detectors.
	AssetGuardDuty AssetKey = "guardduty"
	// AssetRoute53 represents Amazon Route 53 resources.
	AssetRoute53 AssetKey = "route53"
	// AssetEKS represents Amazon Elastic Kubernetes Service clusters.
	AssetEKS AssetKey = "eks"
	// AssetELB represents Elastic Load Balancers.
	AssetELB AssetKey = "elb"
	// AssetRDS represents Amazon Relational Database Service instances.
	AssetRDS AssetKey = "rds"
	// AssetLambda represents AWS Lambda functions.
	AssetLambda AssetKey = "lambda"
	// AssetECR represents Amazon Elastic Container Registry repositories.
	AssetECR AssetKey = "ecr"
	// AssetSecretsManager represents AWS Secrets Manager secrets.
	AssetSecretsManager AssetKey = "secretsmanager"
	// AssetAccount represents a cloud account (e.g., AWS Account).
	AssetAccount AssetKey = "account"
)

type AssetRow

type AssetRow struct {
	// Key is the unique identifier for the type of asset (e.g., ec2, s3).
	Key AssetKey `json:"key"`
	// DisplayName is the human-readable name of the asset.
	DisplayName string `json:"displayName"`
	// Subtitle provides additional context or identification for the asset.
	Subtitle string `json:"subtitle,omitempty"`
	// EntityCounts holds counts of specific entities associated with the asset.
	EntityCounts map[string]int `json:"entityCounts,omitempty"`
	// Cost contains the cost summary for the asset.
	Cost CostSummary `json:"cost"`
	// DomainStatus maps each domain to its current health or action status.
	DomainStatus map[Domain]DomainStatus `json:"domainStatus,omitempty"`
	// Findings is a list of specific issues or observations associated with the asset.
	Findings []*Finding `json:"findings,omitempty"`
	// FindingsCount is the total number of findings for the asset.
	FindingsCount int `json:"findingsCount"`
}

AssetRow is the primary unit the UI renders in “Impacted Assets”. It provides a consolidated view of an asset's findings, cost, and domain status.

type CostSummary

type CostSummary struct {
	// WindowDays is the number of days over which the cost is calculated.
	WindowDays int `json:"windowDays"`
	// TotalUSD is the total cost incurred during the window in USD.
	TotalUSD float64 `json:"totalUsd"`
	// AnnualizedUSD is the projected annual cost based on the window in USD.
	AnnualizedUSD float64 `json:"annualizedUsd,omitempty"`
	// ByServiceLabel breaks down the total cost by individual service labels.
	ByServiceLabel map[string]float64 `json:"byServiceLabel,omitempty"`
}

CostSummary aggregates the cost information for an asset over a specific time window.

type Domain

type Domain string

Domain is the UI column grouping for a finding.

const (
	// DomainFinOps represents the financial operations and cost optimization domain.
	DomainFinOps Domain = "finops"
	// DomainObservability represents the observability, logging, and monitoring domain.
	DomainObservability Domain = "observability"
	// DomainCompliance represents the compliance, regulatory, and security domain.
	DomainCompliance Domain = "compliance"
)

type DomainStatus

type DomainStatus string

DomainStatus indicates the high-level health or actionability of a domain for an asset.

const (
	// StatusAct indicates that there are active issues requiring attention.
	StatusAct DomainStatus = "Act"
	// StatusGood indicates that the domain is healthy with no significant issues.
	StatusGood DomainStatus = "Good"
	// StatusNA indicates that the domain is not applicable to the asset.
	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

StartRunMetadata initializes a new RunMetadata instance, recording the start time.

func (*RunMetadata) Complete

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

Complete finalizes the execution metadata, setting the completion time and calculating the duration.

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"
)