domain

Documentation

Overview

Package domain is a container of all of the domain types and interfaces that are used across multiple packages within the service.

This package is also the container for all domain errors leveraged by the service. Each error here should represent a specific condition that needs to be communicated across interface boundaries.

Generally speaking, this package contains no executable code. All elements are expected to be either pure data containers that have no associated methods or interface definitions that have no corresponding implementations in this package. The notable exception to this are the domain error types which are required to define a corresponding Error() method. Because these errors provide executable code they must also have corresponding tests. Only domain error types are allowed to deviate from the "no executable code" rule.

Index

• Constants
• type Finding
• type InProgressError
  • func (e InProgressError) Error() string
• type LogFn
• type Logger
• type MissingScanTargetError
  • func (e MissingScanTargetError) Error() string
• type NotFoundError
  • func (e NotFoundError) Error() string
• type Producer
• type Scanner
• type ScriptedScanner
• type Stat
• type StatFn
• type Store
• type Vulnerability
• type VulnerabilityDate
• type VulnerabilityID
• type VulnerabilityScore

Constants

const (
	VulnStateLikely  = "LIKELY VULNERABLE"
	VulnStateNot     = "NOT VULNERABLE"
	VulnStateVuln    = "VULNERABLE"
	VulnStateDOS     = "VULNERABLE (DoS)"
	VulnStateExploit = "VULNERABLE (Exploitable)"
	VulnStateUnknown = "UNKNOWN (unable to test)"

	RiskFactorHigh   = "HIGH"
	RiskFactorMedium = "MEDIUM"
	RiskFactorLow    = "LOW"
)

nolint (self documenting constants)

Types

type Finding

type Finding struct {
	// Timestamp is when the finding was detected.
	Timestamp time.Time
	// IP is the address that was scanned.
	IP string
	// Hostnames are optionally included names that resolve to the scan IP.
	Hostnames       []string
	Vulnerabilities []Vulnerability
}

Finding is a set detected vulnerability for a specific system.

type InProgressError

type InProgressError struct {
	Identifier string
}

InProgressError is returned from Load when the value is not present but the work is in progress.

func (InProgressError) Error

func (e InProgressError) Error() string

type LogFn

type LogFn = runhttp.LogFn

LogFn is the recommended way to extract a logger from the context.

type Logger

type Logger = runhttp.Logger

Logger is the project logger interface.

type MissingScanTargetError

type MissingScanTargetError struct {
	Target string
}

MissingScanTargetError represents cases where the given host or IP for a scan cannot be found.

func (MissingScanTargetError) Error

func (e MissingScanTargetError) Error() string

type NotFoundError

type NotFoundError struct {
	Identifier string
}

NotFoundError is returned from Load when the value is neither set nor is is there a progress marker.

func (NotFoundError) Error

func (e NotFoundError) Error() string

type Producer

type Producer interface {
	Produce(ctx context.Context, event interface{}) (interface{}, error)
}

Producer is used to ship results to a destination.

type Scanner

type Scanner interface {
	Scan(ctx context.Context, host string) ([]Finding, error)
}

Scanner represents a system that will probe the given host and determine if there are any vulnerable components.

type ScriptedScanner

type ScriptedScanner interface {
	ScanWithScripts(ctx context.Context, scripts []string, scriptArgs []string, host string) ([]Finding, error)
}

ScriptedScanner is a Scanner that enables per-scan overrides of the specific scripts that are executed.

type Stat

type Stat = runhttp.Stat

Stat is the project metrics client interface.

type StatFn

type StatFn = runhttp.StatFn

StatFn is the recommended way to extract a metrics client from the context.

type Store

type Store interface {
	// Mark the identifier as in-progress.
	Mark(ctx context.Context, identifier string) error
	// Set the value of the identifier.
	Set(ctx context.Context, identifier string, findings []Finding) error
	// Load the value of the identifier.
	Load(ctx context.Context, identifier string) ([]Finding, error)
}

Store is used to track the results of scans.

type Vulnerability

type Vulnerability struct {
	// Unique identity of the vulnerability as reported by nmap.
	Key string
	// Title of the vulnerability.
	Title string
	// State of the vuln. One of the VulnState* constants.
	State string
	// External vulnerability database identifiers. (optional)
	IDs []VulnerabilityID
	// Short-hand severity rating. One of HIGH, MEDIUM, or LOW. (optional)
	RiskFactor string
	// Scores defined as CVSS or CVSSv2. (optional)
	Scores []VulnerabilityScore
	// Long form description of the issue. (optional)
	Description string
	// Critical dates associated with the vulnerability such as disclosure.
	// (optional)
	Dates []VulnerabilityDate
	// CheckResults contains any output relevant to the scan or probe that might
	// help diagnose or confirm the vulnerability state. (optional)
	CheckResults []string
	// ExploitResults contains any output gathered during an exploid of a
	// system. (optional)
	ExploitResults []string
	// ExtraInfo contains any arbitrary content from a scan or probe that does
	// not fit into other categories. (optional)
	ExtraInfo []string
	// References are external links to vulnerability databases or pages that
	// contain additional content about the vulnerability.
	References []string

	// Source is the script that generated the finding.
	Source string
	// Port on which the vulnerability was detected.
	Port int
	// Protocol used during network communications
	Protocol string
	// Service is the kind of application running on the port. Ex: http
	Service string
}

Vulnerability is a container that matches the output of any nmap library that uses the vulns module for reporting issues. There is no apparent documentation or contract for the library so this has been created based on the source code of the vulns module. Notably, the `local format_vuln_base` function was used.

type VulnerabilityDate

type VulnerabilityDate struct {
	// Type is the kind of date. Most commonly this is "disclosure".
	Type  string
	Year  int
	Month int
	Day   int
}

VulnerabilityDate is used to describe when vulnerability conditions were reported or updated.

type VulnerabilityID

type VulnerabilityID struct {
	Type  string
	Value string
}

VulnerabilityID is a container for typed identifiers. The most common entries are Type=CVE and Type=OSVDB.

type VulnerabilityScore

type VulnerabilityScore struct {
	Type  string
	Value string
}

VulnerabilityScore is a container of various forms of severity scoring. The most common entries are Type=CVSS and Type=CVSSv2.