If you are having issues cloning this repository, see these
instructions <https://github.com/oasis-open/cti-stix-common-objects/blob/main/cloning-help.rst/>
_
for alternatives.
NOTE: This is an OASIS TC Open Repository <https://www.oasis-open.org/resources/open- repositories/>
.
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 <https://github.com/oasis-open/cti-python-stix2>
_ library can help you work with the content as shown in the examples below.
The current objects were created via a script found at generate_common_objects.py <scripts/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 <https://docs.oasis-open.org/cti/stix/v2.1/cs02/stix-v2.1-cs02.html#_i1sw27qw1v0s>`_
Identity objects
OASIS <objects/identity/identity--8ce3f695-d5a4-4dc8-9e93-a65af453a31a.json>
_)industry-sector-ov <https://docs.oasis-open.org/cti/stix/v2.1/cs02/stix-v2.1-cs02.html#_oogrswk3onck>
_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 <https://oasis-open.github.io/cti-documentation/taxii/intro>`_.
The source code, installation instructions, and basic documentation for the library can be found `here <https://github.com/oasis-open/cti-python-stix2>`_.
There is a more thorough `API documentation <http://stix2.readthedocs.io/en/latest/overview.html>`_ 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 <http://stix2.readthedocs.io/en/latest/guide/datastore.html>
.
For these examples, we will simply use a FileSystemSource <http://stix2.readthedocs.io/en/latest/guide/filesystem.html>
.
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:
.. code-block:: python
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 <http://stix2.readthedocs.io/en/latest/guide/datastore.html#Filters>
_. 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:
.. code-block:: python
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:
.. code-block:: python
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.
.. code-block:: python
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.
.. code-block:: python
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")
This GitHub public repository cti-stix-common-objects <https://github.com/oasis-open/cti-stix-common-objects>
was created at the request of the OASIS Cyber Threat Intelligence (CTI) TC <https://www.oasis-open.org/committees/cti/>
as an OASIS TC Open Repository <https://www.oasis-open.org/resources/open-repositories/>
_ 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 <https://www-legacy.oasis-open.org/sites/www.oasis-open.org/files/BSD-3-Clause.txt>
. That license was selected as the declared Applicable License <https://www.oasis-open.org/resources/open-repositories/licenses>
when the TC voted to create this Open Repository.
As documented in Public Participation Invited <https://github.com/oasis-open/cti-stix-common-objects/blob/master/CONTRIBUTING.md#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 <https://www.oasis-open.org/policies-guidelines/open-repositories>
, the open source LICENSE.md <LICENSE.md>
designated for this particular repository, and the requirement for an Individual Contributor License Agreement <https://cla-assistant.io/oasis-open/Open-Repo-admin>
that governs intellectual property.
Maintainers
The current maintainers of this TC Open Repository are:
- `Emily Ratliff <mailto:Emily.Ratliff@ibm.com>`__; GitHub ID:
https://github.com/ejratl; WWW: `IBM <http://www.ibm.com/>`__
- `Rich Piazza <mailto:rpiazza@mitre.org>`__; GitHub ID:
https://github.com/rpiazza; WWW: `MITRE <http://www.mitre.org/>`__
TC Open Repository `maintainers <https://www.oasis-open.org/resources/open-repositories/maintainers-guide>`_ are responsible for oversight of this project's community development activities, including evaluation of GitHub `pull requests <https://github.com/oasis-open/cti-stix-common-objects/blob/master/CONTRIBUTING.md#fork-and-pull-collaboration-model>`_ and `preserving <https://www.oasis-open.org/policies-guidelines/open-repositories#repositoryManagement>`_ 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 <https://www.oasis-open.org/resources/open-repositories/maintainers-guide#additionalMaintainers>`_.
About OASIS TC Open Repositories
TC Open Repositories: Overview and Resources <https://www.oasis-open.org/resources/open-repositories/>
_Frequently Asked Questions <https://www.oasis-open.org/faq-tc-repo/>
_Open Source Licenses <https://www.oasis-open.org/resources/open-repositories/licenses>
_Maintainers' Guidelines and Agreement <https://www.oasis-open.org/resources/open-repositories/maintainers-guide>
_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 `repository-admin@oasis-open.org <mailto:repository-admin@oasis-open.org>`_ and any specific CLA-related questions to `repository-cla@oasis-open.org <mailto:repository-cla@oasis-open.org>`_.