domain

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 5, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package domain defines the core business types and errors for the Nucleus Security CLI. This package has zero external dependencies.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNotFound indicates the requested resource does not exist.
	ErrNotFound = errors.New("resource not found")

	// ErrUnauthorized indicates invalid or missing authentication credentials.
	ErrUnauthorized = errors.New("unauthorized: invalid or missing API key")

	// ErrForbidden indicates the authenticated user lacks permission.
	ErrForbidden = errors.New("forbidden: insufficient permissions")

	// ErrRateLimited indicates the API rate limit has been exceeded.
	ErrRateLimited = errors.New("rate limited: too many requests")

	// ErrCircuitOpen indicates the circuit breaker is open due to repeated failures.
	ErrCircuitOpen = errors.New("circuit breaker open: API is unavailable")

	// ErrRetryExhausted indicates all retry attempts have been exhausted.
	ErrRetryExhausted = errors.New("all retry attempts exhausted")

	// ErrValidation indicates invalid input data.
	ErrValidation = errors.New("validation error: invalid input")
)

Sentinel errors for domain-level error handling.

Functions

func IsRetryable 

func IsRetryable(err error) bool

IsRetryable returns true if the error is transient and the request can be retried.

Types

type APIError 

type APIError struct {
	StatusCode int
	Message    string
	RequestID  string
}

APIError represents a structured error from the Nucleus API.

func (*APIError) Error 

func (e *APIError) Error() string

type Asset 

type Asset struct {
	ID                     string    `json:"asset_id"`
	Name                   string    `json:"asset_name"`
	Type                   AssetType `json:"asset_type"`
	IPAddress              string    `json:"ip_address"`
	DomainName             string    `json:"domain_name"`
	OperatingSystem        string    `json:"operating_system_name"`
	OperatingSystemVersion string    `json:"operating_system_version"`
	Criticality            string    `json:"asset_criticality"`
	Groups                 []string  `json:"asset_groups"`
	Location               string    `json:"asset_location"`
	Notes                  string    `json:"asset_notes"`
	DataSensitivityScore   string    `json:"asset_data_sensitivity_score"`
	Public                 string    `json:"asset_public"` // "0" or "1"
	Active                 bool      `json:"active"`
	ScanDate               string    `json:"scan_date"`
	RiskScore              string    `json:"asset_base_risk_score"`
	VulnCritical           string    `json:"finding_count_critical"`
	VulnHigh               string    `json:"finding_count_high"`
	VulnMedium             string    `json:"finding_count_medium"`
	VulnLow                string    `json:"finding_count_low"`
}

Asset represents a Nucleus Security asset within a project. Note: the Nucleus API returns most numeric fields as strings.

type AssetGroup 

type AssetGroup struct {
	Name       string `json:"asset_group"`
	AssetCount int    `json:"asset_count"`
}

AssetGroup represents a logical grouping of assets.

type AssetGroupMetrics 

type AssetGroupMetrics struct {
	// Group identifier — the API returns results keyed per-group but the
	// group name is passed as a query parameter, so we track it locally.
	GroupName string `json:"-"`

	RiskScore                      int `json:"risk_score"`
	AssetCount                     int `json:"asset_count"`
	VulnCount                      int `json:"vuln_count"`
	VulnCountCritical              int `json:"vuln_count_critical"`
	VulnCountHigh                  int `json:"vuln_count_high"`
	AvgAgeCritical                 int `json:"avg_age_critical"`
	AvgAgeHigh                     int `json:"avg_age_high"`
	ChurnPct7d                     int `json:"churn_pct_7d"`
	ChurnPctCritical7d             int `json:"churn_pct_critical_7d"`
	ChurnPctHigh7d                 int `json:"churn_pct_high_7d"`
	PastDuePctCritical             int `json:"past_due_pct_critical"`
	PastDuePctHigh                 int `json:"past_due_pct_high"`
	MTTR7d                         int `json:"mttr_7d"`
	MTTRCritical7d                 int `json:"mttr_critical_7d"`
	MTTRHigh7d                     int `json:"mttr_high_7d"`
	MTTRPublishDate7d              int `json:"mttr_publish_date_7d"`
	MTTRPublishDateCritical7d      int `json:"mttr_publish_date_critical_7d"`
	MTTRPublishDateHigh7d          int `json:"mttr_publish_date_high_7d"`
	NucleusExploitedCount          int `json:"nucleus_exploited_count"`
	NucleusZeroDayCount            int `json:"nucleus_zero_day_count"`
	NucleusThreatCount             int `json:"nucleus_threat_count"`
	NucleusExploitedByMalwareCount int `json:"nucleus_exploited_by_malware_count"`
	ComplianceFailPct              int `json:"compliance_fail_pct"`
	CompliancePassPct              int `json:"compliance_pass_pct"`
	AssetExternalPct               int `json:"asset_external_pct"`
}

