coverage

package
v1.7.7 Latest Latest
Warning

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

 Go to latest Published: Sep 3, 2026 License: GPL-3.0 Imports: 14 Imported by: 0

Documentation

Overview

Package coverage records and renders Sliver comprehensive end-to-end test coverage. Reports intentionally contain no timestamps so identical inputs produce byte-for-byte identical output.

Index

Constants

View Source 
const (
	// SchemaVersion is the on-disk report schema version.
	SchemaVersion = 1

	// TargetReportKind identifies a per-target report.
	TargetReportKind = "sliver-e2e-target-coverage"
	// GlobalReportKind identifies an aggregated report.
	GlobalReportKind = "sliver-e2e-global-coverage"

	// GlobalJSONFilename, GlobalMarkdownFilename, and CommandMarkdownFilename
	// are the aggregator outputs.
	GlobalJSONFilename      = "coverage-summary.json"
	GlobalMarkdownFilename  = "coverage-summary.md"
	CommandMarkdownFilename = "command-coverage.md"
)
View Source 
const (
	TransportMTLS = "mtls"
	TransportWG   = "wg"
	TransportHTTP = "http"

	ImplantModeSession = "session"
	ImplantModeBeacon  = "beacon"
)

Canonical transport and implant-mode names used by the comprehensive matrix. The fields remain strings so future transports and modes can still be represented without a schema change.

View Source 
const MatrixStatusNotRun = "not_run"

MatrixStatusNotRun marks a cross-product cell for which no scenario record was found. It is intentionally not a valid Record status.

Variables

This section is empty.

Functions

This section is empty.

Types

type Command 

type Command struct {
	GRPCMethod string `json:"grpc_method"`
	Scenario   string `json:"scenario"`
}

Command identifies one command scenario represented by a matrix row.

type CommandExpectation 

type CommandExpectation struct {
	Command
	SupportedTargets  []Target
	UnsupportedReason string
}

CommandExpectation declares one required command/scenario row and the exact targets on which it is supported. SupportedTargets must be explicit and nonempty so additions to the target matrix cannot silently gain coverage.

func ComprehensiveCatalog 

func ComprehensiveCatalog() []CommandExpectation

ComprehensiveCatalog returns the static command/scenario catalog exercised by the comprehensive E2E harness. Keeping this independent of observed reports ensures a command omitted everywhere is still rendered as NOT RUN.

type Dimensions 

type Dimensions struct {
	Targets      []Target
	Transports   []string
	ImplantModes []string
	Commands     []CommandExpectation
}

Dimensions declares the expected cross-product axes. A nonempty axis is strict: observed identities outside it are rejected. Empty axes are inferred from records for focused callers and tests.

func ComprehensiveDimensions 

func ComprehensiveDimensions() Dimensions

ComprehensiveDimensions returns the requested Sliver E2E matrix. Darwin is the Go operating-system name for macOS and wg is Sliver's WireGuard transport name.

type GlobalReport 

type GlobalReport struct {
	SchemaVersion   int              `json:"schema_version"`
	Kind            string           `json:"kind"`
	Targets         []Target         `json:"targets"`
	Transports      []string         `json:"transports"`
	ImplantModes    []string         `json:"implant_modes"`
	Commands        []Command        `json:"commands"`
	RPCDispositions []RPCDisposition `json:"rpc_dispositions"`
	Summary         Summary          `json:"summary"`
	Records         []Record         `json:"records"`
	Matrix          []MatrixRow      `json:"matrix"`
}

GlobalReport is the deterministic aggregate JSON representation.

func AggregateDirectory 

func AggregateDirectory(root string, expected Dimensions) (GlobalReport, error)

AggregateDirectory recursively finds per-target coverage-*.json reports and builds the global cross-product report. Malformed reports and identities duplicated within or across source files are rejected.

func (GlobalReport) FailedRecords 

func (r GlobalReport) FailedRecords() []Record

FailedRecords returns a sorted copy of all failed scenario records.

func (GlobalReport) NotRunIdentities 

func (r GlobalReport) NotRunIdentities() []Identity

NotRunIdentities returns every required cross-product identity without a recorded outcome. Expected platform-specific skips are not missing records.

func (GlobalReport) RecordedSkipRecords 

func (r GlobalReport) RecordedSkipRecords() []Record

RecordedSkipRecords returns a sorted copy of all explicitly recorded skip results. Catalog validation rejects records for unsupported targets, so in a strict catalog aggregate every result returned here is a skipped scenario on a supported target/transport/mode cell. Synthetic platform skips are matrix cells with Recorded=false and are intentionally excluded.

type Identity 

type Identity struct {
	TargetOS    string
	TargetArch  string
	Transport   string
	ImplantMode string
	GRPCMethod  string
	Scenario    string
}

Identity is the unique key for one scenario result.

func (Identity) String 

func (i Identity) String() string

type MatrixCell 

type MatrixCell struct {
	TargetOS    string        `json:"target_os"`
	TargetArch  string        `json:"target_arch"`
	Transport   string        `json:"transport"`
	ImplantMode string        `json:"implant_mode"`
	Status      string        `json:"status"`
	Duration    time.Duration `json:"duration_ns"`
	Detail      string        `json:"detail"`
	Recorded    bool          `json:"recorded"`
}

MatrixCell is one target/transport/mode result in a global matrix row.

type MatrixRow 

type MatrixRow struct {
	GRPCMethod string       `json:"grpc_method"`
	Scenario   string       `json:"scenario"`
	Cells      []MatrixCell `json:"cells"`
}

MatrixRow contains the complete cross product for one gRPC method/scenario.

type Observation 

type Observation struct {
	Transport   string
	ImplantMode string
	GRPCMethod  string
	Scenario    string
	Status      Status
	Duration    time.Duration
	Detail      string
}

Observation is the target-independent portion of a scenario result supplied to a Recorder.

type RPCDisposition 

type RPCDisposition struct {
	Method         string              `json:"method"`
	Class          RPCDispositionClass `json:"class"`
	ImplantTraffic bool                `json:"implant_traffic"`
	Reason         string              `json:"reason"`
}

RPCDisposition classifies one method in the generated SliverRPC service. ImplantTraffic is false for server-only methods and for tunnel allocation methods which create only server-side state.

func ComprehensiveRPCDispositions 

func ComprehensiveRPCDispositions() []RPCDisposition

ComprehensiveRPCDispositions returns the exhaustive classification of the generated SliverRPC service surface. Tests compare this registry against the protobuf service descriptor, so a newly added RPC cannot remain unclassified.

type RPCDispositionClass 

type RPCDispositionClass string

RPCDispositionClass describes how a SliverRPC method relates to an implant. 

const (
	// RPCServerOnly is a control-plane method which does not exchange a command
	// with an implant.
	RPCServerOnly RPCDispositionClass = "server-only"
	// RPCCommandCovered is a finite implant command exercised by the
	// comprehensive E2E command catalog.
	RPCCommandCovered RPCDispositionClass = "implant-command-covered"
	// RPCCommandDeferred is a finite implant command which is deliberately not
	// yet exercised by the comprehensive E2E command catalog.
	RPCCommandDeferred RPCDispositionClass = "implant-command-deferred"
	// RPCImplantLifecycle changes the implant process or connection lifecycle.
	RPCImplantLifecycle RPCDispositionClass = "implant-lifecycle"
	// RPCTunnelInteractive belongs to a pivot, tunnel, SOCKS, port-forward, or
	// interactive stream protocol rather than the finite command matrix.
	RPCTunnelInteractive RPCDispositionClass = "tunnel-or-interactive"
)

type Record 

type Record struct {
	TargetOS    string        `json:"target_os"`
	TargetArch  string        `json:"target_arch"`
	Transport   string        `json:"transport"`
	ImplantMode string        `json:"implant_mode"`
	GRPCMethod  string        `json:"grpc_method"`
	Scenario    string        `json:"scenario"`
	Status      Status        `json:"status"`
	Duration    time.Duration `json:"duration_ns"`
	Detail      string        `json:"detail"`
}

Record is one complete scenario result. Duration is encoded as nanoseconds to preserve time.Duration exactly across aggregation.

func (Record) Identity 

func (r Record) Identity() Identity

Identity returns the unique key for r. Status, duration, and detail are not identity fields, so a scenario cannot be recorded twice with different outcomes.

func (Record) Validate 

func (r Record) Validate() error

Validate checks all required identity fields and result values.

type Recorder 

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

Recorder safely collects results for one target from concurrent subtests.

func NewRecorder 

func NewRecorder(target Target) (*Recorder, error)

NewRecorder returns a recorder for target.

func (*Recorder) Add 

func (r *Recorder) Add(observation Observation) error

Add records one observation. Duplicate scenario identities are rejected at insertion time rather than silently overwriting an earlier outcome.

func (*Recorder) Records 

func (r *Recorder) Records() []Record

Records returns a sorted snapshot of the recorder's results.

func (*Recorder) Write 

func (r *Recorder) Write(dir string) (ReportPaths, error)

Write writes coverage-<os>-<arch>.json and .md beneath dir.

type ReportPaths 

type ReportPaths struct {
	JSON            string
	Markdown        string
	CommandMarkdown string
}

ReportPaths contains the files written by a report call. CommandMarkdown is populated only for global reports.

func WriteGlobalReports 

func WriteGlobalReports(dir string, report GlobalReport) (ReportPaths, error)

WriteGlobalReports writes the global JSON, detailed Markdown, and condensed command coverage Markdown reports.

func WriteTargetReports 

func WriteTargetReports(dir string, target Target, records []Record) (ReportPaths, error)

WriteTargetReports validates and writes deterministic JSON and Markdown for one target.

type Status 

type Status string

Status is the result of one end-to-end scenario. 

const (
	StatusPass Status = "pass"
	StatusFail Status = "fail"
	StatusSkip Status = "skip"
)

func (Status) Valid 

func (s Status) Valid() bool

Valid reports whether s is a supported result status.

type Summary 

type Summary struct {
	Recorded   int `json:"recorded"`
	Pass       int `json:"pass"`
	Fail       int `json:"fail"`
	Skip       int `json:"skip"`
	NotRun     int `json:"not_run"`
	TotalCells int `json:"total_cells"`
}

Summary contains aggregate record and matrix counts.

type Target 

type Target struct {
	OS   string `json:"os"`
	Arch string `json:"arch"`
}

Target identifies the operating system and architecture under test.

func (Target) Validate 

func (t Target) Validate() error

Validate checks that the target is safe to use as both an identity and a report filename component.

type TargetReport 

type TargetReport struct {
	SchemaVersion int      `json:"schema_version"`
	Kind          string   `json:"kind"`
	Target        Target   `json:"target"`
	Records       []Record `json:"records"`
}

TargetReport is the deterministic on-disk representation for one target.

func LoadTargetReport 

func LoadTargetReport(path string) (TargetReport, error)

LoadTargetReport strictly decodes and validates a per-target JSON report.

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.