The aim of this article is to give you as a user a simple, all inclusive, guide to installing and using the toolbelt!
If you have trouble during any of these steps, take a look at Troubleshooting.
Installation
This part of the guide will show you how to install and configure the toolbelt.
Installation
Installing the toolbelt is done via pip. This will install the framework as well as the script to run the toolbelt.
To install the toolbelt simply write the following
$ pip3 install argus-toolbelt
If you're getting permission problems when installing, you might have to use the --user flag when installing.
Installation with the --user option will place the script in ~/.local/bin/ on unix systems and %APPDATA%\Roaming\Python\Python<VERSION>\Scripts on windows.
These are typically not in your PATH variable, and thus you'll need to add them.
Updating
To update the toolbelt, the following command is used.
$ pip3 install --upgrade argus-toolbelt
Configuration
After having installed the toolbelt you'll have to provide a configuration with your API key.
To generate an API key, go to your User Preferences in Argus.
Create a file in your home directory called .argus_cli.yaml and add your configuration there. Since your API key only should be used by you, it's recommended to set the permissions on the file so that only you can view and edit it.
$ touch ~/.argus_cli.yaml $ chmod 600 ~/.argus_cli.yaml
The following is what you want to place in the file. Remember to replace the "api_key" parameter to your own API key.
api: api_key: my/api/key method: apikey
Usage
After having installed the toolbelt you can simply call the argus-cli command. After installation this should have been added to your path. On a Linux machine, simply type argus-cli in your terminal, and on a Windows machine you'll have to type argus-cli.exe in your terminal.
If you're ever wondering how to use a command (or what commands are avaliable). Simply use --help on the command.
Examples
Using a custom made command
In this example case is the plugin while statistics is the command. Here we're getting statistics for a month for mnemonic. Dates follow ISO8061. Because this is a custom written command, it will give you a more readable output. In this example it will give you a CSV output, which can be further visualized with programs like excel.
$ argus-cli cases statistics 2017-01-01 2017-02-01 --customer mnemonic
week,low,medium,high,critical 2017-W00,3,4,0,0 2017-W01,0,8,0,0 2017-W02,1,11,0,0 2017-W03,3,11,0,0 2017-W04,1,12,0,0 2017-W05,1,3,0,0
Using a auto generated api endpoint
In this example we're searching for cases containing the keyword "Email containing malicious data" for customer 1.
This example uses an autogenerated API endpoint, which would mimic a result you'd get by using curl on the endpoint. The resulting output will be in a JSON format.
$ argus-cli cases v2 case simple-case-search --keywords "Malware"
Autogenerated api endpoint commands can typically be identified by having a version in the command path (in this example: v2)
Creating a simple command
Development for the toolbelt is aimed to be accessible for everyone.
The following is a simple command for printing case-numbers when searching a case.
from argus_cli.plugin import register_command # Function for registering a command to the cli from argus_cli.utils import output # Common helper for creating nice outputs from argus_api.api.cases.v2.case import advanced_case_search # The case search endpoint from argus_plugins.cases.utils import get_customer_id @register_command(extending="cases") # Register the command to the plugin "say" # The command with arguments for title and customer (which automatically translates a customer name to it's ID) def search(title: str, customer: get_customer_id): ""Search for a case :param title: Title to search for :param customer: Customer to base the search on """ # Get cases based on a customer and keyword cases = advanced_case_search( customerID=[customer] keywords=[title] )["data"] # We only care about the data the endpoint returned. Not the metadata about the response. # Prints the ID and subject in CSV format print(output.csv(["id", "subject"], cases))
Now to be able to use this command you need to add the file or folder to your config.
cli: plugins: - <Path to file/folder>
Now you can run the command!
$ argus_cli cases search "Email" id,subject 23,Suspect Email 42,Wierd Email
$ argus_cli cases search --help usage: argus_cli say hello title customer positional arguments: title Title to search for customer Customer to base the search on optional arguments -h, --help Show this help message and exit