Related names¶
Related names are names that have been frequently observed shortly before or after a reference name.
This has proven to be very useful to discover command and control domains used by malware when only a few of them were previously known. This is also useful to investigate an infection chain.
Internally, multiple complementary matching algorithms are used, but this client library takes care of aggregating and normalizing the results.
Getting the list of related names¶
Related names for a single name can be looked up, as well as for a vector of names:
db.related_names('www.github.com')
db.relates_names(['www.github.com', 'www.mozilla.org')
These functions return a Response::Distinct
object, if a single
name was used as a starting point, or a Response::HashByName
if a
vector was provided.
The maximum number of results can be specified:
db.related_names('www.skyrock.com', max_names: 50)
An optional block can also be given.
This block is a filter: it will be given each (name, score) as an
argument, and only names for which the return value of this block is
not false
/nil
will be kept.
For example, this only retrieves names matching a given regular expression:
db.related_names('www.skyrock.com') { |name| name.match /^miss-/ }
And this only retrieves names whose score is more than 0.1:
db.related_names('www.skyrock.com') { |name, score| score > 0.1 }
Getting the list of related names, with scores¶
In addition to a list of names, a “score” can be returned for each name found. This score is in the [0.0, 1.0] range, 1.0 meaning that a name is likely to be closely related to the reference name, 0.0 meaning that these have not been observed together very frequently.
Related names for a single name can be looked up, as well as for a vector of names:
db.related_names_with_score('www.github.com')
db.relates_names_with_score(['www.github.com', 'www.mozilla.org')
These functions return a Response::HashByName
.
An optional filter can be provided:
db.related_names_with_score('www.skyrock.com') do |name|
name.match /^miss-/
end
Getting a set of distinct related names for a list of names¶
Given a list of names, this returns a set of names related to these.
db.distinct_related_names(['www.github.com', 'www.github.io'])
This returns a Result::Distinct
object.
The maximum number of results can be specified:
db.distinct_related_names(['www.github.com', 'www.github.io'],
max_results: 250)
By default, only direct neighbors of the given names are returned, but deep traversal is also fully supported.
This will return a list of names related to those provided in the vector, but also names related to these newly found names, names related to these related names:
db.distinct_related_names(['www.github.com', 'www.github.io'],
max_results: 250,
max_depth: 3)
Since a deep traversal can return a lot of results, some not being of interest, a filter can be provided. This filter will be automatically applied after each iteration:
db.distinct_related_names(['www.github.com', 'www.github.io'],
max_results: 250,
max_depth: 3) do |name, score|
name.match(/^com-/) && score > 0.1
end
A single name can also be given instead of a vector. This is
equivalent to related_names
when a deep traversal is not performed.
This function returns a Response::Distinct
object.