Skip to content

Commit

Permalink
Merge branch 'develop'
Browse files Browse the repository at this point in the history
  • Loading branch information
@maroberts82
maroberts82 committed Aug 16, 2022
2 parents 1b6b028 + 84f37d1 commit ac234af
Showing 1 changed file with 52 additions and 38 deletions.
90 changes: 52 additions & 38 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,15 @@

## OASIS TC Open Repository: openc2-yuuki

# Yuuki

[<img src="snow_yuuki.jpg" alt="Yuuki" title="Yuuki Image" width="224" height="104"/>](snow_yuuki.jpg)
This GitHub public repository ( [https://github.com/oasis-open/openc2-yuuki](https://github.com/oasis-open/openc2-yuuki) ) was created at the request of the [OASIS Open Command and Control (OpenC2) TC](https://www.oasis-open.org/committees/openc2/) 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](https://github.com/oasis-open/openc2-yuuki/blob/master/CONTRIBUTING.md#governance-distinct-from-oasis-tc-process) 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 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 TC Open Repository was created.
As documented in ["Public Participation Invited"](https://github.com/oasis-open/openc2-yuuki/blob/master/CONTRIBUTING.md#public-participation-invited), contributions to this OASIS 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](https://github.com/oasis-open/openc2-yuuki/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.

[<img src="snow_yuuki.jpg" alt="Yuuki" title="Yuuki Image" width="224" height="104"/>](snow_yuuki.jpg)

## Table of Contents

[Introduction](#introduction)
[Requirements and Setup](#requirements-and-setup)
[Yuuki's Consumer Components](#components-of-a-yuuki-consumer)
Expand All @@ -25,12 +29,16 @@ Yuuki is a tool for creating OpenC2 Consumers.
Open Command and Control, or OpenC2, is a standardized language for the command and control of technologies that provide or support cyber defenses.
OpenC2 Commands are sent by Producer devices to Consumers that receive and implement Commands.
OpenC2 is defined in the [OpenC2 Architecture Specification](https://docs.oasis-open.org/openc2/oc2arch/v1.0/csd02/oc2arch-v1.0-csd02.md) and [OpenC2 Language Specification](https://github.com/oasis-tcs/openc2-oc2ls/blob/published/oc2ls-v1.0-cs02.md)
Yuuki serves a few purposes:

* Provide an introduction to OpenC2
* Facilitate experimentation with different Actuator profiles, transfer protocols and message serializations
* Provide an OpenC2 Consumer for OpenC2 Producers to test against
#### Statement of Purpose
Statement of Purpose for this OASIS TC Open Repository (openc2-yuuki) as [proposed](https://drive.google.com/open?id=0B-FunCZrr-vtcUJTWVBNaFNlVUE) and [approved](https://www.oasis-open.org/committees/ballot.php?id=3115) [[bis]](https://issues.oasis-open.org/browse/TCADMIN-2746) by the OpenC2 TC:
The purpose of the openc2-yuuki GitHub repository is to
(a) demonstrate the implementation of OpenC2 via multiple dispatch on type, and
(b) provision a codebase to enable other prototype efforts.
The initial codebase for the openc2-yuuki repository is imported from the OpenC2 Forum's Github repository.

Yuuki is designed to be a good introduction to OpenC2, to facilitate experimentation with different Actuator profiles,
transfer protocols and message serializations, and to provide a simple OpenC2 Consumer for OpenC2 Producers to test against.
The three main components of Yuuki are the [Consumer](consumers), [Actuator](#actuators), and [Serialization](#serializations) classes,
defined respectively in the `consumer.py`, `actuator.py`, and `serialization.py` files.

Expand Down Expand Up @@ -80,7 +88,7 @@ Being focused on cyber defense, Yuuki Consumers have a rate limit that caps the
This helps protect against network overload, recursion errors, or other unforseen issues.

```python
from oc2_arch import Consumer
from yuuki import Consumer

consumer = Consumer(rate_limit=60, versions=['1.0'], actuators=[], serializations=[])
```
Expand All @@ -100,12 +108,12 @@ You will see it at the end of properly processed command logic, and also
with many error messages to send the appropriate failure status code as an OpenC2 message.

```python
from oc2_arch import OpenC2RspFields
from yuuki import OpenC2RspFields

consumer.create_response_msg(response_body=OpenC2RspFields(), encode='json')
```
To extend Consumers to support additional Commands and methods of serializing methods,
the Actuator and Serialization classes are used. Instances of these classes can be provided as arguments to a Consumer
To extend Consumers to support additional Commands and methods of serializing methods,
the Actuator and Serialization classes are used. Instances of these classes can be provided as arguments to a Consumer
when it is initialized, or can be added later using the `add_actuator_profile` and `add_serialization` methods.


Expand Down Expand Up @@ -133,10 +141,11 @@ After an Actuator is initialized, functions that correspond to Commands that the
These functions should have an `OpenC2CmdFields` object as their only parameter and return an `OpenC2RspFields` object.

The `pair` decorator is used to indicate to the Actuator which Command a function is intended to support.
Pairs consist of an action and a target the actuator will read from the OpenC2 Command, as well as logic for what actions to perform and OpenC2 Response to generate.
Pairs consist of an action and a target the actuator will read from the OpenC2 Command, as well as logic for what actions to perform and OpenC2 Response to generate.


```python
from oc2_arch import OpenC2CmdFields, OpenC2RspFields, StatusCode
from yuuki import OpenC2CmdFields, OpenC2RspFields, StatusCode

@example.pair('action', 'target')
def example_command(oc2_cmd: OpenC2CmdFields) -> OpenC2RspFields:
Expand All @@ -146,7 +155,6 @@ def example_command(oc2_cmd: OpenC2CmdFields) -> OpenC2RspFields:
Functions for Commands that are specified in the Actuator profile, but not implemented by the Actuator should set the `implemented` argument to `False`, and provide a desired response message.
For example, if you are implementing an IPv6 packet filter, which does not have IPv4 functions, but you want to send proper notifications,
changing the implementation of these to False should provide the proper `Unimplemented Command` as opposed to `Actuator Not Found`.

```python
@example.pair('action', 'target', implemented=False)
def unsupported_command(oc2_cmd: OpenC2CmdFields) -> OpenC2RspFields:
Expand All @@ -159,12 +167,11 @@ def unsupported_command(oc2_cmd: OpenC2CmdFields) -> OpenC2RspFields:

Serialization objects add support for different message encoding and decoding methods to the Consumer.
They are initialized with three arguments: a string to identify the protocol in OpenC2 Messages,
a function for encoding messages, and a function for decoding messages.
a function for encoding messages, and a function for decoding messages.
The Consumer class comes with support for JSON.

```python
import json
from oc2_arch import Serialization
from yuuki import Serialization

Serialization(name='json', deserialize=json.loads, serialize=json.dumps)
```
Expand Down Expand Up @@ -229,16 +236,14 @@ Yuuki's Consumer functions require it has OpenC2 to read. Transport functions ar
These are found under `/openc2_arch/transports` and have `__init__,` `config` and `transport` functions.
These were not listed with the other core parts of Yuuki only because they interact with its Consumer logic very little.
They are very important, but they deal with transporting serialized messages, not OpenC2 Commands.
This is where your connection info is sent to properly establish connections.
This is where your connection info is sent to properly establish connections.
Tinker with caution!

### MQTT

You can find the OpenC2 MQTT Transfer Specification [Here](https://github.com/oasis-tcs/openc2-transf-mqtt/blob/published/transf-mqtt-v1.0-cs01.md).
A connection to an MQTT broker is required. A publicly available MQTT broker is hosted at [test.mosquitto.org](https://test.mosquitto.org).

#### Start Consumer:

```sh
python examples/mqtt_example_full.py --host test.mosquitto.org
```
Expand All @@ -252,18 +257,15 @@ python producers/mqtt_producer.py --host test.mosquitto.org
You can find the OpenC2 HTTPS Transfer Specification [Here](https://github.com/oasis-tcs/openc2-impl-https/blob/published/open-impl-https-v1.1-cs01.md)

#### Start Consumer:

```sh
python examples/http_example.py
```

#### Publish an OpenC2 Command:

```sh
python examples/producers/http_producer.py
```


### OpenDXL

| :warning: | *Support for OpenDXL is experimental*|
Expand All @@ -282,32 +284,44 @@ python examples/opendxl_example.py PATH_TO_OPENDXL_CONFIG
```sh
python examples/producers/opendxl_producer.py PATH_TO_OPENDXL_CONFIG
```

## Frequently Asked Questions:

#### What is OpenC2?


#### What is OpenC2?
Open Command and Control, or OpenC2, is an OASIS Technical Committee Specification.
OpenC2 is a standardized language for the command and control of technologies that provide or support cyber defenses.
By providing a common language for machine-to-machine communication, OpenC2 is vendor and application agnostic,
enabling interoperability across a range of cyber security tools and applications.
Learn more about OpenC2 at their website, [openc2.org](https://openc2.org/)

#### Who is "In Charge" of Yuuki?

[OASIS Open Projects](https://www.oasis-open.org/open-projects/) operate independently under lightweight rules,
are funded by sponsorship by organizations committed to the project's success, and are coordinated and managed by OASIS.

#### Where can I find Actuators?

Example Implementations of OASIS approved Actuator Profiles will be provided in the Examples folder.
Other functions may be in the works, or used for demo purposes, and these do not generally end up on OASIS Main
until they are fully vetted and polished. However, if you want to see what we're cooking up, feel free to [take a look](https://github.com/ScreamBun/openc2-yuuki/tree/develop)

#### Can I make my own Actuators for Yuuki?

Yes! Yuuki is an Open Project, and while OASIS requires contributors to
#### Can I make my own Actuators for Yuuki?
Yes! Yuuki is an [OASIS Open Project](https://www.oasis-open.org/open-projects/), and while OASIS requires contributors to
read and agree to their Contributor Licensing Agreement, absolutely anyone can pull down
and play around with the code. You can have Yuuki perform officially approved
OpenC2 Actuator Profile functions, or just mess around with things of your own design.
Good Luck, and Have Fun!
Good Luck, and Have Fun!

#### Who Maintains Yuuki?
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]() 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/maintainers-guide/#additionalMaintainers).
Current Maintainers of this TC Open Repository

* [Dave Kemp]([email protected]); GitHub ID: [https://github.com/davaya](https://github.com/davaya); WWW: [Department of Defense](www.nsa.gov)
* [Joshua Brulé](mailto:[email protected]); GitHub ID: [https://github.com/jtcbrule](https://github.com/jtcbrule); WWW: [University of Maryland](https://umd.edu/)
* [David Lemire](mailto:[email protected]); GitHub ID: [https://github.com/dlemire60](https://github.com/dlemire60); WWW: [National Security Agency](www.nsa.gov)
* The ScreamingBunny Development team; GitHub ID: [https://github.com/ScreamBun](https://github.com/ScreamBun)

#### Where can I learn 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/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)

#### How do I submit Feedback to this Repository?
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](https://ccoe-gitlab.hii-tsd.com/screamingbunny/yuuki/-/blob/34630146e94b73b0604bdeea80b74339607e08e3/README.md#currentMaintainers). Please send general questions about TC Open Repository participation to OASIS Staff at [[email protected]](mailto:[email protected]) and any specific CLA-related questions to [[email protected]](mailto:[email protected]).

0 comments on commit ac234af

Please sign in to comment.