sighting

Documentation

Overview

Package sighting implements the STIX 2.1 Sighting object.

The following information comes directly from the STIX 2.1 specification.

A Sighting denotes the belief that something in CTI (e.g., an indicator, malware, tool, threat actor, etc.) was seen. Sightings are used to track who and what are being targeted, how attacks are carried out, and to track trends in attack behavior.

The Sighting relationship object is a special type of SRO; it is a relationship that contains extra properties not present on the Generic Relationship object. These extra properties are included to represent data specific to sighting relationships (e.g., count, representing how many times something was seen), but for other purposes a Sighting can be thought of as a Relationship with a name of "sighting-of". Sighting is captured as a relationship because you cannot have a sighting unless you have something that has been sighted. Sighting does not make sense without the relationship to what was sighted.

Sighting relationships relate three aspects of the sighting: What was sighted, such as the Indicator, Malware, Campaign, or other SDO (sighting_of_ref), Who sighted it and/or where it was sighted, represented as an Identity (where_sighted_refs), What was actually seen on systems and networks, represented as Observed Data (observed_data_refs)

What was sighted is required; a sighting does not make sense unless you say what you saw. Who sighted it, where it was sighted, and what was actually seen are optional. In many cases it is not necessary to provide that level of detail in order to provide value.

Sightings are used whenever any SDO has been "seen". In some cases, the object creator wishes to convey very little information about the sighting; the details might be sensitive, but the fact that they saw a malware instance or threat actor could still be very useful. In other cases, providing the details may be helpful or even necessary; saying exactly which of the 1000 IP addresses in an indicator were sighted is helpful when tracking which of those IPs is still malicious.

Sighting is distinct from Observed Data in that Sighting is an intelligence assertion ("I saw this threat actor") while Observed Data is simply information ("I saw this file"). When you combine them by including the linked Observed Data (observed_data_refs) from a Sighting, you can say "I saw this file, and that makes me think I saw this threat actor".

Index

• type Sighting
  • func Decode(data []byte) (*Sighting, error)
  • func New() *Sighting
  • func (o *Sighting) AddObservedDataRefs(values interface{}) error
  • func (o *Sighting) AddWhereSightedRefs(values interface{}) error
  • func (o *Sighting) Encode() ([]byte, error)
  • func (o *Sighting) EncodeToString() (string, error)
  • func (o *Sighting) GetPropertyList() []string
  • func (o *Sighting) SetCount(i int) error
  • func (o *Sighting) SetSightingOfRef(s string) error
  • func (o *Sighting) SetSummary() error
  • func (o *Sighting) UnmarshalJSON(b []byte) error
  • func (o *Sighting) Valid() (bool, int, []string)

Types

type Sighting

type Sighting struct {
	objects.CommonObjectProperties
	properties.DescriptionProperty
	properties.SeenProperties
	Count            int      `json:"count,omitempty"`
	SightingOfRef    string   `json:"sighting_of_ref,omitempty"`
	ObservedDataRefs []string `json:"observed_data_refs,omitempty"`
	WhereSightedRefs []string `json:"where_sighted_refs,omitempty"`
	Summary          bool     `json:"summary,omitempty"`
}

Sighting - This type implements the STIX 2 Sighting SRO and defines all of

the properties and methods needed to create and work with this object. All of the methods not defined local to this type are inherited from the individual properties.

func Decode

func Decode(data []byte) (*Sighting, error)

Decode - This function is a simple wrapper for decoding JSON data. It will

decode a slice of bytes into an actual struct and return a pointer to that object along with any errors.

func New

func New() *Sighting

New - This function will create a new STIX Sighting object and return

it as a pointer. It will also initialize the object by setting all of the basic properties.

func (*Sighting) AddObservedDataRefs

func (o *Sighting) AddObservedDataRefs(values interface{}) error

AddObservedDataRefs - This method takes in a string value, a comma separated

list of string values, or a slice of string values that represents an id of an observed data object that identifies what was sighted and adds it to the observed data refs property.

func (*Sighting) AddWhereSightedRefs

func (o *Sighting) AddWhereSightedRefs(values interface{}) error

AddWhereSightedRefs - This method takes in a string value, a comma separated

list of string values, or a slice of string values that represents an id of a location object that identifies where this was sighted (location, sector, etc) and adds it to the where sighted refs property.

func (*Sighting) Encode

func (o *Sighting) Encode() ([]byte, error)

Encode - This method is a simple wrapper for encoding an object into JSON

func (*Sighting) EncodeToString

func (o *Sighting) EncodeToString() (string, error)

EncodeToString - This method is a simple wrapper for encoding an object into

JSON

func (*Sighting) GetPropertyList

func (o *Sighting) GetPropertyList() []string

GetProperties - This method will return a list of all of the properties that

are unique to this object. This is used by the custom UnmarshalJSON for this object. It is defined here in this file to make it easy to keep in sync.

func (*Sighting) SetCount

func (o *Sighting) SetCount(i int) error

SetCount - This method takes in an integer that represents the number of

sightings and upates the count properties.

func (*Sighting) SetSightingOfRef

func (o *Sighting) SetSightingOfRef(s string) error

SetSightingOfRef - This method takes in a string value that represents a STIX

identifier of the object that was sighted and updates the sighting of ref property.

func (*Sighting) SetSummary

func (o *Sighting) SetSummary() error

SetSummary - This method set the boolean value of the summary to true.

func (*Sighting) UnmarshalJSON

func (o *Sighting) UnmarshalJSON(b []byte) error

UnmarshalJSON - This method will over write the default UnmarshalJSON method

to enable custom properties that this library does not know about. It will store them as map where the value of each key is a byte arrays. This way a tool that does know how to deal with them can then further process them after this is done. This will also allow the storage of the raw JSON data.

func (*Sighting) Valid

func (o *Sighting) Valid() (bool, int, []string)

Valid - This method will verify and test all of the properties on an object

to make sure they are valid per the specification. It will return a boolean, an integer that tracks the number of problems found, and a slice of strings that contain the detailed results, whether good or bad.