ctrl/README.md

# Ctrl

ctrl is a Command & Control (C2) backend system for Servers, IOT and Edge platforms. Simply put, control anything that runs an operating system.

Example use cases:

- Send shell commands or scripts to one or many end nodes that will instruct to change config, restart services and control those systems.
- Gather data from both secure and not secure devices and systems, and transfer them encrypted in a secure way over the internet to your central system for handling those data.
- Collect metrics or monitor end nodes, then send and store the result to some ctrl instance, or pass those data's on to another ctrl instance for further handling of metrics or monitoring data.
- Distribute certificates.
- Run as a sidecar in Kubernetes for direct access to the pod.

As long as you can do something as an operator in a shell on a system you can do the same with ctrl in a secure and encrypted way to one or all end nodes (servers) in one go with one single message/command.


## Features

- Run bash commands or complete scripts of your prefered scripting language (bash, python, powershell and so on).
- Read and write to files.
- Copy files.
- ACL's to restric who can do what.

## Example

An example of a **request** message to copy into ctrl's **readfolder**.

## Quick start

Start up a local nats message broker

```bash
docker run -p 4444:4444 nats -p 4444
```

Create a ctrl docker image.

```bash
git clone git@github.com:postmannen/ctrl.git
cd ctrl
docker build -t ctrl:test1 .
mkdir -p testrun/readfolder
cd testrun
```

create a .env file

```bash
cat << EOF > .env
NODE_NAME="node1"
BROKER_ADDRESS="127.0.0,1:4444"
ENABLE_DEBUG=1
START_PUB_REQ_HELLO=60
IS_CENTRAL_ERROR_LOGGER=0
EOF
```

Start the ctrl container.

```bash
docker run --env-file=".env" --rm -ti -v $(PWD)/readfolder:/app/readfolder ctrl:test1
```

Send a message.

```yaml
cat << EOF > msg.yaml
---
- toNodes:
    - node1
  method: REQCliCommand
  methodArgs:
    - "bash"
    - "-c"
    - |
      echo "some config line" > /etc/my-service-config.1
      echo "some config line" > /etc/my-service-config.2
      echo "some config line" > /etc/my-service-config.3
      systemctl restart my-service

  replyMethod: REQNone
  ACKTimeout: 0
EOF

cp msg.yaml readfolder
```

### Input methods

New Request Messages in Json/Yaml format can be injected by the user to ctrl in the following ways:

- **Unix Socket**. Use for example netcat or another tool to deliver new messages to a socket like `nc -U tmp/ctrl.sock < msg.yaml`.
- **Read Folder**. Write/Copy messages to be delivered to the `readfolder` of ctrl.
- **TCP Listener**, Use for example netcat or another tool to deliver new messages a TCP Listener like `nc localhost:8888 < msg.yaml`.

### Error messages from nodes

- Error messages will be sent back to the central error handler and the originating node upon failure.

The error logs can be read on the central server in the directory `<ctrl-home>/data/errorLog`, and in the log of the instance the source node. You can also create a message to read the errorlog if you don't have direct access to the central server.

### Flags and configuration file

ctrl supports both the use of flags with env variables. An .env file can also be used.

### Schema for the messages to send into ctrl via the API's

|Name | value | description|
|-----|-------|------------|
|toNode | `string` | A single node to send a message to|
|toNodes | `string array` | A comma separated list of nodes to send a message to|
|method | `string` | The request method to use |
|methodArgs | `string array` | The arguments to use for the method |
|replyMethod | `string` | The method to use for the reply message |
|replyMethodArgs | `string array` | The arguments to use for the reply method |
|ACKTimeout | `int` | The time to wait for a received acknowledge (ACK). 0 for no acknowledge|
|retries | `int` | The number of times to retry if no ACK was received |
|replyACKTimeout | `int` | The timeout to wait for an ACK message before we retry |
|replyRetries | `int` | The number of times to retry if no ACK was received for repply messages |
|methodTimeout | `int` | The timeout in seconds for how long we wait for a method to complete |
|replyMethodTimeout | `int` | The timeout in seconds for how long we wait for a method to complete for repply messages |
|directory | `string` | The directory for where to store the data of the repply message |
|fileName | `string` | The name of the file for where we store the data of the reply message |
|schedule | [int type value for interval in seconds, int type value for total run time in seconds] | Schedule a message to re run at interval |


### Request Methods

| Method name| Description|
|------------|------------|
|REQOpProcessList | Get a list of the running processes|
|REQOpProcessStart | Start up a process|
|REQOpProcessStop | Stop a process|
|REQCliCommand | Will run the command given, and return the stdout output of the command when the command is done|
|REQCliCommandCont | Will run the command given, and return the stdout output of the command continously while the command runs|
|REQTailFile | Tail log files on some node, and get the result for each new line read sent back in a reply message|
|REQHttpGet | Scrape web url, and get the html sent back in a reply message|
|REQHello | Send Hello messages|
|REQCopySrc| Copy a file from one node to another node|
|REQErrorLog | Method for receiving error logs for Central error logger|
|REQNone | Don't send a reply message|
|REQToConsole | Print to stdout or stderr|
|REQToFileAppend | Append to file, can also write to unix sockets|
|REQToFile | Write to file, can also write to unix sockets|

## History

ctrl is the continuation of the code I earlier wrote for RaaLabs called Steward. The original repo was public with a MIT license, but in October 2023 the original repo was made private, and are no longer avaialable to the public. The goal of this repo is to provide an actively maintained, reliable and stable version. This is also a playground for myself to test out ideas an features for such a service as described earlier.

This started out as an idea I had for how to control infrastructure.  This is the continuation of the same idea, and a project I'm working on free of charge in my own spare time, so please be gentle :)

NB: Filing of issues and bug fixes are highly appreciated. Feature requests will genereally not be followed up simply because I don't have the time to review it at this time :

Steward was written with an MIT License. With the new fork the service was renamed to ctrl and the license were changed to AGPL V3.0. More information in the [LICENSE-CHANGE.md](LICENSE-CHANGE.md) and [LICENSE](LICENSE) files.

## Disclaimer

All code in this repository are to be concidered not-production-ready, and the use is at your own responsibility and risk. The code are the attempt to concretize the idea of a purely async management system where the controlling unit is decoupled from the receiving unit, and that that we know the state of all the receiving units at all times.

Also read the license file for further details.

Expect the main branch to have breaking changes. If stability is needed, use the released packages, and read the release notes where changes will be explained.