¶ The SOC.OS Agent
The SOC.OS Agent is software that forwards syslog alerts from on-premise security tools (source systems) up to the SOC.OS platform for processing.
Once installed, it listens on the set of assigned ports for syslog alerts sent over UDP, TCP or TLS protocol. Each open port is designated to a different source system.
For example:
| Port | Protocol | Source System |
|---|---|---|
| 514 | TCP | Darktrace |
| 515 | UDP | Palo Alto PanOS |
TLS is also supported.
This flexible port-based system is one of the methods SOC.OS uses to identify what type of alerts are being sent.
During the on-boarding process, a SOC.OS team member will configure these ports and the agent will automatically pick this up on startup.
Follow the below guide on the steps to install the agent. Once the agent is up and running, you can then move on to integrating your tools.
¶ Install Requirements
The agent is designed to be flexible in where it can be installed, to suit most environments.
¶ Host Machine
A machine (virtual or physical) is required to deploy the agent on, with the following minimum requirements:
| CPU | 2 cores (or higher) |
| RAM | 4GB (or higher) |
| Storage | 20GB (or higher) |
¶ Operating System & Architecture
The agent is built for Windows or Linux-based operating systems and architectures:
| Operating System | Architecture |
|---|---|
| Windows | 64-bit (amd64/x86_64) |
| Windows | 32-bit (i386) |
| Linux | 64-bit (amd64/x86_64) |
| Linux | 32-bit (i386) |
¶ Networking
Ensure the agent is installed in a section of the network that allows alerts to be sent from source systems to the agent.
The agent also needs to be able to communicate with the SOC.OS cloud platform - the SOC.OS team can help you configure outbound rules if needed.
Should any of your tools require TLS to forward alerts over syslog, please see TLS
¶ Installation
The SOC.OS Team will provide you with links to download the agent executable. You may also receive a preconfigured config.json file.
Pick the correct version of the agent for your operating system and architecture, download the executable (and config.json if available), and move them onto your agent host machine.
Please continue with the following steps depending on your operating system (select between Windows and Linux tabs on the sections below as appropriate):
On Linux, the agent should be installed in the /usr/local/bin/socos-agent directory to prevent issues with permissions and security architectures like SELinux.
Unzip the .tar.gz folder to the installation location with:
tar -xvzf socos-agent.tar.gz
Make the agent executable with:
chmod +x socos-agent
If running on a system using SELinux (e.g. CentOS 8), once unzipped, open the folder and run:
restorecon socos-agent
This command stands for Restore SELinux Context. It will reset the SELinux security context for files and directories to its default values.
You can confirm this setting has been successful by running:
ls -lZ socos-agent
Which should return something similar to:
-rwxrwxr-x. 1 centos centos unconfined_u:object_r:bin_t:s0 22228011 Feb 10 16:33 socos-agent
This has not been successful if it returns:
-rwxrwxr-x. 1 centos centos unconfined_u:object_r:user_home_t:s0 22228011 Feb 10 16:33 socos-agent`
Drop the preconfigured config.json file next to the agent executable and continue with configuration.
On Windows, the agent can be installed in any preferred location.
Unzip the .zip folder to this location.
If provided, drop the preconfigured config.json file next to the agent executable and continue with configuration.
¶ Using the Agent
The agent executable can be run in the command line on Linux (Bash) with:
./socos-agent
Which prints the root help menu:
SOC.OS Cyber Security Ltd. Alert Forwarding Agent
Usage:
socos-agent [command]
Available Commands:
configure Configure the SOC.OS Agent
help Help about any command
run Runs the SOC.OS Agent interactively in the CLI
service Manage the SOC.OS Agent service (install/uninstall/stop/start/restart)
version Prints the SOC.OS Agent version number
Flags:
-h, --help help for socos-agent
-l, --level string logging level
-o, --log string file path to log output (defaults to stdout)
Use "socos-agent [command] --help" for more information about a command.
Commands can be selected by appending one of the available commands, e.g. the following will print the agent version number:
./socos-agent version
Help is always available with the --help or -h flag, e.g.:
./socos-agent run --help
Logging can be increased with the --level or -l flag and a log level (error/warn/info/debug/trace), e.g.:
./socos-agent run -l debug
The agent executable can be run in the command line on Windows (Powershell) with:
.\socos-agent.exe
To run these commands using Windows Command prompt, simply remove the
./preceeding each command.
Which prints the root help menu:
SOC.OS Cyber Security Ltd. Alert Forwarding Agent
Usage:
socos-agent [command]
Available Commands:
configure Configure the SOC.OS Agent
help Help about any command
run Runs the SOC.OS Agent interactively in the CLI
service Manage the SOC.OS Agent service (install/uninstall/stop/start/restart)
version Prints the SOC.OS Agent version number
Flags:
-h, --help help for socos-agent
-l, --level string logging level
-o, --log string file path to log output (defaults to stdout)
Use "socos-agent [command] --help" for more information about a command.
Commands can be selected by appending one of the available commands, e.g. the following will print the agent version number:
.\socos-agent.exe version
Help is always available with the --help or -h flag, e.g.:
.\socos-agent.exe run --help
Logging can be increased with the --level or -l flag and a log level (error/warn/info/debug/trace), e.g.:
.\socos-agent.exe run -l debug
¶ Configuration
Use the following command to configure the agent:
./socos-agent configure
This will return a help dialogue listing 2 subcommands - config and credentials, which should be run in that order.
The
configcommand only needs to be run if you do not already have a preconfiguredconfig.jsonfile.
In older versions of the agent, the
configurecommand does not have any subcommands, and running it will allow you to configure both theconfigandcredentialstogether.
Run the following command to configure the agent config:
./socos-agent configure config
This will ask you to fill out a series of configuration options - these should have been provided to you by the SOC.OS Team.
Run the following command to configure the agent credentials:
./socos-agent configure credentials
This will ask you to fill out a series of configuration options - these should have been provided to you by the SOC.OS Team.
This command may take a few seconds to complete.
If you don't have these configuration options, please contact support@socos.io.
Use the following command to configure the agent:
.\socos-agent.exe configure
This will return a help dialogue listing 2 subcommands - config and credentials, which should be run in that order.
The
configcommand only needs to be run if you do not already have a preconfiguredconfig.jsonfile.
In older versions of the agent, the
configurecommand does not have any subcommands, and running it will allow you to configure both theconfigandcredentialstogether.
Run the following command to configure the agent config:
.\socos-agent.exe configure config
This will ask you to fill out a series of configuration options - these should have been provided to you by the SOC.OS Team.
Run the following command to configure the agent credentials:
.\socos-agent.exe configure credentials
This will ask you to fill out a series of configuration options - these should have been provided to you by the SOC.OS Team.
This command may take a few seconds to complete.
If you don't have these configuration options, please contact support@socos.io.
¶ Running the Agent
The agent can be run interactively in the command line, or in the background as a service.
We suggest that for initial setup the agent is run in the command line, so logging can be monitored as tools are onboarded. Once the agent is fully configured, stop the agent running in the comand line with CTRL+C and install the agent as a service. It is not necessary to run the agent in CLI once the service is running, and doing so may prevent the agent from correctly listening on the configured ports.
Once installed as a service, the agent should restart automatically should the host machine be restarted.
¶ CLI
The agent can be run in the CLI with:
./socos-agent run
You can increase logging level with the -l flag, as described in Using the Agent.
The agent can be run in the CLI with:
.\socos-agent.exe run
You can increase logging level with the -l flag, as described in Using the Agent.
¶ Service
To install as a service, you will require escalated privileges. Log in as root, or preceed the following commands with sudo.
The agent can be installed as a service with:
./socos-agent service install
./socos-agent service start
It can be uninstalled with:
./socos-agent service stop
./socos-agent service uninstall
You can restart the agent with:
./socos-agent service stop
./socos-agent service start
Logs for the agent will be output to the /var/log/socos-agent/ directory.
You can check the agent has started and is running correctly by running one of the following commands, depending on your Linux distribution:
sudo service SOCOSAgent status
sudo systemctl status SOCOSAgent
You can use the following command to check service logs for more information:
sudo journalctl -xe
To install as a service, you will require escalated privileges. Run Powershell as an Administrator.
The agent can be installed as a service with:
.\socos-agent.exe service install
.\socos-agent.exe service start
It can be uninstalled with:
.\socos-agent.exe service stop
.\socos-agent.exe service uninstall
You can restart the agent with:
.\socos-agent.exe service stop
.\socos-agent.exe service start
Logs for the agent will be output to a logs directory next to the agent executable.
You can check the agent has started and is running correctly by opening Windows Services (Win+R and run services.msc) and finding SOC.OS Agent in the list of services. The agent should move from status Starting and remain in status Running.
You can also check Windows Event Logs to see the service startup logs for the agent. To do so, run Event Viewer (Win+R and run eventvwr) and open Custom Views > Administrative Events. You should see rows with source SOCOSAgent. Click on these rows to see full log information.