malware

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Aug 5, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package malware is a deterministic, fully-offline static scanner for known-bad content in image layers: cryptominer binaries, web/reverse shells, persistence droppers, and known-bad file hashes. It closes the static side of CAPABILITY_SPEC domains 3/11 — the runtime detector already catches behavior, but nothing scanned the layers at rest.

Design mirrors the rest of the tool: no network, no external engine. Signatures are data (see internal/malware/data/signatures.json, embedded), so the pack can grow without code changes and an operator can supply an external pack. Matching is exact/substring/hash — never a heuristic that could differ between runs — so results are golden-testable.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func SortMatches

func SortMatches(ms []Match)

SortMatches orders matches deterministically: by path, then signature id, then evidence, so callers (and goldens) see a stable sequence.

Types

type Kind

type Kind string

Kind classifies what a signature detects, which maps to a finding rule id.

const (
	KindHash        Kind = "hash"        // exact file content hash of known malware
	KindFilename    Kind = "filename"    // known-bad basename (e.g. xmrig)
	KindContent     Kind = "content"     // byte/string pattern inside a file
	KindPersistence Kind = "persistence" // suspicious persistence/cron/preload entry
)

type Match

type Match struct {
	SignatureID string
	Name        string
	Kind        Kind
	Severity    Severity
	Description string
	Path        string
	// Layer is the layer index the file came from, or -1 for a flattened/dir scan.
	Layer int
	// Deleted is true when the file existed only in a lower layer and was removed
	// by a later whiteout — recoverable but not in the final image.
	Deleted bool
	// Evidence is the concrete matched token (filename, pattern, or "sha256").
	Evidence string
}

Match is one detection against a specific file.

type Pack

type Pack struct {
	Version    string      `json:"version"`
	Signatures []Signature `json:"signatures"`
}

Pack is a set of signatures.

func LoadPack

func LoadPack(path string) (Pack, error)

LoadPack reads and parses a signature pack from a file path, for `--sigs`.

func ParsePack

func ParsePack(data []byte) (Pack, error)

ParsePack parses a signature pack from JSON bytes.

type Scanner

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

Scanner applies a Pack to file content.

func Default

func Default() (*Scanner, error)

Default returns a Scanner built from the embedded signature pack.

func NewScanner

func NewScanner(p Pack) *Scanner

NewScanner indexes a Pack for scanning.

func (*Scanner) Count

func (s *Scanner) Count() int

Count reports how many signatures the pack carries, for diagnostics.

func (*Scanner) ScanFile

func (s *Scanner) ScanFile(path string, data []byte, layer int, deleted bool) []Match

ScanFile returns every signature that matches a single file. layer/deleted are carried through into the Match for provenance; pass layer=-1 for a flat scan.

type Severity

type Severity string

Severity mirrors the qualitative bands used elsewhere, kept local so the signature pack is self-describing without importing the engine.

const (
	SevCritical Severity = "critical"
	SevHigh     Severity = "high"
	SevMedium   Severity = "medium"
)

type Signature

type Signature struct {
	ID          string   `json:"id"`   // stable id, e.g. MAL-MINER-XMRIG
	Name        string   `json:"name"` // human label
	Kind        Kind     `json:"kind"`
	Severity    Severity `json:"severity"`
	Description string   `json:"description,omitempty"`
	// Hash is a lowercase hex sha256 of the whole file (KindHash).
	Hash string `json:"hash,omitempty"`
	// Filenames are basenames matched case-insensitively (KindFilename).
	Filenames []string `json:"filenames,omitempty"`
	// Patterns are substrings searched within file contents (KindContent /
	// KindPersistence). Matching is literal (not regexp) so it is O(n) and
	// deterministic; a match on any pattern fires the signature.
	Patterns []string `json:"patterns,omitempty"`
	// PathHints, when set, limits KindContent/KindPersistence matching to files
	// whose path contains one of these substrings (e.g. "cron", "ld.so"), cutting
	// false positives. Empty = match anywhere.
	PathHints []string `json:"path_hints,omitempty"`
}

Signature is one detection rule.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL