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 ¶
- type CircuitBreaker
- type CircuitBreakerConfig
- type CircuitState
- type Client
- func (c *Client) BulkUpdateFindings(ctx context.Context, projectID string, updates []service.UpdateFindingInput) error
- func (c *Client) CreateAsset(ctx context.Context, projectID string, input *service.CreateAssetInput) (*domain.Asset, error)
- func (c *Client) CreateAssetGroup(ctx context.Context, projectID, name string) error
- func (c *Client) DeleteAsset(ctx context.Context, projectID, assetID string) error
- func (c *Client) DeleteAssetGroup(ctx context.Context, projectID, name string) error
- func (c *Client) Get(ctx context.Context, projectID string) (*domain.Project, error)
- func (c *Client) GetAsset(ctx context.Context, projectID, assetID string) (*domain.Asset, error)
- func (c *Client) GetAssetGroupMetrics(ctx context.Context, projectID string, opts *domain.AssetGroupMetricsOptions) ([]domain.AssetGroupMetrics, error)
- func (c *Client) GetFinding(ctx context.Context, projectID, findingNumber string) (*domain.Finding, error)
- func (c *Client) GetFindingMetrics(ctx context.Context, projectID string) (*domain.FindingMetrics, error)
- func (c *Client) GetFindingOverview(ctx context.Context, projectID string) (*domain.FindingOverview, error)
- func (c *Client) GetFindingTrend(ctx context.Context, projectID string, opts *domain.TrendOptions) (*domain.FindingTrend, error)
- func (c *Client) GetFrameworks(ctx context.Context, projectID string) ([]string, error)
- func (c *Client) GetMitigatedFindings(ctx context.Context, projectID string, opts *domain.MitigatedOptions) ([]domain.MitigatedFinding, error)
- func (c *Client) GetRiskScore(ctx context.Context, projectID string) (*domain.RiskScore, error)
- func (c *Client) List(ctx context.Context) ([]domain.Project, error)
- func (c *Client) ListAssetGroups(ctx context.Context, projectID string) ([]domain.AssetGroup, error)
- func (c *Client) ListAssets(ctx context.Context, projectID string, opts *domain.AssetListOptions) ([]domain.Asset, error)
- func (c *Client) ListFindings(ctx context.Context, projectID string, opts *domain.FindingListOptions) ([]domain.Finding, error)
- func (c *Client) ListScans(ctx context.Context, projectID string, start, limit int) ([]domain.Scan, error)
- func (c *Client) SearchFindings(ctx context.Context, projectID string, search *domain.FindingSearch, ...) ([]domain.Finding, error)
- func (c *Client) UpdateAsset(ctx context.Context, projectID, assetID string, ...) (*domain.Asset, error)
- func (c *Client) UpdateFinding(ctx context.Context, projectID string, input *service.UpdateFindingInput) error
- func (c *Client) UploadScan(ctx context.Context, projectID, filePath string, ...) (*domain.ScanResult, error)
- type ResilientTransport
- type RetryConfig
- type TransportOption
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 ¶
CreateAssetGroup creates a new asset group.
func (*Client) DeleteAsset ¶
DeleteAsset removes an asset from the project.
func (*Client) DeleteAssetGroup ¶
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) 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 ¶
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 ¶
GetRiskScore returns the risk score for a project.
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) 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.
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