API reference#

Session#

class argus_api.session.ArgusAPISession(auth: Optional[Union[argus_api.authentication.authentication.ArgusAPIAuth, str]] = None, api_url: Optional[str] = None, use_cli_config: bool = False, verify: Union[bool, str] = True, proxies: Optional[dict] = None, dev: bool = False, timeout: Optional[int] = None, max_retries: Optional[int] = 3, retry_methods: Collection[int] = ('GET', 'PUT', 'DELETE', 'POST'), retry_statuses: Collection[int] = (500, 503, 504), retry_backoff_factor: Union[int, float] = 0)#
__init__(auth: Optional[Union[argus_api.authentication.authentication.ArgusAPIAuth, str]] = None, api_url: Optional[str] = None, use_cli_config: bool = False, verify: Union[bool, str] = True, proxies: Optional[dict] = None, dev: bool = False, timeout: Optional[int] = None, max_retries: Optional[int] = 3, retry_methods: Collection[int] = ('GET', 'PUT', 'DELETE', 'POST'), retry_statuses: Collection[int] = (500, 503, 504), retry_backoff_factor: Union[int, float] = 0)#

Initialize an API session.

Parameters
  • auth – authentication settings as an ArgusAPIAuth object. can be let unspecified if the use_cli_config argument is True. An API key can also be provided as a string.

  • api_url – base URL of the Argus API. If not set, the default API URL will be used.

  • use_cli_config – if set, default configuration will be loaded from the argus-cli configuration file.

  • verify – SSL certificate verification. Can be set to a boolean or the path to a CA certificate bundle.

  • proxies – proxies dictionary as expected by the proxies argument of requests.request()

  • dev – if set to True, use the development API server. Will take precedence over the api_url argument.

  • timeout – default client-side timeout (in seconds).

  • max_retries – maximum number of retries on failed requests.

  • retry_statuses – HTTP status codes on which to retry.

  • retry_backoff_factor – “backoff factor” between automatic retries.

property auth: argus_api.authentication.authentication.ArgusAPIAuth#

authentication configuration of the session

authenticate(check: bool = False)#

Manually authenticate the session.

Calling this is not required - the session will automatically authenticate if it’s not already authenticated when issuing a request.

Parameters

check – if set to True, ensure that the session’s credentials are verified with Argus even when the authentication does not require an active login (for ex. API key authentication).

Raises

ArgusAPIAuthenticationError – on failed authentication.

backoff_factor: int#

Used to calculate sleep time between retries. backoff sleep time formula: {backoff factor} * (2 ** ({number of total retries} - 1))

base_url: str#

API base URL. Should not contain a trailing /.

check_auth()#

Verify the session’s authentication object’s credentials.

Will raise an exception if the credentials are invalid and return None otherwise.

new_constrained_session(customers: Optional[List[Union[str, int]]] = None, functions: Optional[List[str]] = None, **kwargs) argus_api.session.ArgusAPISession#

Create a new constrained session object.

This method returns a new session object and does not constrain the current one.

All arguments to ArgusAPISession() except auth, use_cli_config and dev can be used and will be passed through to the new session. If they are not used, values from the current session will be used.

Parameters
  • customers – list of customers to constrain the new session to.

  • functions – list of functions to constrain the new session to.

Returns

new constrained session object

property proxies#

proxies dictionary as expected by the proxies argument of requests.request()

set_adapter(default_timeout: Optional[int] = None, max_retries: Optional[int] = None, retry_statuses: Optional[List[int]] = None, retry_methods: Optional[List[str]] = None, backoff_factor: Optional[Union[int, float]] = None)#

Sets the HTTP adapter for the session

this controls global timeout and retry settings.

Parameters
  • default_timeout – default timeout in seconds

  • max_retries – maximun retries on failures

  • retry_statuses – HTTP status codes on which to retry

  • retry_methods – whitelist of methods for which retries will be performed

  • backoff_factor – factor for incremental retry delays

set_timeout(timeout: int)#

Sets the default timeout for the session

Parameters

timeout – new default timeout in seconds

