malware-analysis.go

// Copyright 2020 Joakim Kennedy. All rights reserved. Use of
// this source code is governed by the included BSD license.

package stix2

// MalwareAnalysis captures the metadata and results of a particular static or
// dynamic analysis performed on a malware instance or family.
type MalwareAnalysis struct {
	STIXDomainObject
	// Product is the name of the analysis engine or product that was used.
	// Product names SHOULD be all lowercase with words separated by a dash
	// "-". For cases where the name of a product cannot be specified, a value
	// of "anonymized" MUST be used.
	Product string `json:"product"`
	// Version of the analysis product that was used to perform the analysis.
	Version string `json:"version,omitempty"`
	// HostVM is a description of the virtual machine environment used to host
	// the guest operating system (if applicable) that was used for the dynamic
	// analysis of the malware instance or family. If this value is not
	// included in conjunction with the operating_system_ref property, this
	// means that the dynamic analysis may have been performed on bare metal
	// (i.e. without virtualization) or the information was redacted. The value
	// of this property MUST be the identifier for a SCO software object.
	HostVM Identifier `json:"host_vm_ref,omitempty"`
	// OS is the operating system used for the dynamic analysis of the malware
	// instance or family. This applies to virtualized operating systems as
	// well as those running on bare metal. The value of this property MUST be
	// the identifier for a SCO software object.
	OperatingSystem Identifier `json:"operating_system_ref,omitempty"`
	// InstalledSoftware is a list of any non-standard software installed on
	// the operating system (specified through the operating-system value) used
	// for the dynamic analysis of the malware instance or family. The value of
	// this property MUST be the identifier for a SCO software object.
	InstalledSoftware []Identifier `json:"installed_software_refs,omitempty"`
	// ConfigurationVersion captures the named configuration of additional product
	// configuration parameters for this analysis run. For example, when a
	// product is configured to do full depth analysis of Window™ PE files.
	// This configuration may have a named version and that named version can
	// be captured in this property. This will ensure additional runs can be
	// configured in the same way.
	ConfigurationVersion string `json:"configuration_version,omitempty"`
	// Modules aptures the specific analysis modules that were used and
	// configured in the product during this analysis run. For example,
	// configuring a product to support analysis of Dridex.
	Modules []string `json:"modules,omitempty"`
	// AnalysisEngineVersion is the version of the analysis engine or product
	// (including AV engines) that was used to perform the analysis.
	AnalysisEngineVersion string `json:"analysis_engine_version,omitempty"`
	// AnalysisDefinitionVersion is the version of the analysis definitions
	// used by the analysis tool (including AV tools).
	AnalysisDefinitionVersion string `json:"analysis_definition_version,omitempty"`
	// Submitted is the date and time that the malware was first submitted for
	// scanning or analysis. This value will stay constant while the scanned
	// date can change. For example, when MalwareAnalysis was submitted to a virus
	// analysis tool.
	Submitted *Timestamp `json:"submitted,omitempty"`
	// AnalysisStarted is the date and time that the malware analysis was
	// initiated.
	AnalysisStarted *Timestamp `json:"analysis_started,omitempty"`
	// AnalysisEnded is the date and time that the malware analysis ended.
	AnalysisEnded *Timestamp `json:"analysis_ended,omitempty"`
	// ResultName is the classification result or name assigned to the malware
	// instance by the AV scanner tool.
	ResultName string `json:"result_name,omitempty"`
	// Result is the classification result as determined by the scanner or tool
	// analysis process.
	Result string `json:"result,omitempty"`
	// AnalysisSCOs contains the references to the STIX Cyber-observable
	// Objects that were captured during the analysis process.
	AnalysisSCOs []Identifier `json:"analysis_sco_refs,omitempty"`
	// Sample contains the reference to the SCO file, network traffic or
	// artifact object that this malware analysis was performed against.
	// Caution should be observed when creating an SRO between Malware and
	// Malware Analysis objects when the Malware sample_refs property does not
	// contain the SCO that is included in the Malware Analysis sample_ref
	// property.  Note, this property can also contain a reference to an SCO
	// which is not associated with Malware (i.e., some SCO which was scanned
	// and found to be benign.)
	Sample Identifier `json:"sample_ref,omitempty"`
}

func (o *MalwareAnalysis) MarshalJSON() ([]byte, error) {
	return marshalToJSONHelper(o)
}

// AddCharacterizes describes that the malware analysis is describes the
// related malware.
func (c *MalwareAnalysis) AddCharacterizes(id Identifier, opts ...STIXOption) (*Relationship, error) {
	if !IsValidIdentifier(id) || !id.ForType(TypeMalware) {
		return nil, ErrInvalidParameter
	}
	return NewRelationship(RelationshipTypeCharacterizes, c.ID, id, opts...)
}

// AddAnalysisOf describes that the malware analysis is results for the
// related malware.
func (c *MalwareAnalysis) AddAnalysisOf(id Identifier, opts ...STIXOption) (*Relationship, error) {
	if !IsValidIdentifier(id) || !id.ForType(TypeMalware) {
		return nil, ErrInvalidParameter
	}
	return NewRelationship(RelationshipTypeAnalysisOf, c.ID, id, opts...)
}

// AddStaticAnalysisOf describes that the malware analysis is static analysis
// results for the related malware.
func (c *MalwareAnalysis) AddStaticAnalysisOf(id Identifier, opts ...STIXOption) (*Relationship, error) {
	if !IsValidIdentifier(id) || !id.ForType(TypeMalware) {
		return nil, ErrInvalidParameter
	}
	return NewRelationship(RelationshipTypeStaticAnalysisOf, c.ID, id, opts...)
}

// AddDynamicAnalysisOf describes hat the malware analysis is dynamic analysis
// results for the related malware.
func (c *MalwareAnalysis) AddDynamicAnalysisOf(id Identifier, opts ...STIXOption) (*Relationship, error) {
	if !IsValidIdentifier(id) || !id.ForType(TypeMalware) {
		return nil, ErrInvalidParameter
	}
	return NewRelationship(RelationshipTypeDynamicAnalysisOf, c.ID, id, opts...)
}

// NewMalwareAnalysis creates a new MalwareAnalysis object. One of result or
// analysisSCOs must be provided.
func NewMalwareAnalysis(product, result string, analysisSCOs []Identifier, opts ...STIXOption) (*MalwareAnalysis, error) {
	if product == "" || (len(analysisSCOs) == 0 && result == "") {
		return nil, ErrPropertyMissing
	}
	base := newSTIXDomainObject(TypeMalwareAnalysis)
	obj := &MalwareAnalysis{
		STIXDomainObject: base,
		Product:          product,
		AnalysisSCOs:     analysisSCOs,
		Result:           result,
	}

	err := applyOptions(obj, opts)
	return obj, err
}

const (
	// MalwareResultMalicious AV tool reported the malware binary as malicious.
	MalwareResultMalicious = "malicious"
	// MalwareResultSuspicious AV tool reported the malware binary as
	// suspicious but not definitively malicious.
	MalwareResultSuspicious = "suspicious"
	// MalwareResultBenign AV tool reported the malware binary as benign.
	MalwareResultBenign = "benign"
	// MalwareResultUnknown AV tool was unable to determine whether the malware
	// binary is malicious.
	MalwareResultUnknown = "unknown"
)