REFERENCES

Asset Relations

14min

The V3 release of Flare's API adds a series of endpoints that provide advanced functionality used to explore the different types of assets and their relations to one another.

While the use of the API itself might be straightforward, some explanation of specialized terms is necessary to explain its functionality clearly.

Glossary

Identifier

A Flare specific term referring to a configuration created to monitor continuously for an asset (e.g. an Email identifier is configured to monitor the asset [email protected]). Configured either in the Flare platform or through the API, they gather information about events, entities or other assets related to their monitored asset. They will send out alerts through different channels if configured to do so.

Asset

Something that has value to an organization, which can be tangible (e.g. person) or intangible (e.g. domain, email, IP, BIN, brand). They are immutable and don't contain any user configuration such as filters.

Relation

Defines how different assets are associated with one another (e.g. a Domain asset is mentioned in a GitHub Repository asset).

Concept

Asset relations allow for browsing relations between assets. Browsing relations can be a powerful way of getting insight about the data in Flare by understanding how it is connected. This supports more complex use cases than an identifier feed, as it is possible to distinguish between the different reasons why the different assets would be related to the identifier's monitored asset.

As an example, a Domain asset can be mentioned in (e.g. a code file in a GitHub Repository contains a mention of the Domain example.com) or contribute to (e.g. a commit was made in a GitHub Repository by [email protected]) a GitHub Repository. These relations are fundamentally different and may now be analyzed independently.

The relations each contain params, which qualify the relation between the assets with additional information (e.g. the number of commits that a GitHub User has contributed to a GitHub Repository).

Additions

Flare added new types of identifiers to allow for better monitoring of assets revolving around public contributions on GitHub. These new types are the following :

  • GithubProject
  • GithubUser
  • Email

History

The data used to map and qualify relations between assets is partly constructed using Flare's new capability of monitoring every commit made publicly on GitHub. Commit data previous to May 13th 2022 should not be expected to be exhaustive.

Relations

The currently supported relations revolve around GitHub repositories and users and the domains or emails that contribute publicly on that platform.

Relations Diagram



Relation Types

Subdomain of

The subdomain_of relation qualifies a Domain asset as being a part of another Domain asset, under the DNS hierarchy.

Mentioned in

The mentioned_in relation qualifies a Domain asset as being found in a code file contained in a GitHub Repository asset. This relation is qualified with the following params :

  • number_of_commits : The number of monitored commits in that GitHub Repository.
  • number_of_mentions : The number of mentions of the specified Domain in that GitHub Repository.
  • number_of_leaked_secrets : The number of leaked secrets Flare found in that GitHub Repository using Semgrep and other tools. These may have been leaked by anyone.

Contributed to

The contributed_to relation qualifies either a GitHub User, Domain or an Email asset as having committed publicly into a GitHub Repository asset. This relation is qualified with different params, based on the type of asset having contributed. They can be the following:

  • Domain asset :
    • number_of_commits : The number of monitored commits in that GitHub Repository.
    • number_of_domain_commits : The number of monitored commits made by the specified Domain in that GitHub Repository.
    • number_of_domain_emails : The number of Persons commiting in that GitHub Repository using that Domain.
    • number_of_leaked_secrets : The number of leaked secrets Flare found in that GitHub Repository using Semgrep and other tools. These may have been leaked by anyone.
  • Email asset:
    • number_of_email_commits : The number of commits made by the specified Email in that GitHub Repository.

Commits with

The commits_with relation qualifies an Email asset as being used by a GitHub User asset to commit code. This relation is qualified with the following params :

  • number_of_email_commits : The number of commits made by that GitHub User using the specified email.
  • number_of_github_projects : The number of GitHub Repositories in which that GitHub User has publicly committed.

Found from

The found_from relation qualifies an Email asset as being part of a Domain asset. This relation is qualified with the following params :

  • number_of_github_projects : The number of GitHub Repository in which that Emai has publicly committed.
  • number_of_email_commits : The number of commits made publicly on GitHub by the specified Email.

Use Cases

The following use cases and more are supported by using asset relations :

  • Listing all the GitHub Repositories in which a sensitive Domain asset is mentioned and identify the GitHub Users and Emails commiting into it.
  • Listing all the GitHub Repositories in which the Emails from your organization are committing publicly and order them by number of commits and leaked secrets.
  • Listing all the GitHub Repositories in which specific monitored actors are committing publicly and identify those containing leaked secrets.

API Documentation

The Flare API V3, which contains the asset relations endpoints is documented here : Firework API V3

Related Articles