Common CTIM Entity Properties

In addition to having a common core set of fields built from a base entity definition, all entities in CTIM are sourceable, and describable, as defined in our common schema.

Base Field Summary

All CTIM entities are derived from the base entity.

Required Base Fields

  • id - A globally unique URI identifying this object.
  • type - A valid CTIM entity type.
  • schema_version - The CTIM schema version for this entity.

Optional Base Fields

  • external_ids - One or more custom, user-defined identifiers for the entity, distinct from its globally unique URI. External IDs will be covered in great detail later in this tutorial.
  • revision - A monotonically increasing revision, incremented each time the object is changed.
  • external_references - Specifies a list of external references which refers to non-CTIM information. This property is used to provide one or more URLs, descriptions, or IDs to records in external systems.
  • timestamp - The time this object was created at, or last modified.
  • language - The human language this object is specified in.
  • tlp - Traffic Light Protocol string, which declares how, and to whom, this entity can be shared. For more information on the Traffic Light Protocol, see https://www.us-cert.gov/tlp.

Best Practices for External IDs

External IDs (XIDs) are extremely valuable tools in your toolkit when encoding threat intelligence data in CTIM. If you are careful and consistent about how you generate your external IDs, you can reap many benefits including faster searches, and even avoid creating duplicate entities.

  • External IDs should be constructed in a deterministic fashion, so that if you know some of the key characteristics of a threat intelligence object, you will be able to reconstruct its external ID.
  • External IDs should attempt to avoid collision with IDs from other systems, if possible.
  • External IDs should be unique within a bundle.

To this end, we recommend the following best practices:

  1. All External IDs that you define should have a prefix that is likely to be unique to your organization.
  2. All External IDs should be derivable from SHA256 digest (or larger), based on a deterministically constructible string.

The structure of our recommended external ID string will look like this:

<prefix>-<entity-type>-<sha256-hash>
  • The <prefix> part helps reduce (and, if I choose a suitable prefix string, even eliminate) the chance that I'll have a collision with another namespace. Prefix strings are extremely useful when creating bundles, in order to help us prevent the creation of duplicate entities, as we'll learn later.
  • The <entity-type> part is there for my convenience, to help me reason about relationship entities, as we will also learn later.
  • The <sha256-hash> part is generated from some deterministic collection of strings. Because it is a SHA256 digest, it's exceptionally unlikely that we will accidentally collide with another external ID string. The important thing to note here, is that the hash is deterministic. It is not a hash of a random number, or a hash of the timestamp from when we ran the importer, but something that we can recreate at any time, so long as we know the inputs. For example:
$ echo "CTIM Modeling Tutorial|example-indicator-title|2019-02-28" | sha256sum
1df6883f3a46c66165bc910d6ca0d46234f0fe616a0c3d617e3e4e9caacc3878

If we pick a good descriptive prefix string ctim-tutorial, we can put all three of these parts together to build the final external ID string for this entity:

"ctim-tutorial-indicator-1df6883f3a46c66165bc910d6ca0d46234f0fe616a0c3d617e3e4e9caacc3878"

Note: Translating this process to the language of your choice is left as an exercise to the reader.

Sourceable Field Summary

All of the entities that we cover in this tutorial have the property of being sourceable. What this means, essentially, is that we may specify where the intelligence in the entity comes from. All of the fields for sourceable entities are optional, and they include the following:

Optional Sourceable Fields

  • source - A string representing the name of the source of the intelligence.
  • source_uri - A URI to the source of the intelligence, if one is available.

Notes on Sources

Naturally, if we don't know where intel comes from, we are less likely to trust it. Even though it is an optional field in the schema, all client developers should mark their intel with source and source_uri fields, whenever it is appropriate.

The source and source_uri fields do not describe the source of the CTIM entity, but the source of the cyber threat intelligence captured within that entity. So, for example, if someone in the Cisco Threat Response team is packaging up data from the National Vulnerability Database, we would list the source as the "National Vulnerability Database", and the source_uri as https://nvd.nist.gov.

The source field is useful when searching through your stored intelligence and it can dramatically speed up CTIA queries for your data later on. This is an important and useful field and all client developers are strongly encouraged to use it consistently.

Describable Field Summary

All of the entities that we cover in this tutorial have the property of being describable. What this means, essentially, is that we can provide additional descriptive text for them. All describable entity fields are optional, and they include the following:

Optional Describable Fields

  • title - A string with a maximum of 1024 characters.
  • short_description - A string with a maximum of 2048 characters.
  • description - Markdown string not exceeding 5000 characters.