property verify#

SSL certify verification setting as expected by the verify argument of requests.request()

argus_api.session.get_session() argus_api.session.ArgusAPISession#

Get the session currently used by argus_api.lib methods.

argus_api.session.set_session(session: argus_api.session.ArgusAPISession)#

Set the session used by argus_api.lib methods.

Parameters

session – session to use.

Authentication#

class argus_api.authentication.APIKeyAuth(api_key: str)#

API key authentication interface.

Parameters

api_key – Argus API key.

class argus_api.authentication.PasswordAuthentication(username: str, password: str, domain: Optional[str] = None, request_authorizations: Optional[List[str]] = None)#

Password authentication.

Parameters
  • username – user to authenticate

  • password – password to authenticate with

  • domain – domain to authenticate within

  • request_authorizations – additional special authorizations to request

class argus_api.authentication.LDAPAuthentication(username: str, password: str, domain: Optional[str] = None, request_authorizations: Optional[List[str]] = None)#
Parameters
  • username – user to authenticate

  • password – password to authenticate with

  • domain – domain to authenticate within

  • request_authorizations – additional special authorizations to request

class argus_api.authentication.SessionTokenAuth(session_token: str)#

Session token authorization.

Initialize a SessionTokenAuth object.

Parameters

session_token – Argus session token (argus_session cookie).

CSRF utilities#

argus_api.authentication.csrf.get_CSRF_token(url: str, session_key: str) str#

get an Argus CSRF token for the given URL.

Parameters
  • url – URL to get a token for

  • session_key – Argus session (base64-encoded, as given by argus)

Returns

valid CSRF token for the URL

argus_api.authentication.csrf.base64urlencode(value: Union[str, bytes]) str#

Encode a string to URL-safe base64 (as used by JWT) without padding.

This implements the “base64url” encoding as described in RFC 4648, section 5.

Parameters

value – string or bytes to encode

Returns

encoded string

Pagination#

argus_api.pagination.offset_paginated(func: Callable) Callable[[...], Iterator[dict]]#

decorator that turns API functions returning result sets into iterators on pages.

Uses the limit/offset pagination strategy.

Meant to decorate an API method, as in :

from argus_api.api.cases.v2.case import advanced_case_search
for page in offset_paginated(advanced_case_search)(customer="mnemonic", limit=25):
    cases = page["data"]

The decorated function will return a LimitOffsetPaginator instance.

argus_api.pagination.paginated_items(func: Callable) Callable[[...], Iterator[dict]]#

decorator that turns API functions returning result sets into iterators on results.

Uses the limit/offset pagination strategy.

Meant to decorate an API method, as in :

from argus_api.api.cases.v2.case import advanced_case_search
for case in paginated_items(advanced_case_search)(customer="mnemonic", limit=25):
    print(case["id"])

This is essentially a shortcut for:

from argus_api.api.cases.v2.case import advanced_case_search
for page in offset_paginated(advanced_case_search)(customer="mnemonic", limit=25):
    for case in page["data"]:
         print(case["id"])

It is assumed that each page of data contains a data key.

Exceptions#

class argus_api.exceptions.client.ArgusAPIClientException#

Parent class for client exceptions

class argus_api.exceptions.client.ArgusAPIAuthenticationError(message: Optional[str] = None, response: Optional[Response] = None)#

Error that happened during authentication of a session.

message: Optional[str] = None#

error message

response: Optional[Response] = None#

HTTP error response (if available)

exception argus_api.exceptions.http.AccessDeniedException(resp)#

Used for HTTP 403

exception argus_api.exceptions.http.ArgusException(resp)#

Parent class for server-side errors.

message: str#

error message

response: requests.models.Response#

HTTP error response

status_code: int#

response status code

exception argus_api.exceptions.http.AuthenticationFailedException(resp)#

Used for HTTP 401

exception argus_api.exceptions.http.MultipleValidationErrorException#
exception argus_api.exceptions.http.ObjectNotFoundException(resp)#

Used for HTTP 404

exception argus_api.exceptions.http.ServiceUnavailableException(resp)#

