From 3420bb3493968b88f31d69269f84186a26fdd4fd Mon Sep 17 00:00:00 2001 From: Greg Back Date: Wed, 19 Jul 2017 22:04:54 +0000 Subject: [PATCH] Convert README to ReStructuredText --- README.md | 248 ----------------------------------------------- README.rst | 278 +++++++++++++++++++++++++++++++++++++++++++++++++++++ setup.py | 2 +- 3 files changed, 279 insertions(+), 249 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/README.md b/README.md deleted file mode 100644 index aad8c5e..0000000 --- a/README.md +++ /dev/null @@ -1,248 +0,0 @@ -[![Build Status](https://travis-ci.org/oasis-open/cti-python-stix2.svg?branch=master)](https://travis-ci.org/oasis-open/cti-python-stix2) -[![codecov](https://codecov.io/gh/oasis-open/cti-python-stix2/branch/master/graph/badge.svg)](https://codecov.io/gh/oasis-open/cti-python-stix2) - -# cti-python-stix2 - -*This is an [OASIS Open Repository](https://www.oasis-open.org/resources/open-repositories/). See the [Governance](#governance) section for more information.* - -This repository provides Python APIs for serializing and de-serializing STIX 2 JSON content, along with higher-level APIs for common tasks, including data markings, versioning, and for resolving STIX IDs across multiple data sources. - -For more information, see [the documentation](https://stix2.readthedocs.io/en/latest/) on ReadTheDocs. - -## Installation - -Install with [`pip`](https://pip.pypa.io/en/stable/): - -``` -pip install stix2 -``` - -## Usage - -### Creating STIX Domain Objects - -To create a STIX object, provide keyword arguments to the type's constructor: - -```python -from stix2 import Indicator - -indicator = Indicator(name="File hash for malware variant", - labels=['malicious-activity'], - pattern='file:hashes.md5 = "d41d8cd98f00b204e9800998ecf8427e"') - -``` - -Certain required attributes of all objects will be set automatically if not -provided as keyword arguments: - -- If not provided, `type` will be set automatically to the correct type. - You can also provide the type explicitly, but this is not necessary: - - ```python - indicator = Indicator(type='indicator', ...) - ``` - - Passing a value for `type` that does not match the class being constructed - will cause an error: - - ```python - >>> indicator = Indicator(type='xxx', ...) - stix2.exceptions.InvalidValueError: Invalid value for Indicator 'type': must equal 'indicator'. - ``` - -- If not provided, `id` will be generated randomly. If you provide an `id` - argument, it must begin with the correct prefix: - - ```python - >>> indicator = Indicator(id="campaign--63ce9068-b5ab-47fa-a2cf-a602ea01f21a") - stix2.exceptions.InvalidValueError: Invalid value for Indicator 'id': must start with 'indicator--'. - ``` - -- If not provided, `created` and `modified` will be set to the (same) current - time. - -For indicators, `labels` and `pattern` are required and cannot be set -automatically. Trying to create an indicator that is missing one of these -properties will result in an error: - -```python ->>> indicator = Indicator() -stix2.exceptions.MissingPropertiesError: No values for required properties for Indicator: (labels, pattern). -``` - -However, the required `valid_from` attribute on Indicators will be set to the -current time if not provided as a keyword argument. - -Once created, the object acts like a frozen dictionary. Properties can be -accessed using the standard Python dictionary syntax: - -```python ->>> indicator['name'] -'File hash for malware variant' -``` - -TBD: Should we allow property access using the standard Python attribute syntax? - -```python ->>> indicator.name -'File hash for malware variant' -``` - -Attempting to modify any attributes will raise an error: - -```python ->>> indicator['name'] = "This is a revised name" -TypeError: 'Indicator' object does not support item assignment ->>> indicator.name = "This is a revised name" -stix2.exceptions.ImmutableError: Cannot modify properties after creation. -``` - -To update the properties of an object, see [Versioning](#versioning) below. - -Creating a Malware object follows the same pattern: - -```python -from stix2 import Malware - -malware = Malware(name="Poison Ivy", - labels=['remote-access-trojan']) -``` - -As with indicators, the `type`, `id`, `created`, and `modified` properties will -be set automatically if not provided. For Malware objects, the `labels` and -`name` properties must be provided. - -### Creating Relationships - -STIX 2 Relationships are separate objects, not properties of the object on -either side of the relationship. They are constructed similarly to other STIX -objects. The `type`, `id`, `created`, and `modified` properties are added -automatically if not provided. Callers must provide the `relationship_type`, -`source_ref`, and `target_ref` properties. - -```python -from stix2 import Relationship - -relationship = Relationship(relationship_type='indicates', - source_ref=indicator.id, - target_ref=malware.id) -``` - -The `source_ref` and `target_ref` properties can be either the ID's of other -STIX objects, or the STIX objects themselves. For readability, Relationship -objects can also be constructed with the `source_ref`, `relationship_type`, and -`target_ref` as positional (non-keyword) arguments: - -```python -relationship = Relationship(indicator, 'indicates', malware) -``` - -### Creating Bundles - -STIX Bundles can be created by passing objects as arguments to the Bundle -constructor. All required properties (`type`, `id`, and `spec_version`) will be -set automatically if not provided, or can be provided as keyword arguments: - -```python -from stix2 import bundle - -bundle = Bundle(indicator, malware, relationship) -``` - -### Serializing STIX objects - -The string representation of all STIX classes is a valid STIX JSON object. - -```python -indicator = Indicator(...) - -print(str(indicator)) -``` - -### Versioning - -TBD - - -## Governance - -This GitHub public repository ( -**** ) was [proposed](https://lists.oasis-open.org/archives/cti/201702/msg00008.html) -and -[approved](https://www.oasis-open.org/committees/download.php/60009/) -\[[bis](https://issues.oasis-open.org/browse/TCADMIN-2549)\] by the [OASIS Cyber Threat Intelligence (CTI) -TC](https://www.oasis-open.org/committees/cti/) as an [OASIS Open -Repository](https://www.oasis-open.org/resources/open-repositories/) to -support development of open source resources related to Technical -Committee work. - -While this 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](https://github.com/oasis-open/cti-python-stix2/blob/master/CONTRIBUTING.md#governance-distinct-from-oasis-tc-process) -from the OASIS TC Process and related policies. - -All contributions made to this Open Repository are subject to open -source license terms expressed in the [BSD-3-Clause -License](https://www.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 Open Repository was created. - -As documented in ["Public Participation -Invited](https://github.com/oasis-open/cti-python-stix2/blob/master/CONTRIBUTING.md#public-participation-invited)", -contributions to this OASIS 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 -Open Repository Guidelines and -Procedures](https://www.oasis-open.org/policies-guidelines/open-repositories), -the open source -[LICENSE](https://github.com/oasis-open/cti-python-stix2/blob/master/LICENSE) -designated for this particular repository, and the requirement for an -[Individual Contributor License -Agreement](https://www.oasis-open.org/resources/open-repositories/cla/individual-cla) -that governs intellectual property. - - -### Maintainers - -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-python-stix2/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 associated TC members have designated one or more persons -to serve as Maintainer(s); subsequently, participating community members -may select additional or substitute Maintainers, per [consensus -agreements](https://www.oasis-open.org/resources/open-repositories/maintainers-guide#additionalMaintainers). - -**Current Maintainers of this Open Repository** - -* [Greg Back](mailto:gback@mitre.org); GitHub ID: ; WWW: [MITRE Corporation](http://www.mitre.org/) -* [Chris Lenk](mailto:clenk@mitre.org); GitHub ID: ; WWW: [MITRE Corporation](http://www.mitre.org/) - -## About OASIS Open Repositories - -* [Open Repositories: Overview and Resources](https://www.oasis-open.org/resources/open-repositories/) -* [Frequently Asked Questions](https://www.oasis-open.org/resources/open-repositories/faq) -* [Open Source Licenses](https://www.oasis-open.org/resources/open-repositories/licenses) -* [Contributor License Agreements (CLAs)](https://www.oasis-open.org/resources/open-repositories/cla) -* [Maintainers' Guidelines and Agreement](https://www.oasis-open.org/resources/open-repositories/maintainers-guide) - - -## Feedback - -Questions or comments about this 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](#currentMaintainers). Please send general -questions about Open Repository participation to OASIS Staff at - and any specific CLA-related questions -to . diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..f062d62 --- /dev/null +++ b/README.rst @@ -0,0 +1,278 @@ +|Build Status| |codecov| + +cti-python-stix2 +================ + +This is an `OASIS Open +Repository `__. +See the `Governance <#governance>`__ section for more information. + +This repository provides Python APIs for serializing and de-serializing +STIX 2 JSON content, along with higher-level APIs for common tasks, +including data markings, versioning, and for resolving STIX IDs across +multiple data sources. + +For more information, see `the +documentation `__ on +ReadTheDocs. + +Installation +------------ + +Install with `pip `__: + +:: + + pip install stix2 + +Usage +----- + +Creating STIX Domain Objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To create a STIX object, provide keyword arguments to the type's +constructor: + +.. code:: python + + from stix2 import Indicator + + indicator = Indicator(name="File hash for malware variant", + labels=['malicious-activity'], + pattern='file:hashes.md5 = "d41d8cd98f00b204e9800998ecf8427e"') + +Certain required attributes of all objects will be set automatically if +not provided as keyword arguments: + +- If not provided, ``type`` will be set automatically to the correct + type. You can also provide the type explicitly, but this is not + necessary: + +``python indicator = Indicator(type='indicator', ...)`` + +Passing a value for ``type`` that does not match the class being +constructed will cause an error: + +``python >>> indicator = Indicator(type='xxx', ...) stix2.exceptions.InvalidValueError: Invalid value for Indicator 'type': must equal 'indicator'.`` + +- If not provided, ``id`` will be generated randomly. If you provide an + ``id`` argument, it must begin with the correct prefix: + +``python >>> indicator = Indicator(id="campaign--63ce9068-b5ab-47fa-a2cf-a602ea01f21a") stix2.exceptions.InvalidValueError: Invalid value for Indicator 'id': must start with 'indicator--'.`` + +- If not provided, ``created`` and ``modified`` will be set to the + (same) current time. + +For indicators, ``labels`` and ``pattern`` are required and cannot be +set automatically. Trying to create an indicator that is missing one of +these properties will result in an error: + +.. code:: python + + >>> indicator = Indicator() + stix2.exceptions.MissingPropertiesError: No values for required properties for Indicator: (labels, pattern). + +However, the required ``valid_from`` attribute on Indicators will be set +to the current time if not provided as a keyword argument. + +Once created, the object acts like a frozen dictionary. Properties can +be accessed using the standard Python dictionary syntax: + +.. code:: python + + >>> indicator['name'] + 'File hash for malware variant' + +TBD: Should we allow property access using the standard Python attribute +syntax? + +.. code:: python + + >>> indicator.name + 'File hash for malware variant' + +Attempting to modify any attributes will raise an error: + +.. code:: python + + >>> indicator['name'] = "This is a revised name" + TypeError: 'Indicator' object does not support item assignment + >>> indicator.name = "This is a revised name" + stix2.exceptions.ImmutableError: Cannot modify properties after creation. + +To update the properties of an object, see `Versioning <#versioning>`__ +below. + +Creating a Malware object follows the same pattern: + +.. code:: python + + from stix2 import Malware + + malware = Malware(name="Poison Ivy", + labels=['remote-access-trojan']) + +As with indicators, the ``type``, ``id``, ``created``, and ``modified`` +properties will be set automatically if not provided. For Malware +objects, the ``labels`` and ``name`` properties must be provided. + +Creating Relationships +~~~~~~~~~~~~~~~~~~~~~~ + +STIX 2 Relationships are separate objects, not properties of the object +on either side of the relationship. They are constructed similarly to +other STIX objects. The ``type``, ``id``, ``created``, and ``modified`` +properties are added automatically if not provided. Callers must provide +the ``relationship_type``, ``source_ref``, and ``target_ref`` +properties. + +.. code:: python + + from stix2 import Relationship + + relationship = Relationship(relationship_type='indicates', + source_ref=indicator.id, + target_ref=malware.id) + +The ``source_ref`` and ``target_ref`` properties can be either the ID's +of other STIX objects, or the STIX objects themselves. For readability, +Relationship objects can also be constructed with the ``source_ref``, +``relationship_type``, and ``target_ref`` as positional (non-keyword) +arguments: + +.. code:: python + + relationship = Relationship(indicator, 'indicates', malware) + +Creating Bundles +~~~~~~~~~~~~~~~~ + +STIX Bundles can be created by passing objects as arguments to the +Bundle constructor. All required properties (``type``, ``id``, and +``spec_version``) will be set automatically if not provided, or can be +provided as keyword arguments: + +.. code:: python + + from stix2 import bundle + + bundle = Bundle(indicator, malware, relationship) + +Serializing STIX objects +~~~~~~~~~~~~~~~~~~~~~~~~ + +The string representation of all STIX classes is a valid STIX JSON +object. + +.. code:: python + + indicator = Indicator(...) + + print(str(indicator)) + +Versioning +~~~~~~~~~~ + +TBD + +Governance +---------- + +This GitHub public repository ( +**https://github.com/oasis-open/cti-python-stix2** ) was +`proposed `__ +and +`approved `__ +[`bis `__] by the +`OASIS Cyber Threat Intelligence (CTI) +TC `__ as an `OASIS Open +Repository `__ +to support development of open source resources related to Technical +Committee work. + +While this 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 Open Repository are subject to open +source license terms expressed in the `BSD-3-Clause +License `__. +That license was selected as the declared `"Applicable +License" `__ +when the Open Repository was created. + +As documented in `"Public Participation +Invited `__", +contributions to this OASIS 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 +Open Repository Guidelines and +Procedures `__, +the open source +`LICENSE `__ +designated for this particular repository, and the requirement for an +`Individual Contributor License +Agreement `__ +that governs intellectual property. + +Maintainers +~~~~~~~~~~~ + +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 associated TC members have designated one or more persons +to serve as Maintainer(s); subsequently, participating community members +may select additional or substitute Maintainers, per `consensus +agreements `__. + +**Current Maintainers of this Open Repository** + +- `Greg Back `__; GitHub ID: + https://github.com/gtback/; WWW: `MITRE + Corporation `__ +- `Chris Lenk `__; GitHub ID: + https://github.com/clenk/; WWW: `MITRE + Corporation `__ + +About OASIS Open Repositories +----------------------------- + +- `Open Repositories: Overview and + Resources `__ +- `Frequently Asked + Questions `__ +- `Open Source + Licenses `__ +- `Contributor License Agreements + (CLAs) `__ +- `Maintainers' Guidelines and + Agreement `__ + +Feedback +-------- + +Questions or comments about this 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 <#currentMaintainers>`__. Please send +general questions about Open Repository participation to OASIS Staff at +repository-admin@oasis-open.org and any specific CLA-related questions +to repository-cla@oasis-open.org. + +.. |Build Status| image:: https://travis-ci.org/oasis-open/cti-python-stix2.svg?branch=master + :target: https://travis-ci.org/oasis-open/cti-python-stix2 +.. |codecov| image:: https://codecov.io/gh/oasis-open/cti-python-stix2/branch/master/graph/badge.svg + :target: https://codecov.io/gh/oasis-open/cti-python-stix2 diff --git a/setup.py b/setup.py index c09e04c..54d4e62 100644 --- a/setup.py +++ b/setup.py @@ -16,7 +16,7 @@ def get_version(): raise AttributeError("Package does not have a __version__") -with open(os.path.join(here, 'README.md'), encoding='utf-8') as f: +with open(os.path.join(here, 'README.rst'), encoding='utf-8') as f: long_description = f.read() setup(