AssetGroupMetrics represents security metrics for a single asset group from GET /projects/{id}/assets/groups/metrics.

type AssetGroupMetricsOptions 

type AssetGroupMetricsOptions struct {
	// AssetGroups is required — up to 50 group names.
	AssetGroups []string
	// Metrics is optional — specific metric names to include.
	Metrics []string
}

AssetGroupMetricsOptions defines parameters for GET /assets/groups/metrics.

type AssetListOptions 

type AssetListOptions struct {
	Start              *int
	Limit              *int
	IPAddress          string
	AssetName          string
	AssetGroups        string
	AssetType          AssetType
	InactiveAssets     *bool
	UnscannedAssets    *bool
	AssetsWithFindings *bool
}

AssetListOptions defines filters for listing assets.

type AssetType 

type AssetType string

AssetType represents the type of an asset. 

const (
	AssetTypeHost       AssetType = "Host"
	AssetTypeWebApp     AssetType = "Web Application"
	AssetTypeDatabase   AssetType = "Database"
	AssetTypeContainer  AssetType = "Container"
	AssetTypeCloudAsset AssetType = "Cloud Asset"
	AssetTypeRepository AssetType = "Repository"
	AssetTypeMobileApp  AssetType = "Mobile Application"
	AssetTypeNetwork    AssetType = "Network"
	AssetTypeOther      AssetType = "Other"
)

Asset type constants matching the Nucleus Security API.

type Finding 

type Finding struct {
	ScanID            string `json:"scan_id"`
	FindingID         string `json:"finding_id"`
	FindingNumber     string `json:"finding_number"`
	Name              string `json:"finding_name"`
	Severity          string `json:"finding_severity"`
	SeverityAdjusted  string `json:"finding_severity_adjusted"`
	ScanDate          string `json:"scan_date"`
	ScanType          string `json:"scan_type"`
	CVE               string `json:"finding_cve"`
	Result            string `json:"finding_result"`
	AssetID           string `json:"asset_id"`
	AssetName         string `json:"asset_name"`
	IPAddress         string `json:"ip_address"`
	Discovered        string `json:"finding_discovered"`
	Exploitable       string `json:"finding_exploitable"`
	Status            string `json:"justification_status_name"`
	JustificationText string `json:"justification_text"`
	DueDate           string `json:"due_date"`
	Description       string `json:"finding_description"`
	Recommendation    string `json:"finding_recommendation"`
	Port              string `json:"finding_port"`
	Path              string `json:"finding_path"`
	Package           string `json:"finding_package"`
	PackageVersion    string `json:"finding_package_version"`
	// EPSSScore uses FlexFloat because the API returns it as float (0.01), int (0), or empty string ("").
	EPSSScore                 FlexFloat `json:"epss_score"`
	JustificationIsMitigating FlexInt   `json:"justification_is_mitigating"`
	MandiantExploited         string    `json:"mandiant_exploit_in_the_wild"`
	MandiantRiskRating        string    `json:"mandiant_risk_rating"`
}

Finding represents a vulnerability finding returned by the search endpoint. All IDs and numeric values are returned as strings by the API.

type FindingListOptions 

type FindingListOptions struct {
	Start    *int
	Limit    *int
	Severity Severity
	Status   FindingStatus
}

FindingListOptions defines filters for listing findings.

