shellcodecoverage

package
v1.7.6 Latest Latest
Warning

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

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

Documentation

Overview

Package shellcodecoverage records and reports the fixed Sliver shellcode end-to-end test matrix. Reports omit timestamps and sort every collection so identical observations produce byte-for-byte identical output.

Index

Constants

View Source 
const (
	// MatrixStatusNotApplicable marks an unsupported target/encoder cell.
	MatrixStatusNotApplicable = "n/a"
	// MatrixStatusNotRun marks a required cell with no recorded observation.
	MatrixStatusNotRun = "not_run"
)
View Source 
const (
	// SchemaVersion is the on-disk report schema version.
	SchemaVersion = 2

	// TargetReportKind and GlobalReportKind identify shellcode coverage JSON.
	TargetReportKind = "sliver-e2e-shellcode-target-coverage"
	GlobalReportKind = "sliver-e2e-shellcode-global-coverage"

	// GlobalJSONFilename and GlobalMarkdownFilename are the aggregate outputs.
	GlobalJSONFilename     = "shellcode-coverage.json"
	GlobalMarkdownFilename = "shellcode-coverage.md"

	// RequiredSupportedCombinations is the fixed gate denominator.
	RequiredSupportedCombinations = 192
	// MinimumSGNSamples is the minimum randomized execution depth required for
	// every supported Shikata Ga Nai matrix cell.
	MinimumSGNSamples = 4

	TransportMTLS = "mtls"
	TransportWG   = "wg"
	TransportHTTP = "http"

	ImplantModeSession = "session"
	ImplantModeBeacon  = "beacon"

	CompressionNone  = "none"
	CompressionAPLib = "aplib"

	EncoderNone         = "none"
	EncoderShikataGaNai = "shikata_ga_nai"
	EncoderXOR          = "xor"
	EncoderXORDynamic   = "xor_dynamic"
)

Variables

This section is empty.

Functions

func Compressions 

func Compressions() []string

Compressions returns the fixed shellcode compression modes in report order.

func EncoderSupported 

func EncoderSupported(target coverage.Target, encoder string) bool

EncoderSupported reports whether encoder is a required matrix cell for target. Unknown targets and encoders are unsupported.

func Encoders 

func Encoders() []string

Encoders returns the fixed shellcode encoder columns in report order.

func ImplantModes 

func ImplantModes() []string

ImplantModes returns the fixed implant modes in report order.

func Targets 

func Targets() []coverage.Target

Targets returns the fixed shellcode-generation targets in report order.

func Transports 

func Transports() []string

Transports returns the fixed shellcode E2E transports in report order.

Types

type GlobalReport 

type GlobalReport struct {
	SchemaVersion int               `json:"schema_version"`
	Kind          string            `json:"kind"`
	Targets       []coverage.Target `json:"targets"`
	Transports    []string          `json:"transports"`
	ImplantModes  []string          `json:"implant_modes"`
	Compressions  []string          `json:"compressions"`
	Encoders      []string          `json:"encoders"`
	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) (GlobalReport, error)

AggregateDirectory recursively loads shellcode-coverage-<os>-<arch>.json reports and builds the complete fixed matrix. Missing reports are allowed at aggregation time and appear as NOT RUN so reports can always be emitted. Malformed reports and record identities duplicated within or across files are rejected.

func (GlobalReport) FailedRecords 

func (report GlobalReport) FailedRecords() []Record

FailedRecords returns a sorted copy of every explicitly failed observation.

func (GlobalReport) GateError 

func (report GlobalReport) GateError() error

GateError returns nil only when all 192 required combinations explicitly pass. N/A cells never affect the gate.

func (GlobalReport) NotRunIdentities 

func (report GlobalReport) NotRunIdentities() []Identity

NotRunIdentities returns every required identity without an observation. Unsupported encoder cells are N/A and are intentionally excluded.

func (GlobalReport) Validate 