Used for HTTP 503

exception argus_api.exceptions.http.UnprocessableEntityException(resp)#

Used for HTTP 422

exception argus_api.exceptions.http.ValidationErrorException(resp)#

Used for HTTP 412

File management#

Documents#

argus_api.files.documents.upload.upload_document(mime_type: str, data: Union[bytes, pathlib.Path], folder: Union[str, int], name: str, customer: Optional[Union[str, int]] = None, accessMode: Optional[str] = None, overwriteExisting: bool = False, skipNotification: bool = False, createMissing: Optional[bool] = None, json: bool = True, verify: Optional[bool] = None, proxies: Optional[dict] = None, apiKey: Optional[str] = None, authentication: Optional[dict] = None, server_url: Optional[str] = None, api_session: Optional[ArgusAPISession] = None) dict#

Upload a document to a folder.

Parameters
  • mime_type – MIME type of the document

  • data – document data, either as raw bytes or a pathlib.Path object. if a pathlib.Path object is provided, the file it is pointing to will be read.

  • folder – folder ID or path to upload the document to. If using a folder ID, it must be passed as an int.

  • name – file name of the document.

  • customer – ID or shortname of the customer whose space the document will be uploaded to. Ignored if the destnation folder is provided as an ID, otherwise defaults to the current user’s customer.

  • accessMode (str) – Access mode to set on new document

  • overwriteExisting (bool) – If true, overwrite existing document with the same name

  • skipNotification (bool) – If true, skip notification to folder watchers

  • createMissing – If set to True, create any missing folders before adding the document. Will be ignored if the folder has been provided as an ID.

  • json – return the response’s body as a dict parsed from json. True by default. If set to false, the raw requests.Response object will be returned.

  • verify – path to a certificate bundle or boolean indicating whether SSL verification should be performed.

  • apiKey – Argus API key.

  • authentication – authentication override

  • server_url – API base URL override

  • api_session – session to use for this request. If not set, the global session will be used.

Raises
Returns

dictionary translated from JSON

argus_api.files.documents.download.download_document(document: Union[str, int], destination_file: Optional[Union[str, pathlib.Path]] = None, customer: Optional[Union[str, int]] = None, verify: Optional[bool] = None, proxies: Optional[dict] = None, apiKey: Optional[str] = None, authentication: Optional[dict] = None, server_url: Optional[str] = None, api_session: Optional[ArgusAPISession] = None) bytes#

Download a document.

returns the content of the document as bytes. If destination_path is set to a path, the sample will be written to the file at that location.

Parameters
  • document – path or ID of the document to download. If an ID is provided, it must be passend as an int.

  • destination_file – if set, write the document to the file at the path this points to.

  • customer – ID or shortname of the customer whose space the document will be downloaded from. Ignored if the destnation folder is provided as an ID, otherwise defaults to the current user’s customer.

  • verify – path to a certificate bundle or boolean indicating whether SSL verification should be performed.

  • apiKey – Argus API key.

  • authentication – authentication override

  • server_url – API base URL override

  • api_session – session to use for this request. If not set, the global session will be used.

Raises
Returns

dictionary translated from JSON

Samples#

argus_api.files.sampledb.upload.upload_sample(data: Union[bytes, pathlib.Path], json: bool = True, verify: Optional[bool] = None, proxies: Optional[dict] = None, apiKey: Optional[str] = None, authentication: Optional[dict] = None, server_url: Optional[str] = None, api_session: Optional[ArgusAPISession] = None) dict#

Upload a new sample file. (INTERNAL)

Parameters
  • data – sample data. Can be provided raw bytes or a pathlib.Path object pointing to the sample’s location.

  • json – return the response’s body as a dict parsed from json. True by default. If set to false, the raw requests.Response object will be returned.

  • verify – path to a certificate bundle or boolean indicating whether SSL verification should be performed.

  • proxies – proxies dictionary as expected by the proxies argument of requests.request()

  • apiKey – Argus API key.

  • authentication – authentication override

  • server_url – API base URL override

  • api_session – session to use for this request. If not set, the global session will be used.

