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

AuthenticationFailedException – on 401
AccessDeniedException – on 403
ParentFolderNotFoundException – on 404
ValidationFailedException – on 412
ArgusException – on other status codes

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

AuthenticationFailedException – on 401
AccessDeniedException – on 403
ParentFolderNotFoundException – on 404
ValidationFailedException – on 412
ArgusException – on other status codes

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

AuthenticationFailedException – on 401
AccessDeniedException – on 403
AnErrorOccurredException – on 404
ValidationErrorException – on 412
ArgusException – on other status codes

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

AuthenticationFailedException – on 401
AccessDeniedException – on 403
AnErrorOccurredException – on 404
ValidationErrorException – on 412
ArgusException – on other status codes

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

AuthenticationFailedException – on 401
AccessDeniedException – on 403
AnErrorOccurredException – on 404
ValidationErrorException – on 412
ArgusException – on other status codes

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

AuthenticationFailedException – on 401
AccessDeniedException – on 403
AnErrorOccurredException – on 404
ValidationErrorException – on 412
ArgusException – on other status codes

Returns

content of the sample as bytes