sandbox

README

Sandbox

Agent client-server communication

• gRPC client/server app to bootstrap a binary sample for the malware sandbox analysis.

sequenceDiagram
rect rgb(255, 150, 150)
Client->>Server: /Deploy saferwall sandbox.zip
Server-->>Client: Deployed: {version: 1.0.0}
end
Client->>Server: /Analyze {binary, config}
Note over Client,Server: When timeout is reached ...
Server-->>Client: Analysis finished, here are your results {apitrace.jsonl}

Workflow

• Find a free VM
• Make an RPC /deploy packages.
• Make an RPC /analyze sample.
• Wait for the given timeout until results come back.
• Process the results:
  • Convert the APIs trace log and the sandbox log from jsonl to json.
  • Go over screenshots, generate thumbs and upload them.
  • Go over artifacts+dumps, yara scan them and upload the results.

References

• https://access.redhat.com/solutions/732773
• https://www.redhat.com/en/blog/introduction-virtio-networking-and-vhost-net

Documentation

Index

• Constants
• func Decode(r io.Reader, ptrToSlice interface{}) error
• func Encode(w io.Writer, ptrToSlice interface{}) error
• type AgentCfg
• type Artifact
• type ArtifactType
• type Capability
• type Config
• type DetonationResult
• type Environment
• type Event
• type EventType
• type MatchRule
• type Process
• type ProcessTree
• type Screenshot
• type Service
  • func New(cfg Config, logger log.Logger) (*Service, error)
  • func (s *Service) HandleMessage(m *gonsq.Message) error
  • func (s *Service) Start() error
• type VM
• type VirtManagerCfg
• type Win32API
• type Win32APIBuffer
• type Win32APIParam

Constants

const (
	APIParamAnnotationIn       = "in"
	APIParamAnnotationOut      = "out"
	APIParamAnnotationInOut    = "in_out"
	APIParamAnnotationReserved = "reserved"
)

SAL Win32 API annotation for function parameters.

Functions

func Decode

func Decode(r io.Reader, ptrToSlice interface{}) error

Decode reads the next JSON Lines-encoded value that reads from r and stores it in the slice pointed to by ptrToSlice.

func Encode

func Encode(w io.Writer, ptrToSlice interface{}) error

Encode writes the JSON Lines encoding of ptrToSlice to the w stream

Types

type AgentCfg

type AgentCfg struct {
	// Destination directory inside the guest where the agent is deployed.
	AgentDestDir string `mapstructure:"dest_dir"`
	// The sandbox binary components.
	PackageName string `mapstructure:"package_name"`
}

AgentCfg represents the guest agent config.

type Artifact

type Artifact struct {
	// File  name of the artifact.
	Name string `json:"name"`
	// The binary content of the artifact.
	Content []byte `json:"-"`
	// The artifact kind: memfree, filecreate, ..
	Kind ArtifactType `json:"kind"`
	// The file type: PE, ELF, etc.
	FileFormat string `json:"file_format"`
	// The SHA256 hash of the artifact.
	SHA256 string `json:"sha256"`
	// Detection contains the family name of the malware if it is malicious,
	// or clean otherwise.
	Detection string `json:"detection"`
	// List of all matched rules.
	MatchedRules []string `json:"matched_rules"`
	// The file type, i.e docx, dll, etc.
	Magic string `json:"magic"`
	// The arifact size in bytes.
	Size uint64 `json:"size"`
}

Artifact represents an extracted artifact during the dynamic analysis.

type ArtifactType

type ArtifactType string

ArtifactType represents the type of the artifact.

const (
	// Freed memory regions: ProcessName__PID__TID__VA__ID.memfree
	// example: svchost.exe__0x2E00__0xA60__0x1A46D880000__5a0a1add.memfree
	MemFree ArtifactType = "memfree"

	// Files created: ProcessName__PID__FilePath.filecreate
	// example: explorer.exe__0x2E00__C##ProgramData##Delete.vbs.filecreate
	FileCreate ArtifactType = "filecreate"

	// Code injection: ProcessName__PID__RemoteProcessName__RemotePID.codeinject
	// example: emotet.exe__0x2E00__svchost.exe__0x3004.codeinject
	CodeInjection ArtifactType = "codeinject"

	// Memory dumps: ProcessName__PID__TID__VA.memdmp
	// example: explorer.exe__0x2E00__0x400000__.memdmp
	MemDmp ArtifactType = "memdmp"
)

type Capability

