Getting Started

Note

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

Install

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

Caution

If you’re getting permission problems when installing, you might have to use the –user flag when installing.

Note

Installation with the --user option will place the script in ~/.local/bin/ on unix systems and %APPDATA%\Roaming\Python\PythonVERSION\Scripts (replace VERSION with the relevant version) on windows.

These are typically not in your PATH variable, and thus you’ll need to add them.

Update

To update the toolbelt, the following command is used :

pip3 install --upgrade argus-toolbelt

Basic Configuration

After having installed the toolbelt you’ll have to provide a configuration with your API key.

Note

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 with your own API key.

argus_cli.yaml

api:
    api_key: my/api/key
    method: apikey

Note

for more information, see the Configuration section.

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.

Note

If you have issues with SSL, take a look at Troubleshooting SSL Problems.

Note

If you’re ever wondering how to use a command (or what commands are available), 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.

Case Statistics

argus-cli cases statistics 2017-01-01 2017-02-01 --customer mnemonic

Case Statistics output

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 an auto-generated api endpoint

In this example we’re searching for cases containing the keywords “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.

Case Search

argus-cli cases v2 case simple-case-search --keywords "Malware"

Note

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 at being 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 :

.argus_cli.yaml

cli:
    plugins:
        - "Path to file/folder"

Now you can run the command!

argus_cli cases search "Email"

Result

id,subject
23,Suspect Email
42,Wierd Email

argus_cli cases search --help

Result

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