boxmetrics-agent

README

boxmetrics-agent

This repo contains the boxmetrics agent built with Go

📦 Requirements

Only needed when contributing or building from source

This project should be working as expected with the following minimal version of:

Dependency	Version
Go	>= 1.12

🚀 Quick start

The application must be launch with root or a sudoers, otherwise some features can be unavailable

From docker image :

1. Run this command

docker run --rm -p 4455:4455 -p 5544:5544 286829485023.dkr.ecr.us-west-2.amazonaws.com/boxmetrics-agent:<TAG>

From prebuilt binaries :

1. Donwload a binary from Github release page

2. Run application

# Made application executable
sudo chmod +x boxmetrics-agent

# Start application
./boxmetrics-agent

From source code :

1. Clone the git repository

# cloning git repository
git clone https://github.com/boxmetrics/boxmetrics-agent

1. Build application

# go to boxmetrics-agent directory
cd boxmetrics-agent
# run helper command to build
make build

1. Run application

# Made application executable
sudo chmod +x bin/boxmetrics-agent

# Start application
./bin/boxmetrics-agent start

💡 Usage

Routes

Path	Description
/ws/v1	Websocket root
/	Test page

Communication

Both request and response are JSON message

Request

Key	Type	Require	Default	Description
type	string	yes	NA	Request type
value	string	yes	NA	Type value
options	object	no	Default Options Object	Request options
format	boolean	no	true	Enable formating

Type Values

Value	Description
info	Return value information type
script	Run value script
command	Execute value as command (Use options to add parameters)

Info Type Values

Value	Response	Description
memory	Schema	Return memory information
cpu	Schema	Return cpu usage information
cpuinfo	Schema	Return cpu hardware information
disks	Schema	Return disks information
containers	Schema	Return containers full information
containersid	Array of string	Return containers ID list
host	Schema	Return host information
users	Schema	Return users list
sessions	Schema	Return user sessions list
network	Schema	Return network information
connections	Schema	Return opened connections list
processes	Schema	Return processes information list
process	Schema	Return process full information (options.pid must be set)
general	Schema	Return system wide informations

Script Type Values

Value	Response	Description
adduser	string	Add user to the system (options.args must be set with corresponding value)
killprocess	string	Kill one process (options.pid must be set)

Options Object

Key	Type	Require	Default	Description
args	Array	no	null	Array of arguments to pass to the command or to pass to adduser script eg. ["-p <pass>", "-u <username>", "-g group1"] (-g arg is optional and can be used multiple times)
env	Array	no	null	Array of environment variable to add before executing command eg. MY_VAR=abc
pwd	string	no	""	Location where the command run, if empty string run in the cwd of the process
pid	number	no	0	PID use to retrieve information with process info type or to kill on script killprocess

Response

Key	Type	Description
event	object	The event send
data	object	The data reponse of the event. Corresponding to a specific schema
startDate	string	Start date of the response processing
endDate	string	End date of the response processing
duration	string	Duration of the response processing
status	object	Status of the response
error	string	Error message (null if no error)

Status object

Key	Type	Description
code	number	Status code
message	string	Status message

💬 Contributing

1. Fork the git repository

2. Create your feature branch

3. Apply your changes

4. Run application

# run test
make test
# start application in dev mode
make run #  only on first time
go run main.go

1. Open browser to test your change!

Project is running at http://localhost:4455 or https://localhost:5544

1. Commit your changes

2. Push it on your fork

3. Create new pull request

🧐 What's inside ?

.
├── certificates    # Project Certificates
├── configs         # Configuration file templates or default configs
├── docs            # Design and user documents
├── init            # System init and process manager/supervisor configs
├── internal
│   └── pkg         # Private library code
├── scripts         # Scripts to perform various build, install, analysis, etc operations
├── test            # Additional external test apps and test data
├── Dockerfile      # Docker image
├── go.mod          # Module dependencies
├── go.sum          # Ensure dependencies integrity
├── LICENSE
├── main.go         # Application entry point
├── Makefile        # Helpers command
└── README.md

👷 Maintained by

Laurent Panek Security System Integrator

Abdessalam Benharira JavaScript Developer