Argus API

ArgusAPI is a package that supplies you with automatically generated endpoints for Argus. It uses Argus’ swagger.json definition to generate endpoints the first time the module is loaded, and will re-generate them again if they’re more than a day old, ensuring that the local functions are up to date with the remote API.

When Argus API has converted the api definition into Python code, the modules will be available under argus_api.api, and can be imported like any other Python module — you only need to import the functions you actually need.

Using Argus API on the command-line

Every generated API function registers itself as a plugin, and can be used from the command line. Type argus_cli --help to view the available plugins — all API endpoints will be available here, e.g argus_cli alarms v1 alarm get-alarms. For more information on each command, use the --help parameter.

Using Argus API in your scripts

By default, all API functions accept some additional arguments apart from their normal API parameters, provided by this package. These are:

Argument Default Description
json True Return the JSON as a dict. If this is set to fault, a requests.Response object will be returned
apiKey None Explicitly provide an API key to use for authenticating the request. By default, your requests are unauthenticated. You can use a helper from argus_api.helpers.authentication to handle this for you.
verify True Set this to False to disable SSL/TLS verification, or provide a path to a TLS/SSL certificate to verify against. Useful when you’re behind a proxy
authentication {} Extra authentication headers. You may pass in either a dict of headers to add to the request, or a function that returns a dict of headers. The function will receive the target URL of the request.

Simply import the functions you want to use, and begin using them, e.g

from argus_api.api.alarms.v1.alarm import get_alarms, search_alarms
from argus_api.helpers import authentication

@authentication.with_authentication(mode="api_key", api_key=os.environ.get("ARGUS_API_KEY))
def your_function(authentication: callable):
  """Do something with the API"""

  # Just pass on the authentication variable to your API calls, and
  # they'll be authenticated
  alarms = get_alarms(authentication=authentication)
  pass

Authentication

ArgusAPI supports authentication with a variety of methods. When using the library, you can always pass api_key="YOUR API KEY" to any function that interacts with the API, or you can decorate your function with the provided authentication helper argus_api.helpers.authentication.with_authentication, and receive a keyword argument authentication that you can pass to any function you import. This will ensure your API calls are authenticated.

This package provides a couple of different helpers to help you authenticate your requests, abstracting away the need to ask the user for API keys or username / password.

Option 1: Using a decorator

The with_authentication decorator creates a function that helps you generate valid authentication headers for Argus.

In the case of API key, it will just return the correct headers with your API key to Argus, while if you use LDAP / TOTP / Password authentication, it will generate the CSRF token based on your session key after logging you into Argus. This function is passed to the decorated method as a keyword argument called authentication, and can be passed along to any generated API function.

from argus_api.api.alarms.v1.alarm import get_alarms, search_alarms
from argus_api.helpers import authentication

@authentication.with_authentication(mode="api_key", api_key=os.environ.get("ARGUS_API_KEY))
def your_function(authentication: callable):
  """Do something with the API"""

  # Just pass on the authentication variable to your API calls, and
  # they'll be authenticated
  alarms = get_alarms(authentication=authentication)
  pass

Option 2: Provide an API key

All API functions accept the apiKey keyword argument, so passing an API key to the function will always be supported.

from argus_api.api.alarms.v1.alarm import get_alarms, search_alarms

def your_function():
  """Do something with the API"""

  # Just pass on the authentication variable to your API calls, and
  # they'll be authenticated
  alarms = get_alarms(api_key=os.environ.get("ARGUS_API_KEY))
  pass

Option 3: Turn a function into an authenticated function

from argus_api.api.alarms.v1.alarm import get_alarms, search_alarms
from argus_api.helpers import authentication

# Wrap the function with_credentials and set the mode to "password"
# Since no username / password are provided, Argus API will ask the user for this.
get_authenticated_alarms = authentication.with_credentials(mode="password")(get_alarms)

# Provide an API key:
search_authenticated_alarms = authentication.with_api_key(api_key=os.enviro.get("ARGUS_API_KEY"))(search_alarms)

def your_function():
  """Do something with the API"""

  # Just pass on the authentication variable to your API calls, and
  # they'll be authenticated
  alarms = get_authenticated_alarms()

  search = search_authenticate_alarms(keywords=["This call uses my API key!"])
  pass

Subpackages

argus_api.argus module

Provides the wrapper class for Argus API

argus_api.argus.load(base_url: str = 'https://argusweb.mnemonic.no/', parser: module = <module 'argus_api.parsers.openapi2' from '/Users/amnesthesia1/Development/tools/toolbelt/src/argus_api/parsers/openapi2.py'>, **kwargs) → module[source]

Initializes the ArgusAPI, so that when called, the static API files will be generated to disk if they dont already exist, and the module then returned to the user. If the api module already exists, return the loaded module.

Return type:

module

Parameters:
  • base_url (str) – Base URL to fetch the schema
  • parser (module) – Optional custom parser module for parsing the schema before writing to disk

argus_api.schema module

argus_api.schema.find_schema(location: str) → dict[source]

Loads JSON schema from a file or URL

Return type:dict
Parameters:location (str) – Location of the swagger file
Returns:Swagger JSON in a dict
argus_api.schema.write_schema_to_disk(schema: dict) → None[source]

Saves swagger data to the local filesystem with current timestamp. It currently saves it to %cwd%/DEFAULT_API_DEFINITION_LOCATION

Parameters:schema (dict) – JSON data

Module contents

argus_api.ArgusAPI(base_url: str = 'https://argusweb.mnemonic.no/', parser: module = <module 'argus_api.parsers.openapi2' from '/Users/amnesthesia1/Development/tools/toolbelt/src/argus_api/parsers/openapi2.py'>, **kwargs) → module

Initializes the ArgusAPI, so that when called, the static API files will be generated to disk if they dont already exist, and the module then returned to the user. If the api module already exists, return the loaded module.

Return type:

module

Parameters:
  • base_url (str) – Base URL to fetch the schema
  • parser (module) – Optional custom parser module for parsing the schema before writing to disk

itance: