Skip to content

Latest commit

 

History

History
246 lines (186 loc) · 8.66 KB

COMMAND_LINE_USAGE.md

File metadata and controls

246 lines (186 loc) · 8.66 KB
Raw

ULS Command Line Usage

This document describes the "command line usage" of the ULS software.
All commands referenced in this document are run from the repositories root level.

Table of contents

Pre-requisites

To run the operations in this documentation, make sure you have the following tools installed:

  • git
  • python >= 3.9 (including pip >= 22.2)
  • Akamai API credentials file - .edgerc (see API Credentials for creation instructions)
  • Understanding of available ULS CLI PARAMETERS
  • Access to github.com, uls-beacon.akamaized.net, pypi.org, pythonhosted.org, pypi.python.org as well as your Akamai API hostname (see edgerc) within your firewall

The above apploes as well for Linux and Windows OS.

Installation

To install ULS, you can choose 2 different ways: automated or manual.

Automated Installation

The automated installation actually does everything, the described below in the manual installation but saves you from the copying the blocks.
It will likely only work on "Linux" based operating systems.

# Got to your preferred installation folder (it will install to a subdirectory ./uls
# run the following two lines and follow the on - screen guidance
curl -O https://raw.githubusercontent.com/akamai/uls/main/scripts/get-uls.sh
bash get-uls.sh

Manual Installation

Those steps are the same on windows and linux based operating systems. Please make sure you have properly installed the above requirements according to your OS in order to follow the next steps.

Clone ULS repository

Clone the ULS repository from github, change into the ULS repository directory afterwards and install requirements.

git clone https://github.com/akamai/uls.git
cd uls
pip3 install -r bin/requirements.txt

Akamai Enterprise Access CLI's

The Secure Enterprise Access Products CLI Tools need to be installed into the ext directory within this repo. Please run the following commands to download the CLI tools and install the requirements.

# Enterprise Application Access (EAA)
git clone --depth 1 --single-branch https://github.com/akamai/cli-eaa.git ext/cli-eaa && \
pip3 install -r ext/cli-eaa/requirements.txt

# Enterprise Threat Protector (ETP)
git clone --depth 1 --single-branch https://github.com/akamai/cli-etp.git ext/cli-etp && \
pip3 install -r ext/cli-etp/requirements.txt

# Akamai Phish Proof Multi Factor Authenticator (AKAMAI-MFA)
git clone --depth 1 --single-branch https://github.com/akamai/cli-mfa.git ext/cli-mfa && \
pip3 install -r ext/cli-mfa/requirements.txt

# Guardicore Log-fetcher (beta)
git clone -q --depth 1 -b dev --single-branch https://github.com/MikeSchiessl/gc-logs.git ext/cli-gc && \
pip3 install -q -r ext/cli-gc/bin/requirements.txt

# Linode Log fetcher (alpha)
git clone -q --depth 1 -b dev --single-branch https://github.com/MikeSchiessl/ln-logs.git ext/cli-linode && \
pip3 install -q -r ext/cli-linode/bin/requirements.txt

# Akamai Control Center Events (experimental)
git clone -q --depth 1 -b dev --single-branch https://github.com/MikeSchiessl/acc-logs.git ext/acc-logs && \
pip3 install -q -r ext/acc-logs/bin/requirements.txt

Setup the .EDGERC File

Copy the .edgerc file (instructions for creation) to your users home directory (~):

cp /path/to/your/.edgerc ~/.edgerc

Usage

The command line interface is split into 3 different sections:

  • Global commands (i.e. --loglevel debug)
  • Input configuration (i.e. --input eaa)
  • Output configuration (i.e. --output tcp)

A full list of options/parameters can be printed by typing

python3 bin/uls.py --help

Starting ULS on the command line, ULS will run in foreground and literally run forever (unless terminated).
As a docker/container usage is recommended, ULS does not bring any threading/daemon support right now. All log output will be directed to STDOUT by default.

