nucleus

package
v0.3.1 Latest Latest
Warning

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

 Go to latest Published: May 6, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package nucleus implements the Nucleus Security API client. It provides HTTP-based implementations of the service interfaces with built-in retry logic and circuit breaker support.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CircuitBreaker 

type CircuitBreaker struct {
	// contains filtered or unexported fields
}

CircuitBreaker implements the circuit breaker pattern to prevent cascading failures.

func NewCircuitBreaker 

func NewCircuitBreaker(cfg *CircuitBreakerConfig) *CircuitBreaker

NewCircuitBreaker creates a new circuit breaker with the given configuration.

func (*CircuitBreaker) Allow 

func (cb *CircuitBreaker) Allow() error

Allow checks if a request is allowed through the circuit breaker. Returns nil if allowed, or domain.ErrCircuitOpen if the circuit is open.

func (*CircuitBreaker) RecordFailure 

func (cb *CircuitBreaker) RecordFailure()

RecordFailure records a failed request.

func (*CircuitBreaker) RecordSuccess 

func (cb *CircuitBreaker) RecordSuccess()

RecordSuccess records a successful request.

func (*CircuitBreaker) State 

func (cb *CircuitBreaker) State() CircuitState

State returns the current state of the circuit breaker.

type CircuitBreakerConfig 

type CircuitBreakerConfig struct {
	// FailureThreshold is the number of consecutive failures before the circuit opens.
	FailureThreshold int

	// SuccessThreshold is the number of consecutive successes in half-open state
	// needed to close the circuit.
	SuccessThreshold int

	// OpenTimeout is the duration the circuit stays open before transitioning to half-open.
	OpenTimeout time.Duration
}

CircuitBreakerConfig defines the configuration for the circuit breaker.

func DefaultCircuitBreakerConfig 

func DefaultCircuitBreakerConfig() *CircuitBreakerConfig

DefaultCircuitBreakerConfig returns the default circuit breaker configuration.

type CircuitState 

type CircuitState int

CircuitState represents the state of the circuit breaker. 

const (
	// CircuitClosed is the normal operating state — requests pass through.
	CircuitClosed CircuitState = iota

	// CircuitOpen is the tripped state — requests fail immediately.
	CircuitOpen

	// CircuitHalfOpen is the probing state — one request allowed to test recovery.
	CircuitHalfOpen
)

func (CircuitState) String 

func (s CircuitState) String() string

String returns the string representation of the circuit state.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the Nucleus Security API client. It implements all service interfaces (ProjectService, AssetService, etc.) and handles HTTP communication, authentication, and resilience.

func NewClient 

func NewClient(baseURL, apiKey string, opts ...TransportOption) *Client

NewClient creates a new Nucleus Security API client.

func (*Client) BulkUpdateFindings 

func (c *Client) BulkUpdateFindings(ctx context.Context, projectID string, updates []service.UpdateFindingInput) error

BulkUpdateFindings modifies multiple findings at once.

func (*Client) CreateAsset 

func (c *Client) CreateAsset(ctx context.Context, projectID string, input *service.CreateAssetInput) (*domain.Asset, error)

CreateAsset creates a new asset in the project.

func (*Client) CreateAssetGroup 

func (c *Client) CreateAssetGroup(ctx context.Context, projectID, name string) error

CreateAssetGroup creates a new asset group.

func (*Client) DeleteAsset 

func (c *Client) DeleteAsset(ctx context.Context, projectID, assetID string) error

DeleteAsset removes an asset from the project.

func (*Client) DeleteAssetGroup 

func (c *Client) DeleteAssetGroup(ctx context.Context, projectID, name string) error

DeleteAssetGroup removes an asset group by name. The API expects the group name as a query parameter: DELETE /assets/groups?asset_group=<name>

func (*Client) Get 

func (c *Client) Get(ctx context.Context, projectID string) (*domain.Project, error)

Get returns a specific project by ID.

func (*Client) GetAsset 

func (c *Client) GetAsset(ctx context.Context, projectID, assetID string) (*domain.Asset, error)

GetAsset returns a specific asset by ID.

func (*Client) GetAssetGroupMetrics 

func (c *Client) GetAssetGroupMetrics(ctx context.Context, projectID string, opts *domain.AssetGroupMetricsOptions) ([]domain.AssetGroupMetrics, error)

GetAssetGroupMetrics retrieves security metrics for one or more asset groups. Corresponds to GET /projects/{project_id}/assets/groups/metrics. opts.AssetGroups is required (up to 50 groups); opts.Metrics is optional.

func (*Client) GetFinding 

func (c *Client) GetFinding(ctx context.Context, projectID, findingNumber string) (*domain.Finding, error)

GetFinding returns detailed information about a specific finding.

func (*Client) GetFindingMetrics 

func (c *Client) GetFindingMetrics(ctx context.Context, projectID string) (*domain.FindingMetrics, error)

GetFindingMetrics retrieves aggregated discovery/remediation metrics for a project. Corresponds to GET /projects/{project_id}/findings/metrics.

func (*Client) GetFindingOverview 

func (c *Client) GetFindingOverview(ctx context.Context, projectID string) (*domain.FindingOverview, error)

GetFindingOverview returns a summary overview of findings.

func (*Client) GetFindingTrend 

func (c *Client) GetFindingTrend(ctx context.Context, projectID string, opts *domain.TrendOptions) (*domain.FindingTrend, error)

GetFindingTrend returns trend data for findings over time.

func (*Client) GetFrameworks 

func (c *Client) GetFrameworks(ctx context.Context, projectID string) ([]string, error)

GetFrameworks returns compliance frameworks associated with findings.

func (*Client) GetMitigatedFindings 

func (c *Client) GetMitigatedFindings(ctx context.Context, projectID string, opts *domain.MitigatedOptions) ([]domain.MitigatedFinding, error)

GetMitigatedFindings returns findings that have been mitigated.

func (*Client) GetRiskScore 

func (c *Client) GetRiskScore(ctx context.Context, projectID string) (*domain.RiskScore, error)

GetRiskScore returns the risk score for a project.

func (*Client) List 

func (c *Client) List(ctx context.Context) ([]domain.Project, error)

List returns all projects accessible to the authenticated user.

func (*Client) ListAssetGroups 

func (c *Client) ListAssetGroups(ctx context.Context, projectID string) ([]domain.AssetGroup, error)

ListAssetGroups returns all asset groups in a project.

func (*Client) ListAssets 

func (c *Client) ListAssets(ctx context.Context, projectID string, opts *domain.AssetListOptions) ([]domain.Asset, error)

ListAssets returns assets matching the given options.

func (*Client) ListFindings 

func (c *Client) ListFindings(ctx context.Context, projectID string, opts *domain.FindingListOptions) ([]domain.Finding, error)

ListFindings returns findings matching the given options.

func (*Client) ListScans 

func (c *Client) ListScans(ctx context.Context, projectID string, start, limit int) ([]domain.Scan, error)

ListScans returns scans for a given project with optional pagination. Pagination is controlled via start/limit query parameters (API default: 1, max: 100).

func (*Client) ListTeams added in v0.3.1 

func (c *Client) ListTeams(ctx context.Context, projectID string) ([]domain.Team, error)

ListTeams returns all teams in a project, excluding the default no-access team.

func (*Client) SearchFindings 

func (c *Client) SearchFindings(ctx context.Context, projectID string, search *domain.FindingSearch, start, limit int) ([]domain.Finding, error)

SearchFindings performs a filtered search for findings using the FindingsSearch criteria. The search body is posted directly as a flat JSON object (no wrapper). Pagination is controlled via start/limit query parameters (API default: 100, max: 1000).

func (*Client) UpdateAsset 

func (c *Client) UpdateAsset(ctx context.Context, projectID, assetID string, input *service.UpdateAssetInput) (*domain.Asset, error)

UpdateAsset modifies an existing asset.

func (*Client) UpdateFinding 

func (c *Client) UpdateFinding(ctx context.Context, projectID string, input *service.UpdateFindingInput) error

UpdateFinding modifies a finding's status, severity, or other attributes.

func (*Client) UploadScan 

func (c *Client) UploadScan(ctx context.Context, projectID, filePath string, opts *domain.ScanUploadOptions) (*domain.ScanResult, error)

UploadScan uploads a scan file to a project via multipart/form-data.

type ResilientTransport 

type ResilientTransport struct {
	// contains filtered or unexported fields
}

ResilientTransport wraps an http.RoundTripper with authentication, retry logic, and circuit breaker support.

func NewResilientTransport 

func NewResilientTransport(base http.RoundTripper, apiKey string, retryCfg *RetryConfig, cbCfg *CircuitBreakerConfig) *ResilientTransport

NewResilientTransport creates a transport with auth, retry, and circuit breaker.

func (*ResilientTransport) RoundTrip 

func (t *ResilientTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper with resilience patterns.

type RetryConfig 

type RetryConfig struct {
	// MaxRetries is the maximum number of retry attempts (excluding the initial request).
	MaxRetries int

	// InitialBackoff is the delay before the first retry.
	InitialBackoff time.Duration

	// MaxBackoff is the maximum delay between retries.
	MaxBackoff time.Duration

	// Multiplier is the factor by which the backoff increases each attempt.
	Multiplier float64

	// Jitter is the randomization factor (0.0 to 1.0) applied to backoff.
	Jitter float64
}

RetryConfig defines the retry policy for HTTP requests.

func DefaultRetryConfig 

func DefaultRetryConfig() *RetryConfig

DefaultRetryConfig returns the default retry configuration.

type TransportOption 

type TransportOption func(*transportOptions)

TransportOption is a functional option for configuring the resilient transport.

func WithCircuitBreakerConfig 

func WithCircuitBreakerConfig(cfg *CircuitBreakerConfig) TransportOption

WithCircuitBreakerConfig sets the circuit breaker configuration.

func WithRetryConfig 

func WithRetryConfig(cfg *RetryConfig) TransportOption

WithRetryConfig sets the retry configuration.

func WithTimeout 

func WithTimeout(d time.Duration) TransportOption

WithTimeout sets the HTTP client timeout.

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.