func (report GlobalReport) Validate() error

Validate verifies that a global report is the canonical representation of its records and the fixed shellcode matrix.

type Identity 

type Identity struct {
	Target      coverage.Target
	Transport   string
	ImplantMode string
	Compression string
	Encoder     string
}

Identity is the unique key for one supported matrix observation.

func (Identity) String 

func (identity Identity) String() string

String returns a stable, human-readable matrix identity.

type MatrixCell 

type MatrixCell struct {
	Encoder          string        `json:"encoder"`
	Status           string        `json:"status"`
	Recorded         bool          `json:"recorded"`
	Duration         time.Duration `json:"duration_ns"`
	Detail           string        `json:"detail"`
	PayloadBytes     int64         `json:"payload_bytes"`
	RequiredSamples  int           `json:"required_samples"`
	CompletedSamples int           `json:"completed_samples"`
}

MatrixCell is one encoder result in a target/transport/mode/compression row.

type MatrixRow 

type MatrixRow struct {
	Target      coverage.Target `json:"target"`
	Transport   string          `json:"transport"`
	ImplantMode string          `json:"implant_mode"`
	Compression string          `json:"compression"`
	Cells       []MatrixCell    `json:"cells"`
}

MatrixRow contains all encoder columns for one row identity.

type Observation 

type Observation struct {
	Transport        string
	ImplantMode      string
	Compression      string
	Encoder          string
	Status           coverage.Status
	Duration         time.Duration
	Detail           string
	PayloadBytes     int64
	RequiredSamples  int
	CompletedSamples int
}

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

type Record 

type Record struct {
	Target           coverage.Target `json:"target"`
	Transport        string          `json:"transport"`
	ImplantMode      string          `json:"implant_mode"`
	Compression      string          `json:"compression"`
	Encoder          string          `json:"encoder"`
	Status           coverage.Status `json:"status"`
	Duration         time.Duration   `json:"duration_ns"`
	Detail           string          `json:"detail"`
	PayloadBytes     int64           `json:"payload_bytes"`
	RequiredSamples  int             `json:"required_samples"`
	CompletedSamples int             `json:"completed_samples"`
}

Record is one complete, supported shellcode matrix result.

func (Record) Identity 

func (record Record) Identity() Identity

Identity returns the unique key for record.

func (Record) Validate 

func (record Record) Validate() error

Validate checks that record belongs to the fixed supported matrix. Recorded skips are rejected: unsupported encoder cells are represented synthetically as N/A and supported cells must explicitly pass or fail.

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 coverage.Target) (*Recorder, error)

NewRecorder returns a recorder for one fixed shellcode target.

func (*Recorder) Add 

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

Add validates and records one observation. Duplicate identities are rejected instead of overwriting an earlier result.

func (*Recorder) Records 

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

Records returns a sorted snapshot of all observations.

func (*Recorder) Write 

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

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

type ReportPaths 

type ReportPaths struct {
	JSON     string
	Markdown string
}

ReportPaths contains the deterministic JSON and Markdown output paths.

func WriteGlobalReports 

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

WriteGlobalReports writes shellcode-coverage.json and shellcode-coverage.md.

func WriteTargetReports 

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

WriteTargetReports validates and writes deterministic reports for target.

type Summary 

type Summary struct {
	Recorded      int `json:"recorded"`
	Pass          int `json:"pass"`
	Fail          int `json:"fail"`
	NotRun        int `json:"not_run"`
	NotApplicable int `json:"not_applicable"`
	Required      int `json:"required"`
	TotalCells    int `json:"total_cells"`
}

Summary contains deterministic counts for the fixed matrix.

type TargetReport 

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

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

func LoadTargetReport 

func LoadTargetReport(path string) (TargetReport, error)

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

func (TargetReport) Validate 

func (report TargetReport) Validate() error

Validate checks a per-target report and rejects duplicate records.

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.