Usage examples

  • EAA ADMIN LOG ==> TCP LISTENER

    python3 bin/uls.py --input eaa --feed admin --output tcp --host 10.10.10.200 --port 9090

  • SIA THREAT LOG ==> UDP LISTENER

    python3 bin/uls.py --input sia --feed threat --output udp --host 10.10.10.200 --port 9090

  • MFA AUTH LOG ==> HTTP LISTENER (SPLUNK) disabled TLS verification

     python3 bin/uls.py --input=MFA --feed event --output HTTP --httpformat '{"event": %s}' --httpauthheader '{"Authorization": "Splunk xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}' --httpurl "https://127.0.0.1:9091/services/collector/event" --httpinsecure

  • Logging to a file and sending process to the background

    python3 bin/uls.py --input sia --feed threat --output udp --host 10.10.10.200 --port 9090 &> /path/to/my/logfile &

    Rather consider docker usage instead of this

  • ACC EventViewer LOG ==> RAW with starting time

    python3 bin/uls.py --input ACC -f events --section default --starttime 1719852040 --output raw

ULS as a service: systemd

If you are planning to use multiple Akamai feed with ULS, bear in mind you will need to repeat the instruction below multiple times. We built this guide with CentOS 7.

We assume you have followed the instruction above to install ULS as command line. Before you install the service, make sure it works manually with the configured user.

Create a new file in systemd directory (e.g. /etc/systemd/system), use a name that is easy to remember, like uls-sia-dns.service

# ULS as systemd service example
# uls-sia-dns.service

[Unit]
Description=Akamai ULS feed SIA/DNS  # << Adjust the description with the feed name
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=1
User=uls  # << Change this to reflect the user on your system 
WorkingDirectory=/usr/local/uls  # << Change with ULS location
ExecStart=/usr/bin/python3 /usr/local/uls/bin/uls.py --input sia --feed dns --output tcp --host 127.0.0.1 --port 9090  # << Adjust python path and uls path

[Install]
WantedBy=multi-user.target

Test the service with the following command:

$ systemctl start uls-sia-dns

Make sure everything is working:

$ systemctl status uls-sia-dns

Expected output:

● uls-sia-dns.service - Akamai ULS feed SIA/DNS
   Loaded: loaded (/etc/systemd/system/uls-sia-dns.service; disabled; vendor preset: disabled)
   Active: active (running) since Wed 2021-09-01 23:51:39 UTC; 4s ago
 Main PID: 9428 (python3)
   CGroup: /system.slice/uls-sia-dns.service
           ├─9428 /usr/bin/python3 /root/uls/bin/uls.py --input sia --feed dns --output tcp --host 127.0.0.1 --port 9090
           └─9430 python3 ext/cli-etp/bin/akamai-etp --edgerc /root/.edgerc --section default --user-agent-prefix ULS/1.1.SIA-DNS event dns -f

To make sure the service will start if the machine restarts, use:

$ systemctl enable uls-etp-dns

You might need to adjust some settings until you get what you need. Keep in mind to notify systemd you change the .service file using

$ systemctl daemon-reload

For more information on systemd, see man help man systemd.exec

Updating

To update ULS and the required modules, you can choose 2 different ways: automated or manual

Automated Update

The automated Script will do exactly the steps described in the manual update section below, but saves you from the copying the blocks.

From the root of the ULS directory, run

bash scripts/update-uls.sh

and follow the on - screen guidance

Manual Update

# make sure you are at the root level of your ULS directory
# ULS 
git pull -q
pip3 install -q -r bin/requirements.txt

# EAA CLI (only if installed)
git -C ext/cli-eaa pull -q
pip3 install -q -r ext/cli-eaa/requirements.txt

# ETP CLI (only if installed)
git -C ext/cli-etp pull -q
pip3 install -q -r ext/cli-etp/requirements.txt

# MFA CLI (only if installed)
git -C ext/cli-mfa pull -q
pip3 install -q -r ext/cli-mfa/requirements.txt

# ACC EventViewer (only if installed)
git -C ext/acc-logs pull -q
pip3 install -q -r ext/acc-logs/requirements.txt