https://github.com/miky4u2/raagent
RAagent is one of two related small and simple tools, particularly useful for system administration of multiple servers using remote task execution and automation.
https://github.com/miky4u2/raagent
go go-module golang remote-admin-tool remote-execution sysadmin system-administration
Last synced: 5 months ago
JSON representation
RAagent is one of two related small and simple tools, particularly useful for system administration of multiple servers using remote task execution and automation.
- Host: GitHub
- URL: https://github.com/miky4u2/raagent
- Owner: miky4u2
- License: mit
- Created: 2020-06-17T08:40:46.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2022-04-24T06:40:42.000Z (about 4 years ago)
- Last Synced: 2025-03-22T07:54:51.296Z (about 1 year ago)
- Topics: go, go-module, golang, remote-admin-tool, remote-execution, sysadmin, system-administration
- Language: Go
- Homepage:
- Size: 68.4 KB
- Stars: 3
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://goreportcard.com/report/github.com/miky4u2/RAagent)
[](https://github.com/miky4u2/RAserver/blob/master/LICENSE)
[](https://golang.org/)
[](https://github.com/miky4u2/RAagent/releases/tag/v0.1.0)
# Remote Admin Agent
**RAagent is functioning but not tested on Osx at all. It might still contain some bugs I haven't come across yet but feel free to try it, use it, expand on it...**
RAagent is one of two related small and simple tools, particularly useful for system administration of multiple servers and remote task automation. Those tools are the result of my first project in GO so the code design might not be the best but they do what they were designed to do just fine :-).
Running services allowing remote program execution can represent a high security risk when not properly firewalled, make sure to setup appropriate firewall rules prior to deployment or do not use at all if you don't know what you are doing.
RAagent can be used standalone, in which case the **'modules'** can just be added manually and **'tasks'** can be executed by sending simple HTTPS POST requests from scripts or admin panels. If multiple agents are used, RAserver can act as the **'modules and binaries repository'** for the agents, making bulk modules deployment and agents update easier. I have done my best to design those tools to run on Linux/Osx/Windows but only used them in production on Linux systems.
Check out the [RAserver repository](https://github.com/miky4u2/RAserver) for the related RAserver code and info.
## Description
- RAagent is a Secure REST API service designed to accept **'tasks'**, requests from allowed origins and execute external **'modules'** on the machine it is running on (Windows/Linux/OSX). This can be useful for example to remotely restart services on servers, add users, trigger updates, download repositories, modify system files, manage dockers etc... The list of commands which can be executed is limited by the 'modules' you install on the agent.
- A **'module'** can be any executable, binary or script written in any language as long as it can be executed and optionally accept arguments, some of which might need to be base64 encoded. For special cases with Windows where the execution of an executable pops up a cmd.exe windows, a special module with extension .cmd can be used. (see .cmd special module below)
- A **'task'** is the Json request for the execution of a specific module with provided arguments. A task can be executed in *attached* or *detached* mode (see below).
The API endpoint to create a task is `/tasks/new`
The API endpoint to check the progress of a *detached* task is `/tasks/status`
- The RAserver is optional and can act as the 'repository' for the agents making modules deployment and agents updates easier.. The RAserver holds the agent list as well as each agent's dedicated modules. When notified by the RAserver, the agents pull their modules, binary, config file and TLS certificate from the RAserver. This is a easy way to bulk add or remove modules from agents as well as bulk update TLS certificate or agent binaries.
## Task modes
- *attached* mode: the agent will execute the task by running the module and reply with the output of the execution (adapted to task that are quick to execute like restarting a service or updating a system file).
- *detached* mode: the agent will detach the *module* execution and return a UUID which can then be used to check the progress of the task via api call to `/tasks/status`. This is particularly useful for tasks that require an extended amount of time to complete and would otherwise cause a time out, like running a backup, synchronizing files, cloning repositories etc...
- Both modes accept an optional *notifyURL* parameter which is called when the task is completed. The notifyURL must be of type https:// and is instantly called when a new task is submitted in *attached* mode and deferred in *detached* mode.
## Request Examples
New Task to `/tasks/new` (Method POST)
Request:
```json
# Windows agent task example in detached mode
{
"name": "Start Notepad",
"mode": "detached",
"notifyURL": "https://www.optional_notify_server.com/api/taskresponse",
"module": "start_notepad.cmd",
"args": ""
}
```
```json
# Linux agent task example in attached mode
{
"name": "Restart Crond",
"mode": "attached",
"notifyURL": "",
"module": "restart_services",
"args": [
"crond"
]
}
```
Response example:
```json
{
"UUID": "8db6408d-c4e9-4144-92aa-46d1201a88d0",
"status": "in progress",
"errorMsgs": null,
"startTime": "2020-05-28 23:11:36",
"endTime": "",
"duration": "",
"output": "",
"endPoint": "/tasks/new",
"name": "Start Notepad",
"mode": "detached",
"notifyURL": "https://www.optional_notify_server.com/api/taskresponse",
"module": "start_notepad.cmd",
"args": ""
}
```
Task Status to `/tasks/status` (Method POST)
Request:
```json
{
"uuid": "8db6408d-c4e9-4144-92aa-46d1201a88d0"
}
```
Response (possible returned task *status* : *in progress*, *done*, *failed*), *output* is the base64 encoded output of the module execution:
```json
{
"status": "ok",
"errorMsgs": null,
"task": {
"UUID": "8db6408d-c4e9-4144-92aa-46d1201a88d0",
"status": "done",
"errorMsgs": null,
"startTime": "2020-05-28 23:11:36",
"endTime": "2020-05-28 23:21:36",
"duration": "10s",
"output": "cnVudGltZS9tb2R1bGVzL3NlcnZpY2VfcmVzdGFydC5zeXN0ZW1jdGw6IGNvbW1hbmQgbm90IGZvdW5kCg==",
"endPoint": "/tasks/new",
"name": "Start Notepad",
"mode": "detached",
"notifyURL": "https://www.optional_notify_server.com/api/taskresponse",
"module": "start_notepad.cmd",
"args": ""
}
}
```
## .cmd special module
While testing with Windows it appeared executing a Windows application via a .bat file opens up a cmd.exe window as well which might be a problem in some cases. To avoid this, a module with extension .cmd can be used. The file must contain a command and optional arguments in json format. The example below would execute 'notepad' or 'notepad.exe' directly. The *cmd* and *args* in the file override the *module* and *args* from the `/tasks/new` request. In other words the command provided in the module is executed instead of the module itself.
```json
{
"cmd": "notepad",
"args": [
"somefile.txt"
]
}
```
## RAserver reserved api calls
- `/agent/update`
1. The server sends the agent an update request of type *full* or *modules*.
2. The agent then sends a request to the server to get a tar.gz file with the updated modules and binary.
3. The agent updates itself and restarts)
- `/agent/ctl`
1. The server can send control commands to the agent of type *status*, *restart* and *stop*
## RAagent config file (conf/config.json)
- **serverIP** : Array of one or more IPV4/IPV6. This is the IP of the RAserver. RAagent will validate the IP when receiving *update* and *ctl* requests(see above) from the RAserver. If no server is used, leave this field blank.
- **serverURL** : Base URL of the RAserver, must be https. RAagent will request the tar.gz update archive from this URL. If no server is used, leave this field blank.
- **validateServerTLS** : If the RAserver uses a self signed TLS certificate, set this to *false*, otherwise set this to *true*.
- **agentID** : Unique identifier for this agent. Allowed characters [A to Z, a to z - _ .]
- **agentBindPort** : Port the agent should bind on.
- **agentBindIP** : IP the agent should bind on. Leave blank to bind on all IPs.
- **allowedIPs** : Array of IPV4/IPV6 IP allowed to send requests to `/tasks/new` and `/tasks/status`
- **logToFile** : *true* to log to log file, *false* or blank to log to stdOut
- **logFile** : When logToFile is *true*, either leave this field blank to use the default log file **log/agent.log** or provide a path to a log file. Use windows(\\) or linux(/) path format depending on which platform the agent is running on.
- **validateNotifyTLS** : Use *false* of *NotifyURL* is used in task requests and the notified server is using a self signed certificate. Otherwise use *true*
- **taskHistoryKeepDays** : Number of days task statuses are kept and can be requested via `/tasks/status`
```json
{
"serverIP": ["127.0.0.1","::1"],
"serverURL": "https://localhost:8081",
"validateServerTLS": false,
"agentID": "example.pc",
"agentBindPort": "8080",
"agentBindIP": "",
"allowedIPs": ["127.0.0.1","::1"],
"logFile":"",
"logToFile": true,
"validateNotifyTLS": false,
"taskHistoryKeepDays": 7
}
```
# Runtime deployment file layout
```
runtime
|
+--bin
| |
| +--agent (or agent.exe) agent executable, launched by startagent
| +--startagent (or startagent.exe) wrapper to start/restart the agent
|
+--conf
| |
| +--config.json (agent config file)
| +--cert.pem (agent TLS certificate & chains)
| +--key.pem (agent TLS certificate key)
|
+--log
| |
| +--agent.log (default log file. Auto truncated when it reaches 500k)
|
+--modules
| |
| +--restart_services (possible linux service restart script)
| +--hello.bat (possible Windows module)
| +--some_module.exe (possible Windows module)
| +--start_chrome.cmd (possible special .cmd module)
| +--etc..
|
+--tasks (Required folder to keep the task status history)
|
+--temp (required temp folder to download and unpack updates from optional RAserver)
```
## Building RAagent
Both 'agent' and 'startagent' need to be built and placed in the /bin folder. The *makeosx.sh*, *makewindows.sh*, *makelinux.sh* can be used, alternatively this can be done as below.
Note: For quiet background startup on Windows, both agent and startagent need building with *-ldflags -H=windowsgui* (Be aware the agent process can then only be killed via the Windows task manager or using RAserver)
```
# Linux
#
GOOS=linux GOARCH=amd64 go build -o ./runtime/bin/startagent ./startagent/startagent.go
GOOS=linux GOARCH=amd64 go build -o ./runtime/bin/agent ./agent/agent.go
# Windows (Quiet start requires building both agent and startagent with -ldflags -H=windowsgui)
#
GOOS=windows GOARCH=amd64 go build -o ./runtime/bin/startagent.exe ./startagent/startagent.go
GOOS=windows GOARCH=amd64 go build -o ./runtime/bin/agent.exe ./agent/agent.go
# OSX (not tested)
#
GOOS=darwin GOARCH=amd64 go build -o ./runtime/bin/startagent ./startagent/startagent.go
GOOS=darwin GOARCH=amd64 go build -o ./runtime/bin/agent ./agent/agent.go
```
## Starting RAagent
The agent needs to be started with **startagent** or **startagent.exe** if used with RAserver as the wrapper is required to restart the agent after updates. In stand alone mode, either **agent** or **startagent** can be used to start the agent.
I am not sure how to start it at boot or as a service on Windows but below is a systemd service file that can be used for linux
```
[Unit]
Description = RAagent
After = network.target
[Service]
Type=
ExecStart = /path/to/RAagent/bin/startagent
[Install]
WantedBy = multi-user.target
```