Object Fact Model

Overview

The basic building block of grafeo is the Object-Fact-Model which consists of a large set of objects, such as indicators, threat actors, and object descriptors, on which the system can attribute facts collected from analysis and intelligence sources. Each object represents a real world eternal entity, which exists (theoretically at least) independently of any other information, such as an IP, a person, a file, etc.

It is the facts and relations between objects which are attributed on the objects that may be added from different sources. Such facts may be uncertain, may be sensitive, and even contradicting or overlapping, and need to be traceable and backed by evidence and assessments.

The Object-Fact-Model therefore supports:

• Any number of unique objects which are globally defined.
• Any number of facts added to each object. A fact may be connected to a single object, or may be connected to multiple objects, creating a relation between them. A fact can also directly reference another fact to add more information to that fact (called a meta fact).
• Each fact is a simple statement of a property, is clearly owned by an organization and traceable to a source and point in time.
• Multiple facts may overlap and/or contradict, it is up to the analyst to determine which information to trust.
• Facts are immutable, that is, once a fact is added to the system, it cannot be altered or removed. New information is added as additional facts. To contest a false fact, a user may issue a new fact of type "retraction", asserting that the referenced fact is invalid/retracted.
• The sharing level is set on each fact, to allow granular access control to information. Access control is both role-based and explicit.
• Each fact can be backed by a set of evidence and comments.
• Since every piece of data is timestamped and immutable, this allows the system to "rewind time" or "replay events", and create exact timelines.
• Even changing the access mode of a fact is not allowed. To make a fact more public, the fact needs to be retracted and republished with a less restrictive access mode. Adding a fact with a more restrictive access mode does not make sense, since any user who had access to the original fact will still do so.

Model

Note: The purpose of this section is to explain the concepts behind the Object-Fact-Model. The actual implementation will be slightly different and the API documentation provides all details.

Model	Fields	Notes
Namespace	UUID name	Global namespace definition for type metadata. Each system instance has its own namespace, to allow multiple instances to share globally defined objects within each namespace. Software defined metadata uses a statically defined namespace (e.g. 00000000-0000-0000-0000-000000000000).
Organization	UUID name	List of organizations defined in the system. Organizations are used to mark ownership of facts, and affiliation of sources. Organizations are local to one system, and not shared between system instances.
ObjectType	UUID namespaceUUID name validator	List of object types defined in the system. Object type names are unique within each namespace. Software defined types all have the system defined namespace (e.g. 00000000-0000...), and a static UUID. Each type defines a validator rule (not defined, but regexp or other kind of format specification), to allow enforcing a certain data format for each type.
FactType	UUID namespaceUUID name validator relevantObjectBindings relevantFactBindings	List of fact types defined in the system. Fact type names are unique within each namespace. Software defined types all have the system defined namespace (e.g. 00000000-0000...), and a static UUID. Each fact type defines a validator, similar to object types. Each fact type specifies a list of relevant object bindings. The list should specify which objects may be connected to a fact, and in particular which object types a fact may create relations between. A fact may e.g. be allowed to create a relation between a domain and an IP but not from a domain to a filetype. The binding is directional, to allow the system to determine that the connection between two objects may only be set in one direction. A fact type can also specify a list of relevant fact bindings to define to which facts a meta fact can link directly.
Source	UUID namespaceUUID organizationUUID type trustLevel	Specifies the source for each fact. Sources may be shared to other system instances to allow traceability of information, therefore sources are namespaced. A source may be of different types: user, inputPort, analysisModule. Each source is affiliated with an organization, giving a default ownership to information added by a source (which may be overridden). For each source, the system defines a trust level, which may be used to indicate how much a certain fact is trusted, or to calculate a chain of trust.
Object	UUID typeUUID value	Each object in the system has a type and a value. The object type validator determines if a value is valid. Certain object types may not have a meaningful value (e.g. "procedure"), in which case the object is basically a placeholder for a set of facts. Each object is globally defined, and is automatically created on first use. However, existing objects are not visible to a user unless the user has access to any of the facts bound to the object.
Fact	UUID typeUUID value inReferenceToUUID organizationUUID accessMode sourceUUID confidenceLevel timestamp lastSeenTimestamp	Each fact has a type and a value. The fact type validator determines if a value is valid. A fact may reference another fact, especially relevant for facts of type "retraction" (a fact that another existing fact is retracted or asserted as wrong). In case of a meta fact that fact directly references another fact without any links to objects. Each fact is bound to an organization, and has an access mode (either explicit, roleBased or public). Facts with roleBased access mode are available to users with role-based access to the bound organization, or users in the facts explicit ACL. Facts with access mode explicit are only available to explicit ACL members. Each fact is marked with the timestamp of its creation and the source which added it. The source may point to a user, an input port or an analysis module. Each fact is marked with a confidence level, which is the confidence given by the source for this particular piece of information. Using the source trust and the fact confidence, a user may calculate how reliable this particular fact is. Adding the exactly same fact (same type, value, source, access mode, organization) does not duplicate the fact, but updates lastSeenTimestamp (the only exception from the rule of "immutable facts").
ObjectFactBinding	objectUUID factUUID type: src, dst, none	This model basically states that facts are bound to objects. If a fact is bound to multiple objects, the binding may have a direction. The exact form of this model depends on the chosen storage technology.
FactObjectBinding	factUUID objectUUID type: src, dst, none	Same as ObjectFactBinding but reversed binding.
FactComment	UUID factUUID replyToUUID comment sourceUUID timestamp	A user may add a comment to any visible fact. A comment may be a reply to another existing comment. Each comment is marked with the timestamp and the source of the comment (generally a user).
FactACL	UUID factUUID subjectUUID sourceUUID timestamp	Each fact may have a list of explicit access grants. Since facts are immutable, the system can only grant read access, and any user with read access may grant read access to other users, or use the information as he or she sees fit. An ACL grant is irrevocable, but gives read access to an immutable fact. Other facts or future facts added to the same object are not affected. Each ACL entry is marked with the timestamp of the grant and the source of the grant (generally a user).
EvidenceSubmission	UUID name dataType mediaType length timestamp originalTimestamp sourceUUID accessMode evidenceChecksum	Each piece of evidence submitted to the system has a name, a data type, a media type and is attributed to a source. The timestamp documents when the evidence was submitted. The submission may also document the timestamp of the original evidence (e.g. when it was seen in the real world). The evidence may be marked with a different access mode than the fact it belongs to (given the possibility that the fact itself may be widely spread, but a particular evidence to that fact is more sensitive). Finally, the submission contains the checksum of the submitted data, pointing to the actual evidence.
Evidence	checksum value/data	The evidence model simply makes sure that each unique piece of evidence data (potentially large) is not duplicated in the system. If a submitted evidence has the same checksum as an existing evidence, only the submission is stored, pointing to the same evidence data.
FactEvidenceBinding	UUID factUUID submissionUUID	This model basically states that facts have a list of evidence submissions. The exact form of this model depends on the chosen storage technology.

Example

The Object-Fact-Model basically describes a type system where a user has to define an instance of it by specifying object types and fact types, and afterwards adds the actual data (facts) complying with the types. The picture below shows an example of such an instance.