diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..a5012e5 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,93 @@ +Contributing +============ + +We're thrilled that you're interested in contributing to python-stix2! Here are +some things you should know: + +- `contribution-guide.org `_ has great ideas + for contributing to any open-source project (not just python-stix2). +- All contributors must sign a Contributor License Agreement. See + `CONTRIBUTING.md `_ + in the project repository for specifics. +- If you are planning to implement a major feature (vs. fixing a bug), please + discuss with a project maintainer first to ensure you aren't duplicating the + work of someone else, and that the feature is likely to be accepted. + +Now, let's get started! + +Setting up a development environment +------------------------------------ + +We recommend using a `virtualenv `_. + +1. Clone the repository. If you're planning to make pull request, you should fork +the repository on GitHub and clone your fork instead of the main repo:: + + $ git clone https://github.com/yourusername/cti-python-stix2.git + +2. Install develoment-related dependencies:: + + $ cd cti-python-stix2 + $ pip install -r requirements.txt + +At this point you should be able to make changes to the code. + +Code style +---------- + +All code should follow `PEP 8 `_. We +allow for line lengths up to 160 characters, but any lines over 80 characters +should be the exception rather than the rule. PEP 8 conformance will be tested +automatically by Tox and Travis-CI (see below). + +Testing +------- + +.. note:: + + All of the tools mentioned in this section are installed when you run ``pip + install -r requirements.txt``. + +python-stix2 uses `pytest ` for testing. We encourage the +use of test-driven development (TDD), where you write (failing) tests that +demonstrate a bug or proposed new feature before writing code that fixes the bug +or implements the features. Any code contributions to python-stix2 should come +with new or updated tests. + +To run the tests in your current Python environment, use the ``pytest`` command +from the root project directory:: + + $ pytest + +This should show all of the tests that ran, along with their status. + +You can run a specific test file by passing it on the command line:: + + $ pytest stix2/test/test_.py + +To ensure that the test you wrote is running, you can deliberately add an +``assert False`` statement at the beginning of the test. This is another benefit +of TDD, since you should be able to see the test failing (and ensure it's being +run) before making it pass. + +`tox `_ allows you to test a package +across multiple versions of Python. Setting up multiple Python environments is +beyond the scope of this guide, but feel free to ask for help setting them up. +Tox should be run from the root directory of the project::: + + $ tox + +We aim for high test coverage, using the `coverage.py +`_ library. Though it's not an +absolute requirement to maintain 100% coverage, all code contributions must +be accompanied by tests. To run coverage and look for untested lines of code, +run:: + + $ pytest --cov=stix2 + $ coverage html + +then look at the resulting report in ``htmlcov/index.html``. + +All commits pushed to the ``master`` branch or submitted as a pull request is +tested with `Travis-CI ` +automatically. diff --git a/docs/datastore_api.rst b/docs/datastore_api.rst new file mode 100644 index 0000000..1b10c1b --- /dev/null +++ b/docs/datastore_api.rst @@ -0,0 +1,39 @@ +.. _datastore_api: + +DataStore API +============= + +.. warning:: + + The DataStore API is still in the planning stages and may be subject to + major changes. We encourage anyone with feedback to contact the maintainers + to help ensure the API meets a large variety of use cases. + +One prominent feature of python-stix2 will be an interface for connecting +different backend data stores containing STIX content. This will allow a uniform +interface for querying and saving STIX content, and allow higher level code to +be written without regard to the underlying data storage format. python-stix2 +will define the API and contain some default implementations of this API, but +developers are encouraged to write their own implementations. + +Potential functions of the API include: + +* get a STIX Object by ID (returns the most recent version). +* get all versions of a STIX object by ID. +* get all relationships involving a given object, and all related objects. +* save an object. +* query for objects that match certain criteria (query syntax TBD). + +For all queries, the API will include a "filter" interface that can be used to +either explicitly include or exclude results with certain criteria. For example, + +* only trust content from a set of object creators. +* exclude content from certain (untrusted) object creators. +* only include content with a confidence above a certain threshold (once + confidence is added to STIX). +* only return content that can be shared with external parties (in other words, + that has TLP:GREEN markings). + +Additionally, the python-stix2 library will contain a "composite" data store, +which implements the DataStore API while delegating functionality to one or more +"child" data store. diff --git a/docs/index.rst b/docs/index.rst index 2cd05ba..7e8723d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,6 +10,10 @@ Welcome to stix2's documentation! :maxdepth: 2 :caption: Contents: + overview + roadmap + datastore_api + contributing Indices and tables diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 0000000..b8c3809 --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,24 @@ +Overview +======== + +High level goals/principles of the python-stix2 library: + +1. It should be as easy as possible (but no easier!) to perform common tasks of + producing, consuming, and processing STIX 2 content. +2. It should be hard, if not impossible, to emit invalid STIX 2. +3. The library should default to doing "the right thing", complying with both + the STIX 2.0 spec, as well as associated best practices. The library should + make it hard to do "the wrong thing". + +To accomplish these goals, and to incorporate lessons learned while developing +python-stix (for STIX 1.x), several decisions influenced the design of +python-stix2: + +1. All data structures are immutable by default. In contrast to python-stix, + where users would create an object and then assign attributes to it, in + python-stix2 all properties must be provided when creating the object. +2. Where necessary, library objects should act like ``dict``'s. When treated as + a ``str``, the JSON reprentation of the object should be used. +3. Core Python data types (including numeric types, ``datetime``) should be used + when appropriate, and serialized to the correct format in JSON as specified + in the STIX 2.0 spec. diff --git a/docs/roadmap.rst b/docs/roadmap.rst new file mode 100644 index 0000000..7fb9d8b --- /dev/null +++ b/docs/roadmap.rst @@ -0,0 +1,17 @@ +Development Roadmap +=================== + +.. warning:: + + Prior to version 1.0, all APIs are considered unstable and subject to + change. + +This is a list of (planned) features before version 1.0 is released. + +* Serialization of all STIX and Cyber Observable objects to JSON. +* De-serialization (parsing) of all STIX and Cyber Observable objects. +* APIs for versioning (revising and revoking) STIX objects. +* APIs for marking STIX objects and interpreting markings of STIX objects. +* :ref:`datastore_api`, providing a common interface for querying sources + of STIX content (such as objects in memory, on a filesystem, in a database, or + via a TAXII feed).