:py:mod:`binaryai.client` ========================= .. py:module:: binaryai.client Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: binaryai.client.BinaryAI Attributes ~~~~~~~~~~ .. autoapisummary:: binaryai.client.SDK_VERSION binaryai.client.DEFAULT_SDK_NAME binaryai.client.DEFAULT_POLL_INTERVAL binaryai.client.DEFAULT_POLL_TIMEOUT binaryai.client.HEADER_REQUEST_SOURCE binaryai.client.DEFAULT_ENDPOINT binaryai.client.DEFAULT_LICENSE_SEPARATOR .. py:data:: SDK_VERSION .. py:data:: DEFAULT_SDK_NAME :value: 'PythonSDK' .. py:data:: DEFAULT_POLL_INTERVAL :value: 2 .. py:data:: DEFAULT_POLL_TIMEOUT :value: 60 .. py:data:: HEADER_REQUEST_SOURCE .. py:data:: DEFAULT_ENDPOINT :value: 'https://api.binaryai.cn/v1/endpoint' .. py:data:: DEFAULT_LICENSE_SEPARATOR :value: ',' .. py:class:: BinaryAI(*, secret_id: Optional[str] = os.environ.get('BINARYAI_SECRET_ID'), secret_key: Optional[str] = os.environ.get('BINARYAI_SECRET_KEY'), endpoint: str = os.environ.get('BINARYAI_ENDPOINT') or DEFAULT_ENDPOINT) Bases: :py:obj:`object` BinaryAI client used to interact with servers. Users can receive upload, do analysis, and receive the detailed results by using this client. .. note:: Since the transport session/connection under the hood will be use one at a time, this class is NOT THREAD SAFE. .. py:method:: upload(filepath: Optional[str] = None, *, mem: Optional[bytes] = None, hooks: Optional[Dict] = None, sha256: Optional[str] = None, md5: Optional[str] = None, is_private: Optional[bool] = True) -> str Uploads a file to server. At least one of following input should be not None: * File upload: fill `filepath` for the file to be upload on the disk * Memory upload: `mem` for the file to be upload in the memory If you only have the hash, you can try to fill `sha256` and `md5`, but the error FileRequiredError might be raised. Hash is ignored if file is already provided through `filepath` or `mem. When multiple hashes provided, only use sha256. Memory upload, hash upload and `hooks` are experimental features. They might be changed without noticed. :param filepath: A pathname to a given file for file upload. :type filepath: Optional :param mem: A byte buffer for a file in memory to be upload. :type mem: Optional :param hooks: A dict to modify arguments before certain operations. :type hooks: Optional :param sha256: A string for hash upload. :type sha256: Optional :param md5: A string for hash upload. :type md5: Optional :returns: A actual sha256 that server calculates and returns. .. py:method:: _reanalyze(sha256: str) Reanalyze target file. :param sha256: File sha256sum. .. py:method:: wait_until_analysis_done(sha256: str, timeout: int = DEFAULT_POLL_TIMEOUT, interval: int = DEFAULT_POLL_INTERVAL) Wait until having a latest stable result, by waiting for if all analysis on this file done. You can set the wait timeout in seconds. If no stable results available after timeout, a TimeoutError is raised. If parts being waitied are failed instead of succeed, this function will *not* raise any exception. To get detailed info about status, call `get_analyze_status`. For analyze in parallel, consider call this function in a seperate thread, since this function is wait by calling `threaing.Event`. This function's implementation is a good reference of judging if a file is finished analyzing. :param sha256: File sha256 sum. :param timeout: maxium wait time in seconds. If negative, wait forever. :type timeout: int :param interval: pool interval in seconds. Raise error if not positive. :type interval: int .. py:method:: get_analyze_status(sha256: str) -> Dict Return current state of each analyzers. Read API document about relationship between analyzer and results. :param sha256: File sha256sum. .. py:method:: get_sha256(md5: str) -> str Get file sha256 by its md5. :param md5: File md5 hash. :returns: File sha256sum. :rtype: str .. py:method:: get_filenames(sha256: str) -> List[str] Get all uploaded filenames for a given file. :param sha256: File sha256sum. :returns: A list of filenames. :rtype: List[str] .. py:method:: get_mime_type(sha256: str) -> str Get MIME type for a given file. :param sha256: File sha256sum. :returns: MIME type string. :rtype: str .. py:method:: get_size(sha256: str) -> int Get size in bytes of a given file. :param sha256: File sha256sum. :returns: File size in bytes. :rtype: int .. py:method:: get_compressed_files(sha256: str) -> List[binaryai.compressed_file.CompressedFile] Get a list of files inside a compressed file identified by a sha256. :param sha256: File sha256sum. Returns: int: File size in bytes. .. py:method:: get_all_cve_names(sha256: str) -> List[str] Get all CVE names for a given file. :param sha256: File sha256sum. .. py:method:: get_all_licenses(sha256: str) -> List[binaryai.license.License] Get all licenses for a given file. :param sha256: File sha256sum. :returns: A list of license string. :rtype: List[str] .. py:method:: get_all_license_short_names(sha256: str) -> List[str] Get all license short names for a given file. :param sha256: File sha256sum. :returns: A list of license short names. :rtype: List[str] .. py:method:: get_all_ascii_strings(sha256: str) -> List[str] Get all ASCII strings for a given file. :param sha256: File sha256sum. :returns: A list of ASCII strings. :rtype: List[str] .. py:method:: get_sca_result(sha256: str) -> List[binaryai.component.Component] Get SCA result for a given file. :param sha256: File sha256sum. :returns: A list of software components. :rtype: List[Component] .. py:method:: get_overview(sha256: str) -> Dict[str, Union[str, int]] Fetch analysis overview from BinaryAI Beat server by file's sha256. :returns: A key-value pair containing overview of the binary file .. py:method:: get_download_link(sha256: str) -> Optional[str] Fetch file download link by file's sha256. :returns: A link can be used to download link later. The link might expire. .. py:method:: list_func_offset(sha256: str) -> List[int] Fetch offsets of functions from analysis. :returns: list of function offset .. py:method:: list_funcs(sha256: str, batch_size: int = 32) -> Iterator[binaryai.function.Function] Parses the list of functions and returns a Function instance containing the given function's name, fileoffset, bytes, pseudocode and returns the list with a generator. :param sha256: File sha256sum. :param batch_size: Batch size to get functions' info :returns: Function Iterator .. py:method:: get_func_info(sha256: str, offset: int, with_embedding: bool = False) -> binaryai.function.Function Fetch detailed information about the given function identified by its offset address. Params: offset: offset address of desired function :returns: Function instance containing the given function's name, fileoffset, bytes, pseudocode .. py:method:: get_funcs_info(sha256: str, offsets: List[int], batch_size: int = 32, with_embedding: bool = False) -> Iterator[binaryai.function.Function] Fetch detailed information about the given functions identified by its offset address. Params: offsets: A list of offset addresses of desired functions batch_size: Batch size to get functions' info. :returns: Function iterator :raises ValueError: invalid batch size .. py:method:: _get_funcs_info(sha256: str, offsets: List[int], step: int = 32, with_embedding: bool = False) -> Iterator[binaryai.function.Function] Get functions' info in batches .. py:method:: get_func_match(sha256: str, offset: int) -> List[binaryai.function.MatchedFunction] Match functions about the given function identified by its offset address. Params: offset: offset address of desired function :returns: a List containing 10 match results, every result is a Dict the contains score and pseudocode. The List is sorted by score from high to low .. py:method:: get_khash_info(sha256: str) -> Optional[tuple[bytes, str]] Return the KHash of this file. See website for detailed introduction on KHash. :returns: KHash's value and version. Only compare if version is same. You are not expected to parse version. :rtype: Optional[Tuple[bytes, str]] .. py:method:: get_malware_probability(sha256: str) -> Optional[float] Return the malware probability of this file. 0 usually mean a white file, while 1 mean the file is risky. This is a experimental feature. This might be changed without noticed. :returns: Probability of the file. None means no result is available. :rtype: Optional[float]