type FindingMetrics 

type FindingMetrics struct {
	MetricDate         string `json:"metric_date"`
	Discovered30       int    `json:"projectmetricsdiscovered30"`
	Remediated30       int    `json:"projectmetricsremediated30"`
	RemediationDays30  int    `json:"projectmetricsremdays30"`
	Discovered90       int    `json:"projectmetricsdiscovered90"`
	Remediated90       int    `json:"projectmetricsremediated90"`
	RemediationDays90  int    `json:"projectmetricsremdays90"`
	Discovered180      int    `json:"projectmetricsdiscovered180"`
	Remediated180      int    `json:"projectmetricsremediated180"`
	RemediationDays180 int    `json:"projectmetricsremdays180"`
	Success            bool   `json:"success"`
}

FindingMetrics represents aggregated vulnerability discovery/remediation metrics over 30, 90, and 180-day rolling windows from GET /projects/{id}/findings/metrics.

type FindingOverview 

type FindingOverview struct {
	CritHigh           string `json:"finding_count_crithigh"`
	CVECount           string `json:"finding_count_cve"`
	IAVACount          string `json:"finding_count_iava"`
	ExploitableCount   string `json:"finding_count_exploitable"`
	Critical           string `json:"finding_count_critical"`
	High               string `json:"finding_count_high"`
	Medium             string `json:"finding_count_medium"`
	Low                string `json:"finding_count_low"`
	VulnerabilityScore int    `json:"finding_vulnerability_score"`
}

FindingOverview represents the summary returned by GET /projects/{id}/findings/overview. Most counts are returned as strings by the API.

type FindingSearch 

type FindingSearch struct {
	AssetID             *int     `json:"asset_id,omitempty"`
	AssetName           string   `json:"asset_name,omitempty"`
	IPAddress           string   `json:"ip_address,omitempty"`
	AssetGroups         []string `json:"asset_groups,omitempty"`
	ScanType            string   `json:"scan_type,omitempty"`
	FindingCVE          string   `json:"finding_cve,omitempty"`
	FindingName         string   `json:"finding_name,omitempty"`
	FindingNumber       string   `json:"finding_number,omitempty"`
	FindingSeverity     string   `json:"finding_severity,omitempty"`
	FindingExploitable  string   `json:"finding_exploitable,omitempty"`
	JustificationStatus []string `json:"justification_status,omitempty"`
	IsActive            *bool    `json:"is_active,omitempty"`
	Team                string   `json:"team,omitempty"`
	IncludeTotalCount   bool     `json:"include_total_count,omitempty"`
}

FindingSearch defines the search criteria for POST /projects/{id}/findings/search. All string fields accept wildcards (* or %) and most can be arrays.

type FindingStatus 

type FindingStatus string

FindingStatus represents the current status of a finding. 

const (
	FindingStatusActive                 FindingStatus = "Active"
	FindingStatusInProgress             FindingStatus = "In Progress"
	FindingStatusFixed                  FindingStatus = "Fixed"
	FindingStatusAcceptedRisk           FindingStatus = "Accepted Risk"
	FindingStatusFalsePositive          FindingStatus = "False Positive"
	FindingStatusExceptionRequested     FindingStatus = "Exception Requested"
	FindingStatusExceptionGranted       FindingStatus = "Exception Granted"
	FindingStatusDuplicate              FindingStatus = "Duplicate"
	FindingStatusManuallyMitigated      FindingStatus = "Manually Mitigated"
	FindingStatusScanMitigated          FindingStatus = "Scan Mitigated"
	FindingStatusWaitingForVerification FindingStatus = "Waiting For Verification"
	FindingStatusWaitingForThirdParty   FindingStatus = "Waiting For Third Party"
)

FindingStatus constants for finding status values.

type FindingTrend 

type FindingTrend struct {
	DataPoints []FindingTrendPoint `json:"vulnDiscoveredBar"`
}

FindingTrend represents trend data returned by GET /projects/{id}/findings/trend.

type FindingTrendPoint 

