Argus API Documentation
Space shortcuts
Page tree
Skip to end of metadata
Go to start of metadata

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.

.argus_cli.yaml
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 have issues with SSL, take a look at Troubleshooting SSL Problems.


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.

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 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.

Case Search
$ 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.

.argus_cli.yaml
cli:
	plugins:
		- <Path to file/folder>

Now you can run the command!

Result
$ argus_cli cases search "Email"
id,subject
23,Suspect Email
42,Wierd Email
Result
$ 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
  • No labels