From 40a979572839784aae9896312dafc12aaa59576d Mon Sep 17 00:00:00 2001 From: Alexandre Dulaunoy Date: Fri, 30 Aug 2024 11:31:33 +0200 Subject: [PATCH] feat: [best-practices] Initial conversion of STIX best practices to AsciiDoc using existing CSS template Reference: https://github.com/oasis-tcs/cti-stix2/issues/323 --- best-practices/STIX-Best-Practice-Guide.adoc | 889 +++++++++++++++++++ best-practices/css/stix.css | 459 ++++++++++ best-practices/images/oasis-logo.png | Bin 0 -> 12402 bytes 3 files changed, 1348 insertions(+) create mode 100644 best-practices/STIX-Best-Practice-Guide.adoc create mode 100644 best-practices/css/stix.css create mode 100644 best-practices/images/oasis-logo.png diff --git a/best-practices/STIX-Best-Practice-Guide.adoc b/best-practices/STIX-Best-Practice-Guide.adoc new file mode 100644 index 0000000..8d6077f --- /dev/null +++ b/best-practices/STIX-Best-Practice-Guide.adoc @@ -0,0 +1,889 @@ += image:images/oasis-logo.png[OASIS logo,width=306,height=63] +:xrefstyle: short +:stylesdir: css +:stylesheet: stix.css +:toc: macro +:toclevels: 4 +:star: * +:bracket: [ +:sectnums!: + +STIX Best Practices Guide + +Version 1.0 + +== *Introduction* + +A best practice is defined as: + +_“…a method or technique that has been generally accepted as superior to any alternatives because it produces results that are superior to those achieved by other means or because it has become a standard way of doing things._” _[1]_ + +The _STIX Version 2.1 OASIS Standard_ [2] defines the Structured Threat Information eXpression (STIX) language using normative statements. Examples of these normative statements are *MUST*, *SHOULD*, *MAY*, etc. The STIX specification *MUST* normative statements must be followed, for the organization or implementation to be STIX compliant. However, adhering to best practices for statements such as *SHOULD* or *MAY* is usually voluntary (although a trust group might require it). Additionally, there are many other issues, such as data quality and interoperability that should not be included in a specification but are extremely important when sharing information. This guide suggests best practices to use for STIX content, both for some non-*MUST* normative statements and for considerations beyond the specification. + +There are two types of best practices as alluded to in the quote above: superior techniques as opposed to standard techniques. Sometimes a superior technique has been discovered and the best practice is a description of what to do and _why_. When a best practice describes a standard technique it often is an agreed-upon choice for something that could be done in a number of ways, _none of which is superior_. However, if all producers of content use the agreed-upon way, it supports interoperability. + +This guide is organized as follows: + +Section link:#general-best-practices-ideas[2] link:#general-best-practices-ideas[discusses] general ideas about interoperability best practices. + +Section link:#best-practices-for-general-stix-concepts[3] explores general STIX best practices. + +Section link:#heading=h.lnxbz9[4] examines best practices for common STIX types and properties. + +Sections link:#best-practices-for-sdos-and-sros[5] and link:#best-practices-for-scos[6] detail best practices for different STIX object types. + +Section link:#best-practices-for-patterns[7] covers indicator patterns. + +Section link:#best-practices-for-vocabularies-and-enumerations[8] discusses best practices for open vocabularies and enumerations. + +Section link:#best-practices-for-extensions[9] talks about best practices for STIX extensions. + +Section 10 explores other best practices. + +== *General Best Practices Ideas* +=== *Support Interoperability* + +The driving force behind the STIX standard is to support interoperability. If most STIX producers and consumers follow agreed upon best practices, interoperability will be more likely. + +The purpose of this supplemental document is to discuss guidelines that are inappropriate for inclusion in a specification but need to be considered. The STIX standard is defined independently of any specific storage or serialization method. Many of the best practices discussed in this document are suggestions for design and implementation of storage or serialization for tools that use STIX as their exchange language. + +Another document, the _STIX 2.1 Interoperability Test Document_ [3] sets the stage for more effortless sharing of Cyber Threat Intelligence (CTI) information expressed in STIX. However, that document defines the _minimal_ policies that can be used to determine if a STIX implementation or serialization is recognized as being "`interoperable.`" + +By following the combined guidelines from all three documents (The STIX standard, the STIX Interoperability Test Document, and this guide), STIX users can more freely share CTI information, by ignoring the underlying representation used by each producer and consumer. + +=== *Use Common Object Repositories* + +*Best Practice: Organizations should leverage common object repositories when preparing STIX content.* + +Many CTI entities are commonly used and having numerous, duplicate STIX objects representing the same concept has always been considered wasteful and problematic. Several decisions made when writing the STIX specification were aimed at avoiding duplication, which include: + +* specification defined instances of TLP data markings, +* kill chain phases referred to by their names, not as separate objects, and +* deterministic identifiers for STIX cyber-observable objects (SCOs). + +Having a publicly available repository of common CTI objects has always been on the "`wish list`" of members of the Organization for the Advancement of Structured Information Standards (OASIS) Cyber Threat Information Technical Committee (CTI-TC). + +MITRE currently maintains a repositoryfootnote:[https://github.com/mitre/cti] of STIX objects to represent both the ATT&CKfootnote:[https://attack.mitre.org/] and Common Attack Pattern Enumeration and Classification (CAPEC)footnote:[https://capec.mitre.org/] frameworks. This is an example of the case where organizations want to share their cyber threat intellectual property, as represented in STIX. + +However, there are other STIX objects that are general enough that they should be hosted in a common repository, defined once, and reused by the broader STIX community. The Homeland Security Systems Engineering & Development Institute (HSSEDI), with support of OASIS, has stood up such a repositoryfootnote:[https://github.com/oasis-open/cti-stix-common-objects] to help foster consistency across STIX threat-sharing efforts. By using this repository, the amount of data transmitted over the wire is reduced because only identifier references need to be shared. Maintainers of such repositories should avoid containing the same object as other repositories, but if they do, they must be an exact copy with the same UUID. + +Currently, the object types that are included in this repository are locations (e.g., countries) and identities (e.g., industry sectors). Vulnerability objects representing each Common Vulnerabilities and Exposures (CVE) are also found in the repository. Other types, like software (e.g., Microsoft Word – version x) or tools (e.g., Remote Desktop Protocol) could be added at a later time. + +Other object types may not be practical to store in such a repository. For instance, there are over four billion different IPv4 addresses; however, using deterministic identifiers, which renders SCO identifiers uniquely, is an alternative to storing such object instances in a common repository. + +=== *Avoid Deprecated and Reserved Terms* + +*Best Practice: Deprecated constructs and reserved terms should be avoided when creating STIX content.* + +The STIX 2.1 specification contains a few definitions that have been marked as deprecated. It is a best practice to avoid any construct that is deprecated. + +*Best Practice: STIX Cyber-Observable Objects (SCOs) should be used instead of the Cyber Observable Container.* + +With the introduction of STIX Cyber-Observable Objects (SCOs), the Cyber Observable Container from STIX 2.0 was deprecated, but remains in the STIX 2.1 specification for backwards-compatibility. It is a best practice to use SCOs and perhaps convert existing content in cyber observable containers to SCOs. + +In STIX 2.0, cyber observables were local to an observed data object. However, SCOs are top-level objects, so they are globally referable. One immediate advantage of this approach is that it reduces possible duplication of cyber observable data. This allows for the population of common SCOs in repositories that are available to a trust group or the entire user community, or the use of deterministic ids, as discussed in Section link:#deterministic-identifiers[4.3]. + +*Best Practice: The STIX Extension Definition mechanism should be used instead of the custom objects, custom properties, and custom extensions mechanism.* + +Custom properties, objects and extensions, described in Section 11 of the specification, have been deprecated, but remain in the STIX 2.1 specification for backwards-compatibility. The new Extension Definition facility is defined in Section 7.3 of the specification. + +*Best Practice: Existing custom objects, custom properties, and custom extensions should be converted to use the new STIX Extension Definition mechanism.* + +Because custom objects, custom properties, and custom extensions will no longer be supported in the next major release of the specification, it is best practice to convert the use of them to the STIX extensions as soon as possible. This might require the creation of an extension definition, which would need to be available to all consumers with whom this content will be shared. The extension definition could be stored in a common object repository so it is available for any consumer who receives such content. + +=== *Restrict Allowed Content within Trust Groups* + +*Best Practice: Trust groups can further restrict the allowed content that they consider valid.* + +A trust group is a group of consumers and producers that have an agreement (perhaps legal) on how to share STIX content. Trust groups can further restrict the allowed content that they consider valid, beyond what is found in the specification to meet their sharing requirements. For instance, a trust group might determine that deprecated content is not accepted. This would be enforced within the trust group. Many such choices are suggested in this document. + +== *Best Practices for General STIX Concepts* + +=== *Versioning* + +STIX objects might evolve over time—or contain incorrect or stale information—and need to be updated. One way to do this is to create a new version of an object. The version of an object is specified by three common properties: *id*, *modified* and *revoked*. Not all STIX objects have these properties, and as such _may_ not support versioningfootnote:[*id*, *modified* and *revoked* could be added as part of an extension]. An object can only be versioned by the object creator, as specified by the *created_by_ref* property. This is a strict restriction. Although others might notice that an object needs to be updated, they cannot create a new version. Options for this use case will be discussed later. + +Object creators may not want to create a new version of an object if it has changed significantly – which is called a _material change_. A material change can be thought of as one that changes the meaning of the object. For instance, if an indicator’s *pattern* property was changed to match a completely different SCO, this would be a material change, and versioning is not appropriate. However, if extra text was added to the *description* property to describe the indicator more fully, it would make sense to just create a new version of the object. Trust groups should specify when versioning is appropriate or not. + +*Best Practice: Discard non-current versions unless there is a need to be able to investigate the object’s history.* + +The specification defines the current version of an object as the one with the most recent timestamp contained in the *modified* property of the various versions. The specification contains no guidance for what to do with non-current versions. The best practice would be to discard non-current versions, unless there is a need to be able to investigate the object’s history. This is a product design issue. + +*Best Practice: If a consumer receives two objects that are different, but have the same identifier and modified timestamp, new objects should be created for both.* + +If a consumer receives two objects that are different but have the same id and modified timestamp, the best practice could be to create new objects for both, perhaps with additional text in the *description* property describing the duplication issue. Reusing existing UUIDs is not permitted as per the specification, unless it is a new version of the object. + +*Best Practice: When the content of an object is no longer valid, it should be revoked.* + +When the content of an object is no longer valid, it is best practice for the object creator to revoke it. + +*Best Practice: When a consumer receives a revoked version of an object, all versions of the object should be deleted.* + +When a consumer receives a revoked version of an object, the best practice would be to delete any versions of the object. Of course, this may not be possible if the full history of all objects is retained. Once again, this is a product design issue. + +*Best Practice: The "`derived-from`" relationship, Opinion object, or Note object should be used to update existing objects.* + +If a producer/consumer determines that an object contains information that should be updated, there are four options from which to choose. + +[arabic] +. Object creators have the option of creating a new version of the object if they determine a material change is not being made. +. Producers can create a new object with a new id that contains all of the correct information in the original object, plus any corrections or additions, and also introduce a relationship object between the original and new object of type "`derived-from`". Producers who are not the object creator of the original object cannot revoke it, according to the versioning rules in the specification. +. Producers who are not the object creator can use the Opinion object to comment on the content of the object. The *object_refs* property of the Opinion object should refer to the object that is being commented on. +. Producers who are not the object creator can enrich the content of an object via the use of the Note object. Once again, the *object_refs* property of the Note object should refer to the object that is being enriched. + +=== *Anonymization* + +*Best Practice: Create an anonymous Identity object rather than omitting the created_by_ref property.* + +The specification states that object creators should use the *created_by_ref* property to indicate who the creator is; however, there are many situations where the object creator chooses to remain anonymous. One way to do this is to omit the *created_by_ref* property. Unfortunately, consumers might not trust content when they don’t have any knowledge of who created the object. + +A best practice is to create an anonymous Identity object, which can then be used to populate the *created_by_ref* property. A trust group can maintain a mapping between the anonymized Identity and the true Identity of the object creator. Or, the Identity object might not be anonymized, but also not shared, but this is not a best practice. In both cases, a consumer can decide that a producer with that Identity reference is reliable, without needing to know their true identity. + +=== *Handling Dangling References* + +*Best Practice: Unless a reference refers to an object from a common repository, producers should attempt to avoid dangling references.* + +A best practice mentioned in section 2.3, was to make use of commonly defined objects from a common object repository to avoid sharing redundant information. In other situations, including an object that has been created by the producer should be included, if possible. Of course, there is an obvious trade-off between avoiding dangling references and transmitting additional objects in the bundle. + +*Best Practice: When a dangling reference is found, the producer of the content should be queried for the missing object.* + +The specification states that objects can contain references to other objects that have not been shared (called a "`dangling`" reference). In this case, the consumer should query the same producer for the missing object, but there is no guarantee that it will be available. Contact information should be available in the producer’s identity object (see section 3.4). + +=== *Defining and Using Identities* + +*Best Practice: Identity objects that are not anonymized should include contact information.* + +To support the resolving of dangling references, when appropriate, producers should use an Identity object that includes contact information. + +*Best Practice: All SDOs/SROs created by an object creator should contain the identifier of the object creator’s Identity object in the created_by_ref property.* + +Although the *created_by_ref* property is optional, it is a best practice to include it when creating an object. Anonymization can be handled using the methods described in section 3.2. The object creator is an important aspect of the versioning of STIX objects. Additionally, knowing the creator of an object could have an impact on the consumer’s confidence in the object. + +=== *Data Marking* + +*Best Practice: There is never a need to share a TLP Data Marking object.* + +As stated in the specification, Traffic Light Protocol (TLP) object instances should not be shared. The specification requires that all implementations of STIX must be aware of the TLP instances defined within the specification. Because all products that use STIX must know of these instances, there is no need to ever share them, so a producer should not include a TLP data marking in their content. + +*Best Practice: Ignore any TLP data marking object that is shared.* + +If a TLP data marking is encountered by a consumer in shared content, it might be an exact copy of what is found in the specification, or a TLP data marking object with a different identifier, or other different property values. Because data markings cannot be altered and the TLP markings in the specification are canonical, any TLP marking found in shared content should be ignored. If possible, any object that refers to the unofficial TLP marking should be replaced by the identifier from the specification. + +*Best Practice: Only provide data markings restricting the use of SCOs when necessary.* + +Data markings can be associated with any STIX object. As described in Section 7.2 of the specification, data markings are useful to represent restrictions, permissions, and other guidance for how data can be used and shared. They can also be used to indicate the intellectual property of the object, i.e., copyright or terms of use information. These uses are not necessarily useful for many of the SCO types, although not prohibited. For instance, there is no intellectual property associated with an IP address. The existence of all IP addresses is known; therefore, it makes no sense to restrict the sharing of an IP address SCO. However, a producer may want to provide guidance related to the fact that it has observed an IP address. For this use case, it is a best practice to add a data marking to the Observed Data object rather than the IP Address object. Alternatively, other SCO types might contain information for which guidance on its use might be needed (e.g., an Email Message SCO). + +=== *Bundles* + +*Best Practice: STIX Bundle objects should be treated as transitory objects rather than permanent objects.* + +As described in the specification document, a bundle is a container with no cyber threat intelligence semantics. It is a best practice to treat a bundle as a transitory object, therefore there is no rationale to implement them as a persistent object. + +*Best Practice: All STIX 2.0 objects should be upgraded to STIX 2.1 objects.* + +Bundles in STIX 2.1 are not version specific as they are in STIX 2.0. They may contain objects from different versions of STIX. How to persist objects of different versions is a product design issue, but it is a best practice to upgrade all STIX 2.0 objects to STIX 2.1 objects.footnote:[The stepper is an example of a reference implementation of the needed functionality – see https://github.com/oasis-open/cti-stix-elevator] + +*Best Practice: Include Identity objects referred to by other objects in the bundle.* + +As discussed in section 3.3, resolving a dangling reference can be possible by using the contact information of the producer of the bundle. Therefore, the producer’s Identity object should be contained in the bundle. Additionally, the bundle may include objects created by someone other than the producer, so the associated Identity objects should be included where possible. Trust groups can keep track of the producers of content in some way, which might obviate the need to always include the producer’s Identity object. + +== *Best Practices for Common Types and Common Properties* +=== *External References* + +*Best Practice: When possible, use consistent source names to identify external sources.* + +The source name of an external reference is used to identify the system, registry, organization, etc., which is the source of the reference. Consistent names should be used, especially when the external source is a commonly known registry. Examples are: capec, veris, mitre-attack, cwe, and cve. Trust groups may agree on an additional fixed set of source names. + +=== *Hashes* + +*Best Practice: SHA-256 should be used by content producers when generating a hash.* + +A hash in STIX is represented by the hashes type (Section 2.7 of the specification). It is a set of key/value pairs, where the key is the hash algorithm of the hash value. The hash algorithm value is selected from the open vocabulary hash-algorithm-ov. The inclusion of various hash algorithms supports SCOs, which capture observed data. Many of the included hash algorithms are no longer safe to use but may still be observed. However, when a hash is created by a content producer, it is a best practice to use a SHA-256 hash. A hash could be created by a producer for external references or artifacts. + +=== *Deterministic Identifiers* + +*Best Practice: Deterministic identifiers should be generated for SCOs using identifier contributing properties as defined in the specification to reduce the number of duplicate SCOs.* + +In Section 2.9 of the specification, it is recommended that UUIDv5 identifiers be used for STIX SCOs to reduce the number of duplicate SCOs that consumers must retain. The specification provides default rules for generating this UUIDv5. It is a best practice to use the identifier contributing properties as defined in the specification. + +Trust groups can use their own set of rules for generating UUIDv5 identifiers, assuming their content will not be shared outside the group. If it ever is, de-duplicating would be impaired. + +The algorithm for computing deterministic identifiers in the specification makes use of the identifier contributing properties listed for each SCO type. Because other properties do not play any role in creating the identifier, it is possible for more than one SCO to have the same identifier yet contain different information. How to proceed in this situation is a product design issue. + +*Best Practice: Deterministic identifiers are not always appropriate given the use case and the SCO type.* + +Although using deterministic identifiers (UUIDv5) can be useful to avoid having many different objects for the same cyber observable, it is not always the appropriate choice for an SCO. For instance, there is probably no reason to use a UUIDv4 identifier for an ipv4-address SCO, however, it could make sense for an email-message SCO because most email-message SCOs would contain unique information. In other situations, it often depends upon the use case. An example is a File SCO. In certain use-cases, the SCO represents an actual file, in others it is a placeholder for a file name. + +=== *Kill Chain Phases* + +It was decided that there would not be STIX objects for specifying kill chains and kill chain phases. In general, they have no extra information other than their names, and there are not that many different ones that are commonly referred to. Trust groups can define kill chains of their own if the generally known onesfootnote:[e.g., https://www.lockheedmartin.com/en-us/capabilities/cyber/cyber-kill-chain.html[Lockheed Martin Cyber Kill Chain]™ and http://attack.mitre.org/[MITRE ATT&CK]®] are not sufficient. + +=== *Timestamps* + +*Best Practice: When specifying the modified time for an object, the number of digits of sub-seconds that should be provided is three.* + +The specification of timestamps does not limit the number of digits of sub-seconds that can be provided, but it is generally assumed that the number should be between three and six digits. For the created and modified common properties, three digits are required but others are permitted. Because the modified date is used to determine the version of an object, it is a best practice to use exactly three digits. + +Other timestamps, such as those associated with Observed Data, might need additional precision. However, having more than nanosecond precision could cause interoperability issues, which are discussed in the specification. + +=== *Labels* + +*Best Practice: Labels should only be used for content that cannot be represented using other STIX properties.* + +Labels are used to share an aspect of a STIX object, but the terms used are not defined within the specification. Trust groups should agree on a fixed set of terms and their semantics. Labels can also be useful to mark STIX objects for a purpose internal to an organization or tool. For instance, how to display a STIX object in a tool’s interface might be the type of information that could be stored as a label. + +Care should be taken when choosing label names. Using a prefix to identify a producer or trust group might help avoid name collisions. Labels could have multiple parts – e.g., foo:bar:baz, for related labels. + +It is a best practice to use labels only for content that cannot be represented using the other properties defined in the specification. Additionally, using an extension might make more sense to express certain content. Lastly, data marking is the appropriate object type in STIX to use when representing issues such as shareability, ownership, sensitivity and other policies of the data. + +=== *Spec Version* + +*Best Practice: The spec_version property should be provided on SCOs.* + +For the sake of completeness, it is a best practice to include the *spec_version* property in all newly created SCOs. It is optional because SCOs did not exist in STIX 2.0. + +=== *Confidence* + +*Best Practice: STIX content should leverage a confidence scale that is selected from Appendix A of the STIX specification.* + +https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html#_1v6elyto0uqg[Appendix A of the specification] contains various commonly used confidence scales and their agreed upon conversion to a STIX Confidence Value. Trust groups should agree on the scale that is being used. It is best practice to choose one from Appendix A. + +=== *Best Practices for Optional Common Properties* + +*Best Practice: Each object should include a confidence score and external references to provide users of the information with valuable context.* + +Table 1 summarizes the best practices for including optional common properties when creating a STIX object. + +*Table 1: Optional Common Properties to Provide as a Best Practice* + +[width="100%",cols="50%,50%",options="header",] +|=== +|Property |Discussion +|confidence |Helpful for consumers to evaluate the usefulness of this object +|external_references |Supplement the object with relevant non-STIX formatted information +|=== + +== *Best Practices for SDOs and SROs* + +=== *Best Practices for Optional Properties* + +*Best Practice: Optional properties on STIX Domain Objects (SDOs) and STIX Relationship Objects (SROs) listed in Table 2 should be populated to make them more informative.* + +In general, the more properties populated on a STIX object, the more informative it will be. For various SDO and SRO types, Table 2 suggests those optional properties (at a minimum) it is a best practice to populate, if possible. See the specification for a full set of the optional properties for each object type. + +*Table 2: Optional Properties for each SDO to Provide as Best Practice* + +[width="100%",cols="50%,50%",options="header",] +|=== +|Type |Properties +|Campaign |*first_seen*, *objective* +|Course of Action |*description* +|Grouping |*description*, *name* +|Identity |*identity_class*, *sector* +|Incident |*description* +|Indicator |*indicator_type*, *kill_chain_phases* +|Infrastructure |*description*, *infrastructure_type*, *first_seen*, *kill_chain_phases* +|Intrusion Set |*first_seen*, *goals*, *primary_motivation* +|Malware |*capabilities*, *malware_types*, *operating_system_refs*, *sample_refs* +|Note |*authors* +|Observed Data |*first_observed* +|Opinion |*authors*, *explanation* +|Sighting |*first_seen*, *last_seen*, *where_sighted_refs* +|Threat Actor |*aliases*, *first_seen*, *goals*, *primary_motivation*, *threat_actor_type* +|=== + +=== *Attack Patterns* + +*Best Practice: STIX content that references ATT&CK or CAPEC should leverage the authoritative Attack Pattern objects.* + +There are several publicly available attack pattern registries. The two most well-known ones are ATT&CK, which describes the tactics and techniques used by adversaries to inform network defense based on cyber threat intelligence and CAPEC, which describes the common attributes and techniques used by adversaries to exploit weaknesses in applications. MITRE manages these registries and has provided the content of them as STIX objects. It is a best practice to use these instances, when referring to a CAPEC attack pattern or an ATT&CK technique. + +=== *Campaigns, Threat Actors, Groupings and Intrusion Sets* + +*Best Practice: The selection of the appropriate SDO to use should be made carefully.* + +These STIX objects are used to share inferred cyber threat data. They are usually created as part of cyber analysis. The following describes some best practices on how to use these different object types. + +For instance, during an analysis many different objects of interest may have been discovered while investigating a breach, but there they have no overarching story. However, the Grouping object is used to explicitly assert that they are associated with each other. If the named relationships between the objects in the grouping are not known, using a grouping object could be used as a way to avoid introducing many SROs. + +If one object has many of the same named relationships to a set of target objects (a one-to-many relationship), creating one SRO whose target is a grouping object that contains the set of target objects of the named relationship can be used to avoid introducing many SROs. + +Next, using this Grouping object, it might become possible to start developing the story behind them. What is the objective of all of this malicious activity? This is captured using the Campaign object. + +One of the most important aspects of cyber threat intelligence is determining who is responsible for the malicious activity. This is expressed using the Threat Actor object. Sharing a threat actor and its related objects can make others aware of the attack patterns, malware, and campaigns that they use. + +An intrusion set is a way to relate all of the adversarial behaviors and resources via one object. Unlike the Grouping object, the Intrusion Set objects give meaning and context to the set of objects. An Intrusion Set is a vetted collection of cyber threat information that enables the sharing of related knowledge. + +=== *Incidents* + +*Best Practice: Incident SDOs should include the core incident extension (extension-definition–ef765651-680c-498d-9894-99799f2fa126) to ensure robust incident reporting can be performed.* + +The STIX Incident SDO was created as a stub and the inclusion of this extension definition allows it to be used to consistently transmit complex Incident information that can be meaningfully analyzed and aggregated at scale consistently. + +All subsequent best practices for the Incident SDO are tied to the assumption that this extension is used. + +*Best Practice: Create derivative Incident SDOs to support sharing only public details while maintaining non-sharable data internally.* + +Many details of the incident response process are sensitive and not suitable for unfettered sharing. In these cases, a new Incident SDO can be authored with filtered information from the master Incident SDO, and then a Relationship from the new Incident to the master Incident should be created of type "`derived-from`". + +*Best Practice: Use external_references to correlate STIX Incident SDOs with internal systems.* + +Most incident tracking systems will not use STIX UUIDs and instead have their own identification scheme. These should be included in the *external_references* property of the Incident to allow for cross system correlation. Sharing this external_reference might be superfluous. + +*Best Practice: Record failed security controls using Courses of Action SDOs connected to the Incident using Relationships.* + +The Course of Action SDO can be used to define security controls that organizations can put in place based on industry standards and regulations. One key aspect in the analysis of security incidents across industries is to determine which controls have succeeded and failed. + +As such, recording key controls that are relevant to an incident which failed, were successful or not present helps to enhance future actions. The most effective way to accomplish this in STIX is by employing Relationships with types such as "`for-prevention-of`" or "`for-mitigation-of`" and then adding a label indicates the success or failure of the control between a CoA and Incident that can be: "`failed`", "`successful`", or "`not-attempted`" depending on the environment per the core incident extension documentation. + +The core incident extension’s documentation provides a list of additional common relationships for the Incident SDO and labels for relationships. It should be referred to for additional information. + +*Best Practice: Record observed data within the attacker_activities property of an Incident.* + +The *attacker_activities* property allows recording of the sequence, time span, outcome, goal, and attack pattern of attack activities along with the impacted infrastructure and technical observations made as part of this portion of the incident. + +By recording this information within an Incident it becomes far easier to perform timeline analysis against high level attack characteristics across multiple incidents even with incomplete information. It also becomes easier to trace down the impact of a series of incidents across an organization or sector. + +When possible, the usage of sequence information within attacker activities can be used to allow for fuzzy analysis and filtered sharing when specific timestamps are not available or should not be shared. + +*Best Practice: Record defender_activities associated with incident response within an Incident.* + +Recording key events in the *defender_activities* property allows a timeline to be shared between systems that are involved within the incident response process. Capturing these and sharing these in STIX can also ensure that an organization has complied with legally mandated reporting requirement timelines. + +*Best Practice: When recording attacker and defender activities set the relevant timestamp fidelity properties(s).* + +In general, incident response times are imprecise human entered values. It is very rare to have second level accuracy and in many cases events can only be accurately reported to the day they occurred. As such, providing a fidelity allows other analysts and systems to understand that the value is only accurate to a minute, hour, day or month. + +Systems that have users enter dates and times should automatically populate this property based on the input method used. A tool which only supports entering individual dates should have a fidelity of "`day`". + +This helps avoid confusion during later analysis, as without this present, some systems may determine based on sensor feed data that an incident response began before it was detected. + +*Best Practice: Provide estimated recovery times for systems using the is_projection flag property of the defender_activities property.* + +The defender activity sub-object includes the property is_projection. When set to true this indicates a future event, and is often used to communicate estimated recovery dates. This can be combined with the timestamp_fidelity property to allow a larger window for a projection. For example, recovery in this incident is projected by end of December 2023. + +\{ + +"`type`": "`incident`", + +"`name`": "`Server Room Fire`", + +"`description`": "`There was a fire in the server room.`", + +… + +"`extension-definition–ef765651-680c-498d-9894-99799f2fa126`": \{ + +"`extension_type`": "`property-extension`", + +"`investigation_status`": "`open`", + +"`determination`": "`successful-attempt`", + +"`defender_activities`": [ + +\{ + +"`activity_type`": "`discovery`", + +"`description`": "`The server room caught fire`" + +"`timestamp`": "`2023-10-15T06:00:00.000Z`", + +"`timestamp_fidelity`": "`day`", + +"`impacted_refs`": "`infrastructure–X`" + +}, + +\{ + +"`activity_type`": "`recovery-completed`", + +"`description`": "`Replacement equipment is expected to arrive and be installed by the end of December`", + +"`timestamp`": "`2023-12-01T06:00:00.000Z`", + +"`timestamp_fidelity`": "`month`", + +"`impacted_refs`": "`infrastructure–X`", + +"`is_projection`": true + +} + +] + +} + +} + +*Best Practice: Record "`none`" for confidentiality, integrity, and physical impacts if there is no impact. Record 0 for availability_impact if there is no availability impact.* + +Availability impact is an optional integer value, and the other three impact types allow zero or more impacts of each type to be recorded. If no value is present it only indicates that no information was provided, not that there was no impact. Recording zero for availability impact and "`none`" for the other impacts allows this to be communicated in an unambiguous manner. + +If there was some impact, but it does not affect an information type of particular note then this can also be specified. The following example lists no physical impacts, integrity impacts or availability impacts, but a confidentiality impact that does not include PII. + +\{ + +"`type`": "`incident`", + +"`name`": "`Financial Theft`", + +… + +"`extension-definition–ef765651-680c-498d-9894-99799f2fa126`": \{ + +"`extension_type`": "`property-extension`", + +"`investigation_status`": "`closed`", + +"`determination`": "`successful-attempt`", + +"`availability_impact`": 0, + +"`confidentiality_impacts`": [ + +\{ + +"`information_type`": "`financial`", + +"`loss_type`": "`confirmed-loss`" + +}, + +\{ + +"`information_type`": "`pii`", + +"`loss_type`": "`none`" + +} + +], + +"`integrity_impacts`": [ + +\{ + +"`alteration`": "`none`" + +} + +], + +"`physical_impacts`": [ + +\{ + +"`impact_type`": "`none`" + +} + +] + +} + +} + +=== *Infrastructure* + +*Best Practice: The Infrastructure object should be used to describe systems, software services, and any associated physical or virtual resources that are part of the offensive or defensive activity of an attack.* + +It is best practice to use an Infrastructure object to describe systems, software services, and any associated physical or virtual resources that are part of the offensive or defensive activity of an attack. Often such things can be described without the use of an Infrastructure object. For instance, a malware instance could be used by a server at particular IP address. It might be tempting to connect the malware instance to the IP address via a relationship of type "`uses.`" However, a best practice is to express this information through the use of an Infrastructure object. The following figure (from Appendix C of the specification) demonstrates the best practice for representing this content. + +.DiagramDescription automatically generated +image::data:image/png;base64,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[DiagramDescription automatically generated] + +*Figure 1. Example Best Practice* + +=== *Malware* + +*Best Practice: Use consistent Malware SDOs to represent families.* + +Malware can be used to represent both individual instances of malware as well as families of malware. To assist with graph analysis of STIX content, if your organization generates Malware SDOs to represent families it is best to ensure that the UUIDs of these SDOs are tracked and updated instead of authoring new Malware SDOs for the family each time a matching sample arrives. + +This ensures that consumers of your content can consistently update their representation of this family based on the STIX ID instead of having to fall back to the optional name or alias fields. + +*Best Practice: Create non-family Malware SDOs for samples that have relationships to their malware families instead of automatically updating the family’s SDO.* + +The STIX Malware SDO can represent both individual instances of a malware as well as families. When a malware analysis is performed that indicates that a sample comes from a family it can be useful to create a new Malware SDO that includes the sample in the *sample_refs* property along with other relevant information. + +A relationship of type "`variant-of`" should then be made from this new Malware SDO to the Malware SDO for the family as a whole. This allows samples to continue to be added to systems automatically without continuously re-authoring the Malware SDO for the family. + +By using new Malware SDOs instead of inserting these entries into the family’s sample_refs it becomes easier to avoid race conditions when handling large scale processing, allows Opinions to be provided on if individual samples belong to a family instead of against the family as a whole, and makes it easier to track how samples from a family have changed over time. + +=== *Malware Analysis* + +*Best Practice: When recording anti-virus results Malware Analysis should record the result_name of the finding if present and a result of "`malicious`", "`suspicious`", or "`unknown`" as appropriate. Only tools that use known files lists should ever report "`benign`".* + +Most anti-virus products assess if a file is believed to be malicious based on dynamic rules and heuristics. These methods cannot assert an application is safe only that the file does not appear to have malicious characteristics. As such, if a file is found to not be malicious it should be considered to be "`unknown`" not "`benign`". + +Some tools do work using known file lists. These lists can include known safe files and should assert a file is "`benign`" when appropriate. + +*Best Practice: Tools that perform static or dynamic analysis on malware to extract SCOs should record these results using analysis_sco_refs.* + +Malware Analysis pipelines are represented by chains of Malware Analysis SDOs where each one inputs a value found in the *sample_ref property* and outputs a value found in the *analysis_sco_refs* property that can in turn be analyzed by other tools in the pipeline. By ensuring inputs and outputs are mapped consistently, useful tooling can be easily determined and analysis information can be easily determined. + +*Best Practice: Use Malware Analysis when Indicators cannot be shared.* + +In many cases static rules such as Yara are essential for static analysis pipelines, but the content of the rules themselves are not shareable. Since the Indicator SDO requires sharing the rule signature, using Malware Analysis instead is a valid option. + +In these cases, the product should be listed as the name of the rules engine, for example "`yara`", and the result_name should be the name of the matching signature. + +=== *Opinions and Notes* + +*Best Practice: Opinions and Notes should not be used by the object creator.* + +Opinions are useful only to assess the correctness of information _provided by others_. Because the object creator can make changes to a STIX object, either by versioning it or by revoking it and creating a new correct object, an opinion object should never be used by an object creator to make an assessment about an object they created. + +As stated in the specification, opinions are subjective. Determining how to interpret them is therefore left to trust groups. + +As discussed in Section link:#versioning[3.1], Note objects are used for non-object creators to enrich the information of a STIX object. + +*Best Practice: Opinions should not be used for SCOs* + +An SCO represents "`facts`", so relating it to an Opinion object doesn’t make sense. However, there can be use cases for a Note object to be related to an SCO. + +*Best Practice: The authors property on a Note object should be used to indicate the individual or application that created the Note.* + +Using the *authors* property to indicate the individual or application that created the note or opinion is a best practice, because the *created_by_ref* property may refer to the author’s organization. + +=== *Observed Data* + +Observed Data objects are defined with semantics to support the matching of STIX Indicator patterns. The actual implementation of an Observed Data object will probably be product dependent, but they must always comply with specification requirements. For example, the SCOs contained or referred to must always form a connected SCO graph. + +A connected SCO graph must have at least one SCO, denoted as the "`root`" SCO, such that all other SCOs on the graph must be reachable from that root SCO using embedded relationships or SROs, ignoring the directionality of those relationships. + +In addition, all SCOs and SROs in the graph must be referenced in the *object_refs* property of the Observed Data object. SCOs and SROs that are not part of the complete graph must not be referenced in the *object_refs* property. Observed Data objects must not be used as containers for multiple unrelated SCOs. + +Matching Patterns to Observed Data objects will be discussed in more detail in Section link:#best-practices-for-patterns[7]. + +=== *Reports* + +*Best Practice: Report objects should be used to share the details of the investigation of an attack.* + +Often cyber security analysts perform an extensive investigation of a particular incident, campaign, etc., which is then published, often in a document. It is a best practice to use the Report object to share this information using STIX. The Report object is a comprehensive assessment, containing more information than just a Grouping or Intrusion Set. + +=== *Vulnerability* + +*Best Practice: Avoid duplicate Vulnerability objects to refer to a CVE.* + +CVE is the standard registry for vulnerabilities and is managed by NIST and MITRE. Most vulnerability objects will refer to an already registered CVE via the *external_references* property. The CVE entryfootnote:[See http://cve.mitre.org or http://nvd.nist.gov] itself contains many links to additional information related to the vulnerability, so it is a best practice to not duplicate them as external references in the Vulnerability object. Vulnerabilities based on CVE entries can be defined in a common object repository, as described in Section link:#use-common-object-repositories[2.3]. + +*Best Practice: Vulnerabilities without a CVE reference should be fully described in the description property including any external references that are available.* + +However, vulnerabilities can exist without being registered in CVE. For instance, a 0-day vulnerability can be represented in STIX, but without an external reference to a CVE entry. In these situations, a complete *description* property to describe the vulnerability or weakness is essential. If any external references are available, it is a best practice to include them. + +=== *Relationships* + +Standard relationship names defined in the specification should be used when possible. However, other relationship names are allowed. Trust groups should agree on a fixed set of relationship names and their semantics. + +Several common relationship names are mentioned in the specification. + +* derived-from +** Use if creating a new object from an existing one – _not for versioning_. +* duplicate-of +** A trust group should agree which is the duplicate – the source or the target. The name of this relationship implies if A is a duplicate-of B, then A is the extraneous object. However, this might be incorrect inference. +** *Best Practice: Duplicate objects should be merged into a single new object.* ++ +A best practice might be to merge the information in the duplicates by creating a new object. Care needs to be taken because other objects might refer to the source or target object. Once again, this is a product design issue. ++ +Assuming that the new object creator has not created the two original duplicates, a derived-from relationships could be created between the original objects and the new object. ++ +If the original objects are owned by the same object creator, that creator could make a new version of one of the original objects that contains the union of the information from both original objects, and revoke the other. +* related-to +** Use this relationship type if the semantics of the relationship are not fully defined or known. It is a best practice to use this type sparingly. It is preferable to have trust groups define additional, more specific relationship types for the group’s uses. + +=== *Sightings* + +*Best Practice: SDOs that you observe should be represented with a Sightings object whereas SCOs that you observe should be represented in Observed Data.* + +The only other type of SRO defined in the specification, beyond the generic Relationship object, is the Sighting object. The purpose of the Sighting object is not to indicate that an SCO has been seen. That fact should be represented using an Observed Data object. A Sighting object denotes the inference that some higher-level cyber threat object has been sighted. + +For instance, an Indicator pattern that has been shared is used to discover that some locally observed SCO is malicious. A Sighting object states that the Indicator has been "`sighted`" – using the *sighting_of_ref* property. The Observed Data object that the pattern matches is found in the *observed_data_refs* property. + +A more interesting example is to use a Sighting object to state that a threat actor has been "`sighted`" because of the existence of a particular file has been observed. + +*Best Practice: Although the object sighted should be an SDO, the related SCO should be included whenever possible.* + +Whenever possible (e.g., in cases where it doesn’t reveal sensitive or proprietary information) Sightings should include supporting Cyber Observable data via the *observed_data_refs* property. Such data can be valuable for various use cases, including to help consumers understand the context around the sighting and whether it’s something that they should care about or prioritize. For example, the sighting of a particular malware instance as a file on an endpoint may indicate that the malware is able to evade traditional anti-virus based defenses, whereas the sighting of the same malware instance as an email attachment would indicate a more traditional (and potentially less serious) propagation mechanism. + +*Best Practice: Changes to certain properties should not be viewed as a material change to the Sighting object.* + +Changes to properties that are expected to change regularly, for instance, *last_seen* and *count*, constitute non-material changes to a Sighting Object. + +*Best Practice: A Sighting with count=0 can be used to indicate a window of time when an SDO was not seen.* + +There are some specific cases where reporting the fact that a sighting was not seen can be useful. For example, if a provider has previously reported a sighting of an indicator but has not seen it in a day or week then reporting that it was not seen helps downstream systems to potentially clean up deployed rules that were updated based on active instances. This is especially important where downstream systems have limited space for active rules and they need to actively manage rules out.  + +*Best Practice: Because sightings may enable others to act more quickly on cyber threat intelligence, a best practice is that organizations submit and produce Sightings as frequently as possible.* + +The production of Sighting objects is largely dependent on the procedures and operational processes of the organization that is creating them and the trust group they belong to. In Table 3, we outline several possible frequencies for reporting Sightings, along with their pros and cons.  + +*Table 3*. Pros and cons of sighting frequencies** ** + +[width="100%",cols="<34%,<33%,<33%",options="header",] +|=== +|Frequency/Type |Pros |Cons +|Immediate/Daily  |May enable quicker response, especially to SDOs that may have shorter useful life spans such as Indicators  |Potentially high volume, depending on SDO  Some Sightings may be noise  Can impact usefulness with respect to correlation and reconstruction of sighted activity    +|Weekly  |Limits data size  Provides regular snapshot of current threats  |May not provide context for longer duration SDOs, such as Threat Actors and Campaigns  +|Monthly  |Balances short-term and long-term reporting  Provides historical context for longer duration SDOs, such as Campaigns and Threat Actors  |Time interval may be too long to be useful for SDOs with a limited lifespan, such as Indicators  +|Batch-based   (e.g., 100 sightings at a time)  |Reporting is more predictable  Effort is not expended on once-off sightings  |Waiting for a batch to fill may delay submission, negating the value of Sightings  One batch size may not suit all use cases  +|Fixed Frequency / Batch-based   (e.g., 100 sightings at a time OR at the end of the day, whichever comes first)  |Reporting is more predictable, less erratic  Submissions are not delayed (compared to pure batches)  |One batch size/frequency may not suit all use cases  +|=== + +== *Best Practices for SCOs* +=== *Best Practices for Optional Properties* + +*Best Practice: Optional properties on SCOs should be populated to make them more informative.* + +In general, the more properties populated on a STIX object, the more informative it will be. Most of the properties for each SCO type are optional. Some SCOs would be useless if few or none of the optional properties were populated. Therefore, it is important to populate as many properties as possible. In the following sections, certain properties will be explicitly mentioned as being important to populate as a best practice. + +=== *Artifacts* + +To specify the content of an artifact, two different properties are available; one, but not both, can be used. There are several factors involved to decide which method is better. It might make sense for a very large artifact to be shared by specifying its URL (which must be specified with the hash of the artifact found at that URL). + +However, when sharing smaller artifacts, the use of the *payload_bin* property might be more reliable because the URL might not be available (e.g. 404 status) or the internet might not be accessible. + +=== *Email Message* + +Almost all of the properties of the Email Message SCO are optional. If possible, a best practice is to populate optional properties such as *date*, *from_ref*, *to_refs, subject,* and *body* (or *body_multipart* if the message is a multipart). + +=== *Processes* + +*Best Practice: Specifying only the parent_ref property is sufficient* + +SCOs for processes have the properties *parent_ref* and *child_refs* to indicate their parent and child processes, respectively. However, the *child_refs* property is redundant. Therefore it is best practice to only populate the *parent_ref* property. This property is always known when a process is observed, and is sufficient to construct a tree of related processes. Additionally, it is difficult to maintain the correctness of both of these references because SCOs are not usually versioned. + +=== *Software* + +It is a best practice to populate either the *cpe* or *swid* property. To search for the appropriate Common Platform Enumeration (CPE), go to https://nvd.nist.gov/products/cpe/search. + +Very common instances of Software objects could be defined within a common object repository (e.g., Microsoft Word version x); however, having an object in this repository for every CPE entry is not considered practical. + +It might be possible for trust groups to agree to a subset of id contributing properties when creating the deterministic id for a software object. For instance, if it is agreed to use just *name*, *cpe* and *version*, it might be possible to avoid many duplicates. As with all deterministic ids, uniqueness cannot be guaranteed. + +Often, information like the CPE (or SWID) for a Software object might not be available, but the *name* and *version* property should always be specified, if at all possible. + +=== *User Account* + +The properties *user_id* and *account_login* can be confusing. The *account_login* property should hold the username that is specified when logging in or is the username part of an email address. The *user_id* is usually an internal indicator for an account (e.g., a UID on a Unix system). Sometimes these properties have the same value. In this case, it is a best practice to populate both. + +=== *Windows Registry Keys* + +The *key* property of a registry key object must be the full name of the key, including the hive. The hive must not be abbreviated, and the whole key should be expressed with the case preserved, as a best practice. + +== *Best Practices for Patterns* + +Pattern expressions are the core aspect of Indicator objects. The specification defines a new pattern language with semantics for matching Observed Data objects. Refer to Section 9 of the specification for more details about STIX patterns. + +Patterns using other languages, such as SNORT and YARA, are also allowed. For best practices for other languages, refer to their documentation. This section concerns only the STIX pattern language. + +It should be kept in mind that the Conformance section of the STIX specification discusses various levels of conformance for patterns (see section 12.7). The level of conformance chosen by a trust group may render many of the best practices discussed in this section superfluous. + +=== *Pattern Basics* + +A STIX pattern is an expression that can match one or more Observed Data instances. It contains multiple observation expressions conjoined using various operators, including the Boolean AND and OR. Each observation expression matches one Observed Data instance at a time. Note that STIX patterns are expressed in terms of SCO properties, but do not match SCOs that are not referred to within an Observed Data instance. + +Observable expressions are composed of comparison expressions conjoined using the Boolean AND and OR operators. Each individual comparison expression is used to match a single property of an SCO. The observable expression as a whole must be satisfied by a single SCO. The comparison expression itself has an operator to determine the kind of matching that takes place. The allowed operators are =, !=, >, <, >=, <=, IN, LIKE, MATCHES, ISSUBSET, ISSUPERSET, EXISTS. + +The left-hand side of a comparison expression is an object path. An object path is composed of the SCO type name, followed by one or more property names. The right-hand side of a comparison expression is always a constant.footnote:[The EXISTS operator is unary, with one object path operand.] + +As previously mentioned, all comparison expression operands of an AND observable expression must be limited to match the same type of SCO. Observable OR expressions can contain comparison expressions that match multiple SCO types; however, the matching semantics remain the same – it must match SCOs within one Observed Data object. + +When Observed Data objects have a deprecated container of cyber observables, all matches needed to be found in the container objects (the *objects* property). With the introduction of SCOs as a top-level object, all matching SCOs must be referred to in the *object_refs* property. + +For example: + +*\{* + +*"`type`": "`observed-data`",* + +*"`spec_version`": "`2.1`",* + +*"`id`": "`observed-data–b67d30ff-02ac-498a-92f9-32f845f448cf`",* + +*"`created_by_ref`": "`identity–f431f809-377b-45e0-aa1c-6a4751cae5ff`",* + +*"`created`": "`2016-04-06T19:58:16.000Z`",* + +*"`modified`": "`2016-04-06T19:58:16.000Z`",* + +*"`first_observed`": "`2015-12-21T19:00:00Z`",* + +*"`last_observed`": "`2015-12-21T19:00:00Z`",* + +*"`number_observed`": 50,* + +*"`object_refs`": [* + +*"`ipv4-address–efcd5e80-570d-4131-b213-62cb18eaa6a8`",* + +*"`domain-name–ecb120bf-2694-4902-a737-62b74539a41b`"* + +*]* + +*}* + +*\{* + +*"`type`": "`domain-name`",* + +*"`spec_version`": "`2.1`",* + +*"`id`": "`domain-name–ecb120bf-2694-4902-a737-62b74539a41b`",* + +*"`value`": "`example.com`",* + +*"`resolves_to_refs`": ["`ipv4-addr–efcd5e80-570d-4131-b213-62cb18eaa6a8`"]* + +*}* + +*\{* + +*"`type`": "`ipv4-addr`",* + +*"`spec_version`": "`2.1`",* + +*"`id`": "`ipv4-addr–efcd5e80-570d-4131-b213-62cb18eaa6a8`",* + +"`value`": "`198.51.100.3`" + +} + +would match this STIX pattern: + +*[domain-name:value = '`example.com`' AND domain-name.resolves_to_refs[*].value = '`198.51.100.3`']* + +Notice that the ipv4-addr SCO needed to be referred to within the *object_refs* property, otherwise this Observed Data object would not match the pattern even if the "`ipv4-addr–efcd5e80-570d-4131-b213-62cb18eaa6a8`" object existed. + +If the ipv4-addr object was contained, instead, in a different Observed Data object, then the following pattern would match: + +*[domain-name:value = '`example.com`'] AND [ip4-addr:value = '`198.51.100.3`'].* + +However, this pattern does not indicate that the two observed data objects are related. + +Observation Expressions can use a third operator – FOLLOWEDBY. This operator is similar to the AND operator, except the timestamp of the matching observation of the left operand needs to be less than the timestamp of the matching observation of the right operand. + +=== *Hints on How to Write a STIX Pattern* + +*Best Practice: STIX pattern expressions should be straightforward and not include more than a few observation expressions.* + +A STIX pattern expression can be arbitrarily complex, but it is a best practice to keep it relatively straightforward, not including more than a few observation expressions. Look for opportunities to simplify the pattern. + +==== *Pattern Simplification Tips* + +Here are some ways patterns may be simplified. + +* Drop redundant parentheses +* Apply commonly known Boolean simplifications to comparison expressions +* Apply Boolean simplifications to observation expressions: +** Drop redundant OR operands +** Reduce repetition by factoring out commonalities from ORs (does not work with ANDs) +** A OR (A AND B) = A +* Prefer IP address comparison expressions with ISSUBSET/ISSUPERSET and CIDR notation subnets, to long sequences of "`=`" comparisons to single IP addresses +[arabic, start=2] +. {blank} ++ +==== *Pattern Style Tips* + +These tips are intended to produce more understandable and correct patterns, without necessarily producing clearly "`simpler`" patterns. + +===== *Write the Pattern Right the First Time* + +* If the property is a list, use of the [] notation is needed. +** For example: ++ +.... +\[email-message:to\_refs\[\*\].value \= 'barney@abc.com' OR + + email-message:to\_refs\[\*\].value \= 'wilma@abc.com'\] +.... +** When checking for presence of a value in a list-valued property, use a single comparison expression with the "`*`" list index. It is possible to use integer indices but that would be unwieldy and imply either knowing the length of the list, or the order of values within it. +* For comparison expressions whose right-hand side contains a backslash (\), remember you need to escape the backslash (i.e., \\). In general, a JSON string must also escape a backslash. This leads to the need for four backslashes (\\\\) in pattern strings when in the context of JSON. Note, in Section 9 of the specification, which describes STIX patterns, the examples contain only two backslashes, because they are presented independent of the JSON context. +* An Observable Expression containing the OR operator is more natural for testing for the match of different values for the same property. See the following sections for more advice on OR expressions. ++ +For example: ++ +[ipv4-addr:value = '`219.90.112.203`' OR ipv4-addr:value = '`202.65.222.45`' OR ++ +ipv4-addr:value = '`219.90.112.197`' OR ipv4-addr:value = '`202.65.220.64`'] + +===== *Observation Expression Splits and Merges* + +The following describes how simple observation expressions may be merged or split, and a preference for which form should be used. + +====== *_Split vs Merged Equivalence_* + +Flexibility exists in how you express STIX criteria within a pattern when that pattern contains certain structure. For example, consider these two patterns: + +{empty}[domain-name:value = '`example.com`' OR ip4-addr:value = '`198.51.100.3`'] + +[domain-name:value = '`example.com`'] OR [ip4-addr:value = '`198.51.100.3`'] + +A simple observation OR expression, whose operands are comparison expressions, may be split into separate observation expressions. Also, two or more OR’d simple observation expressions may be combined into a single observation expression. + +This may not be intuitive since it appears as though the first pattern matches one observation, whereas the second matches two. What’s really happening is that the second pattern includes two sets of criteria. The STIX specification requires short-circuiting observation expression OR’s; therefore, the requirement is to find _one_ object that matches either set of criteria. This is the same thing expressed by the first pattern. Therefore, the two patterns are equivalent. + +====== *_Split vs Merged Preference_* + +If a simple observation expression contains comparison expression operands using different SCO types that are OR’d together, it is preferable to split the observation expression according to SCO type. For example, the observation expression: + +{empty}[ipv4-addr:value = '`219.90.112.203`' OR ipv4-addr:value = '`202.65.222.45`' OR + +ipv4-addr:value = '`219.90.112.197`' OR domain-name:value = '`example.com`' OR + +domain-name:value = '`abc.com`' OR file:name = '`foo.dll`'] + +should be split into three, according to the SCO types: + +{empty}[ipv4-addr:value = '`219.90.112.203`' OR ipv4-addr:value = '`202.65.222.45`' OR + +ipv4-addr:value = '`219.90.112.197`'] OR + +[domain-name:value = '`example.com`' OR domain-name:value = '`abc.com`'] OR + +[file:name = '`foo.dll`'] + +If a compound OR observation expression has operands whose comparison expressions are of homogenous and identical SCO type, they should be merged together. For example: + +{empty}[file:name = '`foo.dll`' AND file:parent_directory_ref.path = '`C:\\Windows\\System32`'] OR + +[file:size = 12345] + +Should be merged to: + +{empty}[(file:name = '`foo.dll`' AND file:parent_directory_ref.path = '`C:\\Windows\\System32`') OR + +file:size = 12345] + +*Best Practice: Simple observation expressions should be used to express SCO requirements and the criteria related to a single SCO type should be grouped together in the same observation expression.* + +The implication is that it is a best practice to prefer a simple observation expression to express SCO requirements related to a single SCO type. Another best practice is to prefer to keep the criteria related to a single SCO type together in the same observation expression. This nicely organizes observation criteria, according to SCO type. + +===== *IP Addresses and CIDR subnets* + +If IP addresses are formatted in standard ways, their equivalences and differences will be more obvious to both human and machine. + +* When using CIDR notation, zero out low-order bits +* Drop "`/32`" from IPv4 CIDR subnets and "`/128`" from IPv6 CIDR subnets and treat them as plain IP addresses +* Format IP address portions in standard ways, e.g., according to RFC 5952 for IPv6 addresses +[arabic, start=3] +. {blank} ++ +=== *Conformance Levels Can Influence How to Write a Pattern* + +As discussed above, there are three conformance levels defined in the STIX 2.1 specification. When it is possible to write a pattern in different ways, it is a best practice to write them using syntax from the lowest conformance level. For example, the OR operator need not be supported for level 1 compliance. However, for certain patterns the use of the IN comparison operator can be used instead to express the same pattern semantics. Therefore, to support interoperability, using the IN operator can make the pattern useful to more implementations. + +== *Best Practices for Vocabularies and Enumerations* + +=== *When to Add to an Open Vocabulary* + +*Best Practice: When using properties that leverage open vocabularies, the predefined values should be used.* + +Properties that contain values from open vocabularies do not have to contain values from the ones suggested in the specification. However, the use of other values can be an impediment to interoperability. + +Trust groups should agree on a fixed set of terms and their semantics for extra suggested values of an open vocabulary. + +It is a best practice to use the predefined values as much as possible and beyond that use only values agreed upon by your trust group. + +It is not necessary to use the Extension facility (see Section 7.3 of the specification) to add extra suggested values to an open vocabulary. + +== *Best Practices for Extensions* + +The definition of the objects in the STIX specification may not be rich enough to express all of the information that a producer needs to share. For this purpose, the specification contains a mechanism called an Extension Definition object, which can be used to define other content. + +*Best Practice: STIX Extensions should be defined as a JSON schema.* + +An Extension Definition object contains information that can be used to discover the additional properties and/or objects that it defines. It should be emphasized that an extension definition object does not necessarily completely define the extension itself but provides properties that contain references to the information that fully document and formally describe it. It is a best practice to use a JSON schema to formally describe the extension. + +*Best Practice: STIX Extensions should have a globally unique identifier, a description property that provides a detailed summary, an external reference to complete extension documentation, and a URL that points to the JSON schema.* + +It is a best practice to create an Extension Definition as follows: + +* A UUID that is used to uniquely specify the extension +* A description property to provide _summary_ information that conveys what the extension defines and how it is intended to be used +* An external reference to the complete documentation of the extension using the document style of the STIX specification, with examples +* A URL that points to the location of a JSON schema that defines the extension formally. This schema can then be used to enable automatic validation of extension uses + +As stated in Section link:#avoid-deprecated-and-reserved-terms[2], there is a deprecated way to express additional content – custom properties, objects and extensions, which should be avoided except for backwards compatibility. Notice that the deprecated customization facility does not provide any way to discover the syntax and semantics behind the custom content and therefore is less useful to support interoperability. + +=== *Naming properties and object types* + +*Best Practice: When creating a STIX Extension, objects and properties should use unique names that follow the naming rules defined in the STIX specification.* + +Because object and property names are usually scoped to a particular extension definition, the best practice is to follow the naming rules from the specification. If using the extension type toplevel-property-extension, property names could conflict if more than one such extension is in use for an object that uses the same property name. Additionally, future versions of STIX may use property names that are in conflict with such extensions. For this reason, it is best practice to use unique property names in this situation. + +== *Other Best Practices* +=== *Using Relationships to Make Inferences* + +The relationships explicitly mentioned in the specification provide a rich implicit ontology to make inferences, which can be used to answer questions or derive new information. It is a best practice to make use of this ontology and to share methodology at least within a trust group. + +For example: + +Is a Campaign targeting your industry sector or location? + +The specification explicitly supports the "`Campaign _targets_ identity, location, vulnerability`" types of relationships, therefore collecting all such known relationships and determining if the targeted identity indicates your industry sector, or targeted location encompasses your location is an obvious way to answer this question. + +However, there are many other "`targeting`" relationships discussed in the specification: + +* Attack-pattern _targets_ identity, location, vulnerability + +* Intrusion-set _targets_ targets identity, location, vulnerability + +* Malware targets _targets_ identity, location, vulnerability + +* Threat-actor _targets_ identity, location, vulnerability + +* Tool targets _targets_ identity, location, vulnerability + +If the campaign can be associated with one of these objects, it would enable other ways to answer this question. + +For instance, the relationship "`Campaign _uses_ attack-pattern, infrastructure, malware, tool`", can be used in conjunction with one of the _targets_ relationships above to determine the answer to this question. + +== *Closing Comments* + +STIX 2.1 is a new standard. This document discusses best practices that were noticed during the writing of the standard document, and the initial implementations of a few practitioners. As the use of STIX 2.1 grows, the community of users will discover many additional best practices. Other best practices might be found to be useless or misguided, or a better best practice for the situation might be discovered. These best practices should be either removed from the document or be deprecated. + +Therefore, this document should be considered an initial assessment of the best practices for expressing cyber threat information in STIX 2.1, and how to implement any applications that produce or consume said information. This document will be updated with best practices yet to be learned. + +== *References* + +[width="100%",cols="<50%,<50%",options="header",] +|=== +|[1] |Wikipedia, "`Best practice,`" Wikipedia Foundation, 20 December 2020 (last edited). [Online]. Available: https://en.wikipedia.org/wiki/Best_practice. [Accessed 5 March 2021]. +|[2] |Organization for the Advancement of Structured Information Standards (OASIS) , "`STIX Version 2.1 OASIS Standard,`" OASIS Open, 10 June 2021. [Online]. Available: https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html. [Accessed 4 April 2022]. +|[3] |Organization for the Advancement of Structured Information Standards (OASIS), "`STIX™ 2.1 Interoperability Test Document Version 1.0 Committee Specification Draft 01`" Available: https://docs.oasis-open.org/cti/stix-2.1-interop/v1.0/stix-2.1-interop-v1.0.html. [Accessed 4 April 2022] +|=== + +======= *List of Abbreviations* + +[width="100%",cols="<50%,<50%",options="header",] +|=== +|Abbreviation |Definition +|CAPEC |Common Attack Pattern Enumeration and Classification +|CISA |Cybersecurity and Infrastructure Security Agency +|CPE |Common Platform Enumeration +|CTI |Cyber Threat Intelligence +|CTI-TC |Cyber Threat Intelligence Technical Committee +|CTO |Chief Technology Officer +|CVE |Common Vulnerabilities and Exposures +|DHS |Department of Homeland Security +|FFRDC |Federally Funded Research And Development Center +|HSSEDI |Homeland Security Systems Engineering & Development Institute +|IP |Internet Protocol +|NIST |National Institute of Standards and Technology +|OASIS |Organization for the Advancement of Structured Information Standards +|SCO |STIX Cyber-observable Object +|SDO |STIX Domain Object +|SRO |STIX Relationship Object +|STIX |Structured Threat Information Expression +|TLP |Traffic Light Protocol +|=== + +== diff --git a/best-practices/css/stix.css b/best-practices/css/stix.css new file mode 100644 index 0000000..cabd122 --- /dev/null +++ b/best-practices/css/stix.css @@ -0,0 +1,459 @@ +/*Stylesheet for STIX specification derived from Asciidoctor default stylesheet */ +@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */ +html{font-family:sans-serif;-webkit-text-size-adjust:100%} +a{background:none} +a:focus{outline:thin dotted} +a:active,a:hover{outline:0} +h1{font-size:2em;margin:.67em 0} +b,strong{font-weight:bold} +abbr{font-size:.9em} +abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none} +dfn{font-style:italic} +hr{height:0} +mark{background:#ff0;color:#000} +code,kbd,pre,samp{font-family:monospace;font-size:1em} +pre{white-space:pre-wrap} +q{quotes:"\201C" "\201D" "\2018" "\2019"} +small{font-size:80%} +sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline} +sup{top:-.5em} +sub{bottom:-.25em} +img{border:0} +svg:not(:root){overflow:hidden} +figure{margin:0} +audio,video{display:inline-block} +audio:not([controls]){display:none;height:0} +fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em} +legend{border:0;padding:0} +button,input,select,textarea{font-family:inherit;font-size:100%;margin:0} +button,input{line-height:normal} +button,select{text-transform:none} +button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer} +button[disabled],html input[disabled]{cursor:default} +input[type=checkbox],input[type=radio]{padding:0} +button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0} +textarea{overflow:auto;vertical-align:top} +table{border-collapse:collapse;border-spacing:0} +*,::before,::after{box-sizing:border-box} +html,body{font-size:100%} +body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;line-height:1;position:relative;cursor:auto;-moz-tab-size:4;-o-tab-size:4;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased} +a:hover{cursor:pointer} +img,object,embed{max-width:100%;height:auto} +object,embed{height:100%} +img{-ms-interpolation-mode:bicubic} +.left{float:left!important} +.right{float:right!important} +.text-left{text-align:left!important} +.text-right{text-align:right!important} +.text-center{text-align:center!important} +.text-justify{text-align:justify!important} +.hide{display:none} +img,object,svg{display:inline-block;vertical-align:middle} +textarea{height:auto;min-height:50px} +select{width:100%} +.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em} +div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0} +a{color:#2156a5;text-decoration:underline;line-height:inherit} +a:hover,a:focus{color:#1d4b8f} +a img{border:0} +p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility} +p aside{font-size:.875em;line-height:1.35;font-style:italic} +h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#446CAA;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em} +h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0} +h1{font-size:2.125em} +h2{font-size:1.6875em} +h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em} +h4,h5{font-size:1.125em} +h6{font-size:1em} +hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em} +em,i{font-style:italic;line-height:inherit} +strong,b{font-weight:bold;line-height:inherit} +small{font-size:60%;line-height:inherit} +code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)} +ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit} +ul,ol{margin-left:1.5em} +ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0} +ul.circle{list-style-type:circle} +ul.disc{list-style-type:disc} +ul.square{list-style-type:square} +ul.circle ul:not([class]),ul.disc ul:not([class]),ul.square ul:not([class]){list-style:inherit} +ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0} +dl dt{margin-bottom:.3125em;font-weight:bold} +dl dd{margin-bottom:1.25em} +blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd} +blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)} +@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2} +h1{font-size:2.75em} +h2{font-size:2.3125em} +h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em} +h4{font-size:1.4375em}} +table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal} +table thead,table tfoot{background:#073763} +table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,00,.8);text-align:left} +table tr th{padding:.5625em .625em;font-size:inherit;color:rgba(255,255,255,.8)} +table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)} +table tr.even,table tr.alt{background:#f8f8f7} +table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6} +h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em} +h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400} +.center{margin-left:auto;margin-right:auto} +.stretch{width:100%} +.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table} +.clearfix::after,.float-group::after{clear:both} +:not(pre).nobreak{word-wrap:normal} +:not(pre).nowrap{white-space:nowrap} +:not(pre).pre-wrap{white-space:pre-wrap} +:not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed} +pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed} +pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit} +pre>code{display:block} +pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal} +em em{font-style:normal} +strong strong{font-weight:400} +.keyseq{color:rgba(51,51,51,.8)} +kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;border-radius:3px;box-shadow:0 1px 0 rgba(0,0,0,.2),inset 0 0 0 .1em #fff;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap} +.keyseq kbd:first-child{margin-left:0} +.keyseq kbd:last-child{margin-right:0} +.menuseq,.menuref{color:#000} +.menuseq b:not(.caret),.menuref{font-weight:inherit} +.menuseq{word-spacing:-.02em} +.menuseq b.caret{font-size:1.25em;line-height:.8} +.menuseq i.caret{font-weight:bold;text-align:center;width:.45em} +b.button::before,b.button::after{position:relative;top:-1px;font-weight:400} +b.button::before{content:"[";padding:0 3px 0 2px} +b.button::after{content:"]";padding:0 2px 0 3px} +p a>code:hover{color:rgba(0,0,0,.9)} +#header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em} +#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table} +#header::after,#content::after,#footnotes::after,#footer::after{clear:both} +#content{margin-top:1.25em} +#content::before{content:none} +#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0} +#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf} +#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px} +#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap} +#header .details span:first-child{margin-left:-.125em} +#header .details span.email a{color:rgba(0,0,0,.85)} +#header .details br{display:none} +#header .details br+span::before{content:"\00a0\2013\00a0"} +#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)} +#header .details br+span#revremark::before{content:"\00a0|\00a0"} +#header #revnumber{text-transform:capitalize} +#header #revnumber::after{content:"\00a0"} +#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem} +#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em} +#toc>ul{margin-left:.125em} +#toc ul.sectlevel0>li>a{font-style:italic} +#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0} +#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none} +#toc li{line-height:1.3334;margin-top:.3334em} +#toc a{text-decoration:none} +#toc a:active{text-decoration:underline} +#toctitle{color:#446CAA;font-size:1.2em} +@media screen and (min-width:768px){#toctitle{font-size:1.375em} +body.toc2{padding-left:15em;padding-right:0} +#toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto} +#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em} +#toc.toc2>ul{font-size:.9em;margin-bottom:0} +#toc.toc2 ul ul{margin-left:0;padding-left:1em} +#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em} +body.toc2.toc-right{padding-left:0;padding-right:15em} +body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}} +@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0} +#toc.toc2{width:20em} +#toc.toc2 #toctitle{font-size:1.375em} +#toc.toc2>ul{font-size:.95em} +#toc.toc2 ul ul{padding-left:1.25em} +body.toc2.toc-right{padding-left:0;padding-right:20em}} +#content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px} +#content #toc>:first-child{margin-top:0} +#content #toc>:last-child{margin-bottom:0} +#footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em} +#footer-text{color:hsla(0,0%,100%,.8);line-height:1.44} +#content{margin-bottom:.625em} +.sect1{padding-bottom:.625em} +@media screen and (min-width:768px){#content{margin-bottom:1.25em} +.sect1{padding-bottom:1.25em}} +.sect1:last-child{padding-bottom:0} +.sect1+.sect1{border-top:1px solid #e7e7e9} +#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400} +#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em} +#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible} +#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none} +#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221} +details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em} +details{margin-left:1.25rem} +details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent} +details>summary::-webkit-details-marker{display:none} +details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)} +details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)} +details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem} +.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic} +table.tableblock.fit-content>caption.title{white-space:nowrap;width:0} +.paragraph.lead>p,#preamble>.sectionbody>[class=paragraph]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)} +.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%} +.admonitionblock>table td.icon{text-align:center;width:80px} +.admonitionblock>table td.icon img{max-width:none} +.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase} +.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere} +.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0} +.exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px} +.exampleblock>.content>:first-child{margin-top:0} +.exampleblock>.content>:last-child{margin-bottom:0} +.sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px} +.sidebarblock>:first-child{margin-top:0} +.sidebarblock>:last-child{margin-bottom:0} +.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center} +.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0} +.literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em} +@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}} +@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}} +.literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8} +.literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)} +.listingblock>.content{position:relative} +.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5} +.listingblock:hover code[data-lang]::before{display:block} +.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5} +.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"} +.listingblock pre.highlightjs{padding:0} +.listingblock pre.highlightjs>code{padding:1em;border-radius:4px} +.listingblock pre.prettyprint{border-width:0} +.prettyprint{background:#f7f7f8} +pre.prettyprint .linenums{line-height:1.45;margin-left:2em} +pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0} +pre.prettyprint li code[data-lang]::before{opacity:1} +pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none} +table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none} +table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal} +table.linenotable td.code{padding-left:.75em} +table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none} +pre.pygments span.linenos{display:inline-block;margin-right:.75em} +.quoteblock{margin:0 1em 1.25em 1.5em;display:table} +.quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em} +.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify} +.quoteblock blockquote{margin:0;padding:0;border:0} +.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)} +.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0} +.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right} +.verseblock{margin:0 1em 1.25em} +.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans-serif;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility} +.verseblock pre strong{font-weight:400} +.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex} +.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic} +.quoteblock .attribution br,.verseblock .attribution br{display:none} +.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)} +.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none} +.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0} +.quoteblock.abstract{margin:0 1em 1.25em;display:block} +.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center} +.quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf} +.quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0} +.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem} +.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0} +p.tableblock:last-child{margin-bottom:0} +td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere} +td.tableblock>.content>:last-child{margin-bottom:-1.25em} +table.tableblock,th.tableblock,td.tableblock{border:0 solid #073763} +table.grid-all>*>tr>*{border-width:1px} +table.grid-cols>*>tr>*{border-width:0 1px} +table.grid-rows>*>tr>*{border-width:1px 0} +table.frame-all{border-width:1px} +table.frame-ends{border-width:1px 0} +table.frame-sides{border-width:0 1px} +table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0} +table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0} +table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0} +table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0} +table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#073763} +th.halign-left,td.halign-left{text-align:left} +th.halign-right,td.halign-right{text-align:right} +th.halign-center,td.halign-center{text-align:center} +th.valign-top,td.valign-top{vertical-align:top} +th.valign-bottom,td.valign-bottom{vertical-align:bottom} +th.valign-middle,td.valign-middle{vertical-align:middle} +table thead th,table tfoot th{font-weight:bold} +tbody tr th{background:#073763; color:#FFFFFF} +tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold} +p.tableblock>code:only-child{background:none;padding:0} +p.tableblock{font-size:1em} +ol{margin-left:1.75em} +ul li ol{margin-left:1.5em} +dl dd{margin-left:1.125em} +dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0} +li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em} +ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none} +ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em} +ul.unstyled,ol.unstyled{margin-left:0} +li>p:empty:only-child::before{content:"";display:inline-block} +ul.checklist>li>p:first-child{margin-left:-1em} +ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em} +ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em} +ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em} +ul.inline>li{margin-left:1.25em} +.unstyled dl dt{font-weight:400;font-style:normal} +ol.arabic{list-style-type:decimal} +ol.decimal{list-style-type:decimal-leading-zero} +ol.loweralpha{list-style-type:lower-alpha} +ol.upperalpha{list-style-type:upper-alpha} +ol.lowerroman{list-style-type:lower-roman} +ol.upperroman{list-style-type:upper-roman} +ol.lowergreek{list-style-type:lower-greek} +.hdlist>table,.colist>table{border:0;background:none} +.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none} +td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em} +td.hdlist1{font-weight:bold;padding-bottom:1.25em} +td.hdlist2{word-wrap:anywhere} +.literalblock+.colist,.listingblock+.colist{margin-top:-.5em} +.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top} +.colist td:not([class]):first-child img{max-width:none} +.colist td:not([class]):last-child{padding:.25em 0} +.thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd} +.imageblock.left{margin:.25em .625em 1.25em 0} +.imageblock.right{margin:.25em 0 1.25em .625em} +.imageblock>.title{margin-bottom:0} +.imageblock.thumb,.imageblock.th{border-width:6px} +.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em} +.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0} +.image.left{margin-right:.625em} +.image.right{margin-left:.625em} +a.image{text-decoration:none;display:inline-block} +a.image object{pointer-events:none} +sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super} +sup.footnote a,sup.footnoteref a{text-decoration:none} +sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline} +#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em} +#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0} +#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em} +#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em} +#footnotes .footnote:last-of-type{margin-bottom:0} +#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0} +div.unbreakable{page-break-inside:avoid} +.big{font-size:larger} +.small{font-size:smaller} +.underline{text-decoration:underline} +.overline{text-decoration:overline} +.line-through{text-decoration:line-through} +.aqua{color:#00bfbf} +.aqua-background{background:#00fafa} +.black{color:#000} +.black-background{background:#000} +.blue{color:#0000bf} +.blue-background{background:#0000fa} +.fuchsia{color:#bf00bf} +.fuchsia-background{background:#fa00fa} +.gray{color:#606060} +.gray-background{background:#7d7d7d} +.green{color:#006000} +.green-background{background:#007d00} +.lime{color:#00bf00} +.lime-background{background:#00fa00} +.maroon{color:#600000} +.maroon-background{background:#7d0000} +.navy{color:#000060} +.navy-background{background:#00007d} +.olive{color:#606000} +.olive-background{background:#7d7d00} +.purple{color:#600060} +.purple-background{background:#7d007d} +.red{color:#bf0000} +.red-background{background:#fa0000} +.silver{color:#909090} +.silver-background{background:#bcbcbc} +.teal{color:#006060} +.teal-background{background:#007d7d} +.white{color:#bfbfbf} +.white-background{background:#fafafa} +.yellow{color:#bfbf00} +.yellow-background{background:#fafa00} +span.icon>.fa{cursor:default} +a span.icon>.fa{cursor:inherit} +.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default} +.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c} +.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111} +.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900} +.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400} +.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000} +.conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold} +.conum[data-value] *{color:#fff!important} +.conum[data-value]+b{display:none} +.conum[data-value]::after{content:attr(data-value)} +pre .conum[data-value]{position:relative;top:-.125em} +b.conum *{color:inherit!important} +.conum:not([data-value]):empty{display:none} +dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility} +h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em} +p strong,td.content strong,div.footnote strong{letter-spacing:-.005em} +p,blockquote,dt,td.content,span.alt,summary{font-size:1.0625rem} +p{margin-bottom:1.25rem} +.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em} +.exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc} +.print-only{display:none!important} +@page{margin:1.25cm .75cm} +@media print{*{box-shadow:none!important;text-shadow:none!important} +html{font-size:80%} +a{color:inherit!important;text-decoration:underline!important} +a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important} +a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em} +abbr[title]{border-bottom:1px dotted} +abbr[title]::after{content:" (" attr(title) ")"} +pre,blockquote,tr,img,object,svg{page-break-inside:avoid} +thead{display:table-header-group} +svg{max-width:100%} +p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3} +h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid} +#header,#content,#footnotes,#footer{max-width:none} +#toc,.sidebarblock,.exampleblock>.content{background:none!important} +#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important} +body.book #header{text-align:center} +body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em} +body.book #header .details{border:0!important;display:block;padding:0!important} +body.book #header .details span:first-child{margin-left:0!important} +body.book #header .details br{display:block} +body.book #header .details br+span::before{content:none!important} +body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important} +body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always} +.listingblock code[data-lang]::before{display:block} +#footer{padding:0 .9375em} +.hide-on-print{display:none!important} +.print-only{display:block!important} +.hide-for-print{display:none!important} +.show-for-print{display:inherit!important}} +@media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem} +.sect1{padding:0!important} +.sect1+.sect1{border:0} +#footer{background:none} +#footer-text{color:rgba(0,0,0,.6);font-size:.9em}} +@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}} +/* Custom styles for STIX */ +.stixtype{font-family:Consolas;color:#C7254E;background:#F9F2F4} +.stixliteral{font-family:Consolas;color:#073763; background:#CFE2F3} +.stixrelationship{font-family:Consolas;color:#073763;background:#CFE2F3} +.stixtitle{margin-top:0in; + margin-right:0in; + margin-bottom:12.0pt; + margin-left:0in; + line-height:115%; + page-break-after:avoid; + font-size:18.0pt; + font-family:"Arial",sans-serif; + color:#446CAA; + font-weight:bold;} +.stixsubtitle{margin-top:0in; + margin-right:0in; + margin-bottom:12.0pt; + margin-left:0in; + line-height:115%; + page-break-after:avoid; + font-size:14.0pt; + font-family:"Arial",sans-serif; + color:#446CAA; + font-weight:bold;} +.stixvocab{font-family:Consolas;color:#C7254E;background:#F9F2F4;text-decoration:underline;} +.stixalt{font-family:Consolas;color:black;background:#EFEFEF} +.stixtr{color:#FFFFFF} +/*.stixreq{color:#F4CCCC}*/ +.stixreq{color:#bf0000} +/*.stixopt{color:#FFF2CC}*/ +.stixopt{color:#446CAA} +/*.stixna{color:#D9D9D9}*/ +.stixna{color:#909090} diff --git a/best-practices/images/oasis-logo.png b/best-practices/images/oasis-logo.png new file mode 100644 index 0000000000000000000000000000000000000000..c8fa8a67be35b233db121a05a07297840ca91ffa GIT binary patch literal 12402 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