Raises
Returns

API response as a dict or response object if the json parameter was set to False.

argus_api.files.sampledb.upload.add_submission(sha256: str, data: Union[bytes, pathlib.Path], fileName: str, user_agent_name: str, user_agent_version: str, customer: Optional[Union[str, int]] = None, observedTimestamp: Optional[int] = None, mimeType: Optional[str] = None, metaData: Optional[dict] = None, acl: Optional[List[Union[str, int]]] = None, tlp: Optional[str] = None, retention: Optional[str] = None, json: bool = True, verify: Optional[bool] = None, proxies: Optional[dict] = None, apiKey: Optional[str] = None, authentication: Optional[dict] = None, server_url: Optional[str] = None, api_session: Optional[ArgusAPISession] = None) dict#

Add a new sample submission. The required challenge token will be generated automatically. (INTERNAL)

Parameters
  • sha256 – sha256 hash of the sample to add the submission for

  • data – sample data. Can be provided raw bytes or a pathlib.Path object pointing to the sample’s location.

  • fileName – The filename of the sample

  • user_agent_name – name of the user agent

  • user_agent_version – version of the user agent

  • customer – The shortname or ID of customer the submission belongs to. Default value is the currernt user’s customer.

  • observedTimestamp – The timestamp of when the sample was observed. Defaults to the current time

  • mimeType – The sample mime type (default application/octet-stream)

  • metaData – Meta data about the sample

  • acl – List of user IDs or shortnames that are given explicit access to the submission

  • tlp – TLP color of the submission. Defaults to amber.

  • retention – Only retain the submission until the specified time. The submission will be deleted after this time, unless the sample is malicious. Allows unix timestamp (milliseconds), ISO timestamp, or a relative time specification.

  • json – return the response’s body as a dict parsed from json. True by default. If set to false, the raw requests.Response object will be returned.

  • verify – path to a certificate bundle or boolean indicating whether SSL verification should be performed.

  • proxies – proxies dictionary as expected by the proxies argument of requests.request()

  • apiKey – Argus API key.

  • authentication – authentication override

  • server_url – API base URL override

  • api_session – session to use for this request. If not set, the global session will be used.

Raises
Returns

API response as a dict or response object if the json parameter was set to False.

argus_api.files.sampledb.challenge.generate_challenge_token(sha256: str, data: Union[bytes, pathlib.Path], verify: Optional[bool] = None, proxies: Optional[dict] = None, apiKey: Optional[str] = None, authentication: Optional[dict] = None, server_url: Optional[str] = None, api_session: Optional[ArgusAPISession] = None) argus_api.files.sampledb.challenge.ChallengeToken#

“Generate a challenge token for a sample

Parameters
  • sha256 – sha256 of the sample

  • data – sample data. Can be provided raw bytes or a pathlib.Path object pointing to the sample’s location.

  • verify – path to a certificate bundle or boolean indicating whether SSL verification should be performed.

  • apiKey – Argus API key.

  • authentication – authentication override

  • server_url – API base URL override

  • api_session – session to use for this request. If not set, the global session will be used.

Raises
Returns

challenge token

argus_api.files.sampledb.download.download_sample(sha256: str, destination_file: Optional[Union[str, pathlib.Path]] = None, verify: Optional[bool] = None, proxies: Optional[dict] = None, apiKey: Optional[str] = None, authentication: Optional[dict] = None, server_url: Optional[str] = None, api_session: Optional[ArgusAPISession] = None) bytes#

download a new sample file. (INTERNAL)

returns the content of the sample as bytes. If destination_path is set to a path, the sample will be written to the file at that location.

Parameters
  • sha256 – sha256 of the sample

  • destination_file – if set, write the sample to the file at the path this points to.

  • verify – path to a certificate bundle or boolean indicating whether SSL verification should be performed.

  • apiKey – Argus API key.

  • authentication – authentication override

  • server_url – API base URL override

  • api_session – session to use for this request. If not set, the global session will be used.

Raises
Returns

content of the sample as bytes