API reference

exception pypandora.AuthError

exception pypandora.PyPandoraError

PyPandora

class pypandora.PyPandora(root_url: str = 'https://pandora.circl.lu/', useragent: str | None = None, *, proxies: dict[str, str] | None = None)

get_apikey(username: str, password: str) → dict[str, str]

Get the API key for the given user.

get_enabled_workers() → list[str]

Get all the enabled workers

get_stats(interval: str = 'year', year: int | None = None, month: int | None = None, week: int | None = None, day: int | None = None, full_date: date | datetime | None = None) → dict[str, Any]

[Admin only] Gets an overview of what was submitted on the platform

get_submit_stats(interval: str = 'year', year: int | None = None, month: int | None = None, week: int | None = None, day: int | None = None, full_date: date | datetime | None = None) → dict[str, Any]

[Admin only] Get the number of submissions on a specific interval

init_apikey(username: str | None = None, password: str | None = None, apikey: str | None = None) → None

Init the API key for the current session. All the requests against pandora after this call will be authenticated.

property is_up: bool

Test if the given instance is accessible

redis_up() → bool

Check if redis is up and running

search(query: str, limit_days: int = 3) → dict[str, Any]

[Admin only] Search a hash or a filename in the tasks

submit(file_in_memory: BytesIO, filename: str, /, seed_expire: datetime | timedelta | int | None = None, password: str | None = None) → dict[str, Any]

Submit a file from the disk.

Parameters:

• file_in_memory – Memory object of the file to submit.

• filename – The name of the file.

• seed_expire – If not None, the response will contain a seed allowing to view the result of the analysis. If the type is a datetime, the seed will expire at that time. If the type is a timedelta, the seed will expire then the given time interval expires. If the type is a int, the seed will expire after the value (in seconds) expires. 0 means the seed never expires.

submit_from_disk(file_on_disk: str | Path, /, seed_expire: datetime | timedelta | int | None = None) → dict[str, Any]

Submit a file from the disk.

Parameters:

• file_on_disk – The path to the file to upload.

• seed_expire – If not None, the response will contain a seed allowing to view the result of the analysis. If the type is a datetime, the seed will expire at that time. If the type is a timedelta, the seed will expire then the given time interval expires. If the type is a int, the seed will expire after the value (in seconds) expires. 0 means the seed never expires.

task_download(task_id: str, to_download: str, seed: str | None = None) → BytesIO

Get elements created during a task. Unless you have an admin account and called init_apikey first, you need to pass a seed. Even with a seed, your account may not be allowed to get specific emelents, it depends how the pandora instance is configured and the roles associated with non-admin users.

That said, the to_download setting have the following meaning:

• img: Preview of the content of the file. It is a zip file containig images. If the file cannot be previewed, returns an error.

• pdf: If the uploaded file was a PDF, the pdf, an error otherwise.

• txt: Text extracted from the document (if any)

• zip: The original file, in password protected zip

• misp: The MISP export of the task

Parameters:

• task_id – The UUID of the task

• to_download – The thing to download, can be ‘img’, ‘pdf’, ‘txt’, ‘zip’, ‘txt_preview’, ‘misp’

• seed – The seed. The seed must be still valid at the time the query is made. It is optional if the session is authenticated.

task_observables(task_id: str, seed: str | None = None) → dict[str, Any]

Get the observables from a task

task_status(task_id: str, seed: str | None = None) → dict[str, Any]

Get the status of a task.

Parameters:

• task_id – The UUID of the task

• seed – The seed. The seed must be still valid at the time the query is made. It is optional if the session is authenticated.

worker_status(task_id: str, all_workers: bool = False, details: bool = False, seed: str | None = None, worker_name: str | None = None) → dict[str, Any]

Get the status of a task.

Parameters:

• task_id – The UUID of the task

• seed – The seed. The seed must be still valid at the time the query is made. It is optional if the session is authenticated.

• all_workers – Show the status of every workers and the details at the same time

• worker_name – The name of the worker you want the status of. It is optional if you want every workers details

• details – The details from the wanted worker

workers_stats_day(year: int | str | None = None, month: int | str | None = None, day: int | str | None = None) → dict[str, Any]

[Admin only] Get the workers stats for a specific day - defaults to today

workers_stats_month(year: int | str | None = None, month: int | str | None = None) → dict[str, Any]

[Admin only] Get the workers stats for a specific month - defaults to this month

workers_stats_week(year: int | str | None = None, week: int | str | None = None) → dict[str, Any]

[Admin only] Get the workers stats for a specific week - defaults to this week

workers_stats_year(year: int | str | None = None) → dict[str, Any]

[Admin only] Get the workers stats for a specific year - defaults to this year