type FindingTrendPoint struct {
	Date          string `json:"vuln_date_short"`
	Critical      string `json:"Critical"`
	High          string `json:"High"`
	Medium        string `json:"Medium"`
	Low           string `json:"Low"`
	Informational string `json:"Informational"`
}

FindingTrendPoint represents a single data point in the vulnDiscoveredBar trend. All severity counts are returned as strings by the API.

type FlexFloat 

type FlexFloat struct {
	Value float64
	Set   bool
}

FlexFloat is a custom JSON type for the EPSS score field. The Nucleus API returns it inconsistently as float (0.01), int (0), or empty string (""). FlexFloat unmarshals a JSON value that may be a float, int, or empty string. This is needed because the Nucleus API returns epss_score inconsistently.

func (FlexFloat) MarshalJSON 

func (f FlexFloat) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for FlexFloat.

func (FlexFloat) String 

func (f FlexFloat) String() string

func (*FlexFloat) UnmarshalJSON 

func (f *FlexFloat) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for FlexFloat.

type FlexInt 

type FlexInt struct {
	Value int
	Set   bool
}

FlexInt is a custom JSON type for integer fields that the Nucleus API returns inconsistently as numbers, numeric strings, or empty strings.

func (FlexInt) MarshalJSON 

func (f FlexInt) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for FlexInt.

func (*FlexInt) UnmarshalJSON 

func (f *FlexInt) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for FlexInt.

type MitigatedFinding 

type MitigatedFinding struct {
	FindingNumber   string   `json:"finding_number"`
	Name            string   `json:"finding_name"`
	Severity        string   `json:"finding_severity"`
	Severities      []string `json:"finding_severities"`
	Discovered      string   `json:"finding_discovered"`
	Exploitable     string   `json:"finding_exploitable"`
	ScanType        string   `json:"scan_type"`
	ManualMitigated string   `json:"manual_mitigated"`
	RemediatedDate  string   `json:"finding_remediated_date"`
	RemediationDays string   `json:"finding_remediation_days"`
	TotalOpen       string   `json:"total_open"`
	TotalManual     string   `json:"total_manual"`
	TotalMitigated  string   `json:"total_mitigated"`
}

MitigatedFinding represents a mitigated finding returned by the mitigated endpoint.

type MitigatedOptions 

type MitigatedOptions struct {
	Start     *int
	Limit     *int
	StartDate string
}

MitigatedOptions defines filters for getting mitigated findings.

type Project 

type Project struct {
	ID          string    `json:"project_id"`
	Name        string    `json:"project_name"`
	Description string    `json:"project_description"`
	Org         string    `json:"project_org"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

Project represents a Nucleus Security project. Note: the API returns project_id as a string (e.g. "3").

type RiskScore 

type RiskScore struct {
	ProjectID string `json:"project_id"`
	Score     int    `json:"score"`
}

RiskScore represents the risk score for a project.

type Scan 

type Scan struct {
	ID          string `json:"scan_id"`
	Name        string `json:"scan_name"`
	Description string `json:"scan_description"`
	Type        string `json:"scan_type"`
	Status      string `json:"scan_status"`
	ScanDate    string `json:"scan_date"`
	AssetCount  string `json:"asset_count"`
}

Scan represents a vulnerability scan in Nucleus Security. Note: the API returns scan_id as a string (e.g. "2020927").

type ScanResult 

type ScanResult struct {
	ScanID  string `json:"scan_id"`
	Message string `json:"message"`
}

ScanResult represents the result of uploading a scan.

type ScanUploadOptions 

type ScanUploadOptions struct {
	Description string
	Type        string
}

ScanUploadOptions defines optional parameters for uploading a scan.

type Severity 

type Severity string

Severity represents the severity level of a finding. 

const (
	SeverityCritical Severity = "Critical"
	SeverityHigh     Severity = "High"
	SeverityMedium   Severity = "Medium"
	SeverityLow      Severity = "Low"
	SeverityInfo     Severity = "Info"
)

Severity constants for finding severity levels.

type TrendOptions 

type TrendOptions struct {
	StartDate   string
	EndDate     string
	AssetGroups []string
}

TrendOptions defines filters for getting finding trends.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.