type Capability struct {
	// Description describes in a few words the capability.
	Description string `json:"description"`
	// The severity of the capability: low, suspicious, high, etc.
	Severity string `json:"severity"`
	// Category of the capability: persistence, anti-analysis, etc.
	Category string `json:"category"`
	// The module that generated the capability: yara, behavior.
	Module string `json:"module"`
	// Rule ID which matched.
	RuleID string `json:"rule_id"`
	// Process identifier responsible for generating this capability.
	ProcessID string `json:"pid"`
	// Optional field indicating the malware family name.
	Family string `json:"-"`
}

Capability represents any capability found in executable files. An example of a capability is: Exfiltration over C2 server.

type Config

type Config struct {
	LogLevel      string             `mapstructure:"log_level"`
	SharedVolume  string             `mapstructure:"shared_volume"`
	EnglishWords  string             `mapstructure:"english_words"`
	YaraRules     string             `mapstructure:"yara_rules"`
	BehaviorRules string             `mapstructure:"behavior_rules"`
	Agent         AgentCfg           `mapstructure:"agent"`
	VirtMgr       VirtManagerCfg     `mapstructure:"virt_manager"`
	Producer      config.ProducerCfg `mapstructure:"producer"`
	Consumer      config.ConsumerCfg `mapstructure:"consumer"`
}

Config represents our application config.

type DetonationResult

type DetonationResult struct {
	// The API trace results. This consists of a list of all API calls made by
	// the sample.
	APITrace []byte
	// Same as APITrace, but this is not capped to any threshold.
	// The full trace is uploaded to the object storage,
	FullAPITrace []byte
	// The buffer of large byte* for some Win32 APIs.
	APIBuffers []Win32APIBuffer
	// The logs produced by the agent running inside the VM.
	AgentLog []byte
	// The logs produced by the sandbox.
	SandboxLog []byte
	// The config used to scan dynamically the sample.
	ScanCfg config.DynFileScanCfg
	// List of desktop screenshots captured.
	Screenshots []Screenshot
	// List of the sample capabilities.
	Capabilities []Capability
	// List of artifacts collected during detonation.
	Artifacts []Artifact
	// Environment represents the environment used to scan the file.
	Environment
	// Summary of system events.
	Events []Event
	// The process execution tree.
	ProcessTree ProcessTree
}

DetonationResult represents the results for a detonation.

type Environment

type Environment struct {
	// The sandbox version.
	SandboxVersion string `json:"sandbox_version"`
	// The agent version.
	AgentVersion string `json:"agent_version"`
}

Environment represents the environment used to scan the file. This include OS versions, installed software, analyzer version.

type Event

type Event struct {
	// Process identifier responsible for generating the event.
	ProcessID string `json:"pid"`
	// Type of the system event.
	Type EventType `json:"type"`
	// Path of the system event. For instance, when the event is of type:
	// `registry`, the path represents the registry key being used. For a
	// `network` event type, the path is the IP or domain used.
	Path string `json:"path"`
	// Th operation requested over the above `Path` field. This field means
	// different things according to the type of the system event.
	// - For file system events: can be either: create, read, write, delete, rename, ..
	// - For registry events: can be either: create, rename, set, delete.
	// - For network events: this represents the protocol of the communication, can
	// be either HTTP, HTTPS, FTP, FTP
	Operation string `json:"op"`
}

Event represents a system event: a registry, network or file event.

type EventType

type EventType string

EventType is the type of the system event. A type can be either: `registry`, `network` or `file`.

type MatchRule

type MatchRule struct {
	// Description describes the purpose of the rule.
	Description string `json:"description"`
	// ID uniquely identify the rule.
	ID string `json:"id"`
	// Category indicates the category of the yara rule.
	// examples include: anti-analysis, ransomware, ..
	Category string `json:"category"`
	// Severity indicates how confident the rule is to classify
	// the threat as malicious.
	Severity string `json:"severity"`
	// Process identifier responsible for matching the rule.
	// This field is not always available as some behavior rules matches over
	// multiple processes.
	ProcessID string `json:"proc_id"`
	// Family describes the family name of the malware.
	Family string `json:"family"`
}

MatchRule represents a matched yara rule.

type Process

