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 theuse_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 ofrequests.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))
- 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()
exceptauth
,use_cli_config
anddev
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 ofrequests.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 ofrequests.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#
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.
- 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.
- response: requests.models.Response#
HTTP error response
- 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
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 rawrequests.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
ObjectNotFoundException – on 404
ValidationErrorException – 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
ObjectNotFoundException – on 404
ValidationErrorException – 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 rawrequests.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 ofrequests.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 toFalse
.
- 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 rawrequests.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 ofrequests.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
ObjectNotFoundException – 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 toFalse
.
- 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
ObjectNotFoundException – 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
ObjectNotFoundException – on 404
ValidationErrorException – on 412
ArgusException – on other status codes
- Returns
content of the sample as bytes