Skip to content

Latest commit

 

History

History
173 lines (108 loc) · 9.79 KB

README.rst

File metadata and controls

173 lines (108 loc) · 9.79 KB
Raw

If you are having issues cloning this repository, see these instructions for alternatives.

Introduction

NOTE: This is an OASIS TC Open Repository. See the Governance section below for more information.

This repository contains commonly used STIX 2.1 objects that can be used by STIX content producers and consumers.

Using these objects, instead of each producer creating their own, will reduce the number of duplicates shared and enable producers to share information using just the identifier reference of these common objects. Consumers can incorporate these object instances locally in order to resolve those identifiers.

Contributions are encouraged via a pull request and will be vetted by the repository maintainers until a more formal process is put in place. Please enter an issue on GitHub for bugs and feature requests.

The following describes the contents of the repository and how to query and manipulate it.

STIX 2.1 is expressed using JSON, which can be easily consumed using Python or other programming languages. If you are using Python, the python-stix2 library can help you work with the content as shown in the examples below.

What type of STIX content can be found in this repository

The current objects were created via a script found at generate_common_objects.py.

Location objects

  • All countries (compiled from Python pycountry package)
  • All US States (constant in script)
  • All Canadian Provinces (constant in script)
  • All regions in region-ov

Identity objects

Vulnerability objects

  • All “published” CVEs (updated daily). As of December 2023, there are over 200,000 objects.

Using Python and STIX 2.1

In this section, we will describe how to query and manipulate STIX that has been retrieved from this repository using Python. Other programming languages can also be used.

A Python library has been created for using and creating STIX 2.1 content. This library abstracts storage and transport details so that the same code can be used to interact with data locally on the filesystem or in memory, or remotely via TAXII. The source code, installation instructions, and basic documentation for the library can be found here. There is a more thorough API documentation as well.

There is currently no TAXII server set up to distribute the content in this repository.

Python Library

To begin querying STIX 2.1 data, you must first have a DataSource. For these examples, we will simply use a FileSystemSource.

The repository contents must first be cloned or downloaded from GitHub.

Creating a DataStore

Once the stix2 Python library is installed and the content is acquired, we need to open the DataStore for querying:

from stix2 import FileSystemSource
fs = FileSystemSource('./cti-stix-common-objects/objects')

For a production system, a DataStore to process objects from Github that integrates with your implemenation is suggested.

Querying

To perform a query, we must define a Filter. As of this writing, a filter must, at a minimum, specify object id's or an object type. The following filter can be used to retrieve all CVE Vulnerabilities:

from stix2 import Filter
filter = Filter('type', '=', 'vulnerability')

Once this filter is defined, you can pass it to the DataSource query function in order to actually query the data:

vulnerabilities = fs.query([filter])

This query will process over 200,000 objects, which takes serveral minutes.

Notice that the query function takes a list of filters. These filters are logically AND'd together during the query.

For the remaining examples, the imports and the FileSystemStore initialization will be omitted.

Get the Location object for a country

In this example, the country name must be passed into the function. Here we query for the Location object for France.

def get_location_for_country(store, country_name):
    filter = [
        Filter('type', '=', 'location'),
        Filter('name', '=', country_name),
    ]
    return store.query(filter)

get_location_for_country(fs, "France")

Get the latest Vulnerability objects

Here we query for all of Vulnerability objects added after midnight on 2/28/2021.

def get_new_vulnerabilities(store, added_after_date):
    filter = [
        Filter('type', '=', 'vulnerability'),
        Filter("created", ">=", added_after_date)
    ]
    return store.query(filter)

get_new_vulnerabilities(fs, "2021-02-28T00:00:00.000Z")

Governance

This GitHub public repository cti-stix-common-objects was created at the request of the OASIS Cyber Threat Intelligence (CTI) TC as an OASIS TC Open Repository to support development of open source resources related to Technical Committee work.

While this TC Open Repository remains associated with the sponsor TC, its development priorities, leadership, intellectual property terms, participation rules, and other matters of governance are separate and distinct from the OASIS TC Process and related policies.

All contributions made to this TC Open Repository are subject to open source license terms expressed in BSD-3-Clause License. That license was selected as the declared Applicable License when the TC voted to create this Open Repository.

As documented in Public Participation Invited, contributions to this TC Open Repository are invited from all parties, whether affiliated with OASIS or not. Participants must have a GitHub account, but no fees or OASIS membership obligations are required. Participation is expected to be consistent with the OASIS TC Open Repository Guidelines and Procedures, the open source LICENSE.md designated for this particular repository, and the requirement for an Individual Contributor License Agreement that governs intellectual property.

Maintainers

The current maintainers of this TC Open Repository are:

TC Open Repository maintainers are responsible for oversight of this project's community development activities, including evaluation of GitHub pull requests and preserving open source principles of openness and fairness. Maintainers are recognized and trusted experts who serve to implement community goals and consensus design preferences.

Initially, the TC members designated one or more persons to serve as Maintainer(s); subsequently, participating community members may select additional or substitute Maintainers by consensus agreement.

About OASIS TC Open Repositories

Feedback

Questions or comments about this TC Open Repository's activities should be composed as GitHub issues or comments. If use of an issue/comment is not possible or appropriate, questions may be directed by email to the Maintainer(s) listed above. Please send general questions about TC Open Repository participation to OASIS Staff at [email protected] and any specific CLA-related questions to [email protected].