type Process struct {
	// Process image's path.
	ImagePath string `json:"path"`
	// Process identifier.
	PID string `json:"pid"`
	// The parent process ID.
	ParentPID string `json:"parent_pid"`
	// The relationship between this process and its parent.
	ParentLink string `json:"parent_link"`
	// The name of the process.
	ProcessName string `json:"proc_name"`
	// The file type: doc, exe, etc.
	FileType string `json:"file_type"`
	// Detection contains the family name of the malware if it is malicious,
	// or clean otherwise.
	Detection string `json:"detection"`
}

Process represents a process object within the detonation context. This structure help us build the process tree.

type ProcessTree

type ProcessTree []Process

ProcessTree represents an array of processes, each process contains a process ID that can helps us track the parent/children relationship.

type Screenshot

type Screenshot struct {
	// The name of the filename for the screenshot. Format: <id>.jpeg.
	// IDs are growing incrementally from index 1 to N according to the time
	// they were taken.
	Name string
	// The binary content of the image.
	Content []byte
}

Screenshot represents a capture of the desktop while the sample is running in the VM.

type Service

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

Service represents the sandbox scan service. It adheres to the nsq.Handler interface. This allows us to define our own custom handlers for our messages. Think of these handlers much like you would an http handler.

func New

func New(cfg Config, logger log.Logger) (*Service, error)

New create a new sandbox service.

func (*Service) HandleMessage

func (s *Service) HandleMessage(m *gonsq.Message) error

HandleMessage is the only requirement needed to fulfill the nsq.Handler.

func (*Service) Start

func (s *Service) Start() error

Start kicks in the service to start consuming events.

type VM

type VM struct {
	// ID identify uniquely the VM.
	ID int32
	// Name of the VM.
	Name string
	// IP address of the VM.
	IP string
	// Operating system used by the guest.
	OS string
	// Server version.
	AgentVersion string
	// Snapshots list names.
	Snapshots []string
	// InUse represents the availability of the VM.
	InUse bool
	// Indicates if the VM is healthy.
	IsHealthy bool
	// Pointer to the domain object.
	Dom libvirt.Domain
}

VM represents a virtual machine config.

type VirtManagerCfg

type VirtManagerCfg struct {
	Network      string `mapstructure:"network"`
	Address      string `mapstructure:"address"`
	Port         string `mapstructure:"port"`
	User         string `mapstructure:"user"`
	SSHKeyPath   string `mapstructure:"ssh_key_path"`
	SnapshotName string `mapstructure:"snapshot_name"`
}

VirtManagerCfg represents the virtualization manager config. For now, only libvirt server.

type Win32API

type Win32API struct {
	// Timestamp of the trace.
	Timestamp int64 `json:"ts"`
	// Name of the API.
	Name string `json:"api"`
	// List of its parameters.
	Parameters []Win32APIParam `json:"params"`
	// Process Identifier responsible for generating the API.
	ProcessID string `json:"pid"`
	// Thread Identifier responsible for generating the API.
	ThreadID string `json:"tid"`
	// The name of the process that corresponds to the process ID.
	ProcessName string `json:"proc"`
	// Return value of the API.
	ReturnValue string `json:"ret"`
}

Win32API represents a Win32 API event.

type Win32APIBuffer

type Win32APIBuffer struct {
	// Name of the buffer.
	Name string
	// Content of the buffer.
	Content []byte
}

Win32APIBuffer represents a Win32 API large buffer of parameter of type BYTE*.

type Win32APIParam

type Win32APIParam struct {
	// SAL annotation.
	Annotation string `json:"anno"`
	// Name of the parameter.
	Name string `json:"name"`
	// Value of the parameter. This can be either a string or a slice of bytes.
	// This field is mutually exclusive with the In and Out values.
	Value interface{} `json:"val,omitempty"`
	// Win32 API sometimes uses IN and OUT annotations, so instead of having
	// one `value`, we separate the `in` and `out`. Occasionally, a function can
	// both reads from and writes to buffer, so ValueIn and ValueOut are filled.
	// The function reads from the buffer.
	InValue interface{} `json:"in_val,omitempty"`
	// The function writes to the buffer.
	OutValue interface{} `json:"out_val,omitempty"`

	// An ID is attributed to track BYTE* parameters that spans over 4KB of data.
	// If the buffer is either IN or OUT, the ID will be on `BuffID`, otherwise:
	// BuffIDIn and BufferIdOut
	BufID    string `json:"buf_id,omitempty"`
	InBufID  string `json:"in_buf_id_in,omitempty"`
	OutBufID string `json:"out_buf_id,omitempty"`
}

Win32APIParam describes parameter information for a given Win32 API.