README.md

Communications Backbone

Communications Backbone by C2 Team (NOC)

Data flow

• Client A sends to client-a-outbox (or POSTs to API /send - not yet implemented)
• Messages are forwarded from client-a-outbox to soar-publish
• Messages are published from soar-publish with the given topic read from the message
• Subscribers listen to for messages
• Subscription is delivered to client-b-inbox
• Client B reads from `client-b-inbox (or GETs from API /receive)

There is a parallel flow when a client sends to client-a-notify in which case the messages are delivered through the broadcast exchange to all clients client-x-inbox.

Auth placeholder

As a proxy for proper authentication, when you post a client a random secret is returned in the response. To send to / receive from the bus you then call the API with the client_id and secret and it checks they match. The client_id determines which queues it reads from.

Subsequent requests to the client endpoint return the client_id but not the secret.

Testing

Current coverage:

• API: yes
• Pika RabbitMQ implementation: no

pytest

Running via docker-compose

Using docker-compose will mean that everything is setup automatically, this includes the rabbitmq container, the backbone API, and the backbone bus. The run-compose.sh script has been provided to simplify this even further - all you have to do is set whatever env vars you need in the .env file and then run ./run-compose.sh (the defaults in .env are fine for local dev work, but ones not labelled optional will need setting in a production setting). The env vars are:

• DATA_DIR - Where to mount the volume of the API container on your local system. This defaults to the result of pwd, which should be within the communications-backbone repo
• SOAR_TOKEN_LIFETIME (Optional) - The number of hours until a newly created token expires
• SOAR_TOKEN_SECRET (Optional) - A secret key used to encrypt/decrypt token data. If specified the value should be set using TokenModel.getKey()

Running manually

Setup

In a virtual environment

pip install -r requirements-dev.txt  

RabbitMQ

docker run --rm -p 5672:5672 -d --hostname rmq --name rmq rabbitmq:management

API

python api.py 

Event bus

python soar_bus.py

Usage

To use the backbone you have to create a client. The client id and name should be unique but human readable. A client secret is returned by the API and client credential grants using this client_id and secret are used to authenticate client application connections.

Create some clients

POST to http://localhost:3000/clients

Send / Receive directly

# Send a message 
python client_send.py noc-c2-outbox 'soar.noc.slocum.something' from noc-c2

# Receive messages  
python client_read.py noc-sfmc-inbox

Receive via API

As a placeholder for proper authentication you post the client_id and secret and it checks that a client with that id exists and that the secret matches before allowing the request.

This should be replaced with a proper auth layer.

GET http://localhost:5000/receive?client_id=[client_id]&secret=[secret]