pythx.api package

Submodules

pythx.api.client module

This module contains the main API Client implementation.

class pythx.api.client.Client(username: str = None, password: str = None, api_key: str = None, refresh_token: str = None, handler: pythx.api.handler.APIHandler = None, no_cache: bool = False, middlewares: List[pythx.middleware.base.BaseMiddleware] = None, api_url: str = None)

Bases: object

The main class for API interaction.

The client makes sure that you are authenticated at all times. For authentication data it required either the account’s Ethereum address and password, or a valid combination of access and refresh token. If any token expires, the client will automatically try to refresh the access token, or log the user in again. After that, the original request is executed.

Furthermore, the client class supports various actions for high-level usage to easily submit new analysis jobs, check their status, get notified whether they are ready, and fetch analysis job report data.

A user can inject custom middlewares. There are two required internal ones:

1. ClientToolNameMiddleware Fills in the clientToolName field for new analysis submissions
2. AnalysisCacheMiddleware Sets the noCacheLookup field in new analysis submissions

These middlewares can also be overwritten by the user (even though using the Client parameters is recommended). If any of these middleware instances are missing in the user-defined list, e.g. because they simply add their own ones, the Client constructor will automatically add them with their default or parameter-defined values (if given).

add_group_to_project(group_id: str, project_id: str) → mythx_models.response.group_operation.GroupOperationResponse

Adds group to the project.

This will add the group to the project in the MythX platform.

Parameters:

• group_id – The target group ID
• project_id – The target project ID

Returns:

GroupOperationResponse

analysis_list(date_from: datetime.datetime = None, date_to: datetime.datetime = None, offset: int = None, created_by: str = None, group_name: str = None, group_id: str = None, main_source: str = None) → mythx_models.response.analysis_list.AnalysisListResponse

Get a list of the user’s analyses jobs.

Parameters:

• date_from – Start of the date range (optional)
• date_to – End of the date range (optional)
• offset – The number of results to skip (used for pagination)
• created_by – Filter analysis results based on the creator
• group_name – Filter analysis results based on the group name
• group_id – Filter analysis results based on their group ID
• main_source – Filter analysis results based on their main source name

Returns:

AnalysisListResponse

analysis_ready(uuid: str) → bool

Return a boolean whether the analysis job with the given UUID has finished processing.

Parameters:uuid – The analysis job UUID Returns:bool indicating whether the analysis has finished

analysis_status(uuid: str) → mythx_models.response.analysis_status.AnalysisStatusResponse

Get the status of an analysis job based on its UUID.

Parameters:uuid – The job’s UUID Returns:AnalysisStatusResponse

analyze(bytecode: str = None, main_source: str = None, sources: Dict[str, Dict[str, str]] = None, contract_name: str = None, source_map: str = None, deployed_bytecode: str = None, deployed_source_map: str = None, source_list: List[str] = None, solc_version: str = None, analysis_mode: str = 'quick', payload: mythx_models.request.analysis_submission.AnalysisSubmissionRequest = None) → mythx_models.response.analysis_submission.AnalysisSubmissionResponse

Submit a new analysis job.

At least the smart contracts bytecode, or it’s source code must be given. The more information the MythX API gets, the more precise and verbose the results will be.

Parameters:

• contract_name – The main Solidity contract’s name
• bytecode – The EVM creation bytecode obtained
• source_map – The source map for the EVM creation bytecode
• deployed_bytecode – The deployed EVM bytecode
• deployed_source_map – The deployed bytecode’s source map
• main_source – The main source file to start analysis from
• sources – A dictionary holding the source file data
• source_list – A list of source files (ordered by the source map locs)
• solc_version – The solc version used for compilation
• analysis_mode – The analysis mode
• payload – Directly inject an AnalysisSubmissionRequest model

Returns:

AnalysisSubmissionResponse

assert_authentication() → None

Make sure the user is authenticated.

If necessary, this method will refresh the access token, or perform another login to get a fresh combination of tokens if both are expired.

Returns:None

create_group(group_name: str = '') → mythx_models.response.group_creation.GroupCreationResponse

Create a new group.

Parameters:group_name – The name of the group (max. 256 characters, optional) Returns:GroupCreationResponse

create_project(name: str = '', description: str = '', groups: List[str] = None) → mythx_models.response.project_creation.ProjectCreationResponse

Create a new project.

Parameters:

• name – The project name
• description – The project description
• groups – List of group IDs belonging to the project (optional)

Returns:

ProjectCreationResponse

delete_project(project_id: str = '') → mythx_models.response.project_deletion.ProjectDeletionResponse

Delete an existing project.

Parameters:project_id – The project’s ID Returns:ProjectDeletionResponse

group_list(offset: int = None, created_by: str = '', group_name: str = '', date_from: datetime.datetime = None, date_to: datetime.datetime = None) → mythx_models.response.group_list.GroupListResponse

Get a list of the currently defined MythX analysis groups.

Parameters:

• offset – The number of results to skip (used for pagination)
• created_by – Filter the list results by the creator’s user ID
• group_name – Filter the list results by the group’s name
• date_from – Only display results after the given date
• date_to – Only display results until the given date

Returns:

GroupListResponse

group_status(group_id: str) → mythx_models.response.group_status.GroupStatusResponse

Get the status of an analysis group by its ID.

Parameters:group_id – The group ID to fetch the status for Returns:GroupStatusResponse

login() → mythx_models.response.auth_login.AuthLoginResponse

Perform a login request on the API and return the response.

Returns:AuthLoginResponse

logout() → mythx_models.response.auth_logout.AuthLogoutResponse

Perform a logout request on the API and return the response.

Returns:AuthLogoutResponse

project_list(offset: int = None, limit: int = None, name: str = '') → mythx_models.response.project_list.ProjectListResponse

List the existing projects on the platform

Parameters:

• offset – The number of projects to skip (optional)
• limit – The number of projects to return (optional)
• name – The name to filter projects by (optional)

Returns:

project_status(project_id: str = '') → mythx_models.response.project_status.ProjectStatusResponse

Get detailed information for a project.

Parameters:project_id – The project’s ID Returns:ProjectStatusResponse

refresh() → mythx_models.response.auth_refresh.AuthRefreshResponse

Perform a JWT refresh on the API and return the response.

Returns:AuthRefreshResponse

report(uuid: str) → mythx_models.response.detected_issues.DetectedIssuesResponse

Get the report holding found issues for an analysis job based on its UUID.

Parameters:uuid – The analysis job UUID Returns:DetectedIssuesResponse

request_by_uuid(uuid: str) → mythx_models.response.analysis_input.AnalysisInputResponse

Get the input request based on the analysis job’s UUID.

Parameters:uuid – The analysis job UUID Returns:AnalysisInputResponse

seal_group(group_id: str) → mythx_models.response.group_operation.GroupOperationResponse

Seal the group.

This closes an open group for the submission of any further analyses.

Parameters:group_id – The target group ID Returns:GroupOperationResponse

update_project(project_id: str = '', name: str = '', description: str = '') → mythx_models.response.project_update.ProjectUpdateResponse

Update an existing project.

A new name, a new description, or both should be given.

Parameters:

• project_id – The ID of the project to update
• name – The new project name (optional)
• description – The new project description (optional)

Returns:

ProjectUpdateResponse

version() → mythx_models.response.version.VersionResponse

Call the APIs version endpoint to get its backend version numbers.

Returns:VersionResponse

pythx.api.handler module

This module contains the API request handler implementation.

class pythx.api.handler.APIHandler(middlewares: List[pythx.middleware.base.BaseMiddleware] = None, api_url: str = None)

Bases: object

Handle the low-level API interaction.

The API handler takes care of serializing API requests, sending them to the configured endpoint, parsing the response into its respective domain model, as well as registering and executing request/response middlewares.

assemble_request(req: [<class 'mythx_models.request.analysis_input.AnalysisInputRequest'>, <class 'mythx_models.request.analysis_list.AnalysisListRequest'>, <class 'mythx_models.request.analysis_status.AnalysisStatusRequest'>, <class 'mythx_models.request.analysis_submission.AnalysisSubmissionRequest'>, <class 'mythx_models.request.auth_login.AuthLoginRequest'>, <class 'mythx_models.request.auth_logout.AuthLogoutRequest'>, <class 'mythx_models.request.auth_refresh.AuthRefreshRequest'>, <class 'mythx_models.request.detected_issues.DetectedIssuesRequest'>, <class 'mythx_models.request.group_creation.GroupCreationRequest'>, <class 'mythx_models.request.group_list.GroupListRequest'>, <class 'mythx_models.request.group_operation.GroupOperationRequest'>, <class 'mythx_models.request.group_status.GroupStatusRequest'>, <class 'mythx_models.request.project_creation.ProjectCreationRequest'>, <class 'mythx_models.request.project_deletion.ProjectDeleteRequest'>, <class 'mythx_models.request.project_list.ProjectListRequest'>, <class 'mythx_models.request.project_status.ProjectStatusRequest'>, <class 'mythx_models.request.project_update.ProjectUpdateRequest'>, <class 'mythx_models.request.version.VersionRequest'>]) → Dict[KT, VT]

Assemble a request that is later sent to the API.

This method generates an intermediate data dictionary format holding all the relevant request data needed by the API. This encompasses the HTTP verb, the request payload content (if there is any), the request’s URL parameters, additional headers, as well as the API endpoint the request should be sent to.

Each of these data points is encoded in the domain model as a property. The endpoint URL is constructed from the domain model’s path (e.g. /v1/auth/login) and the API base path: https://api.mythx.io, which is contained in the library configuration module.

Before the serialized request is returned, all registered middlewares are applied to it.

Parameters:req – The request domain model Returns:The serialized request with all middlewares applied

execute_request_middlewares(req: Dict[KT, VT]) → Dict[KT, VT]

Sequentially execute the registered request middlewares.

Each middleware gets the request’s data dictionary as generated by the APIHandler.assemble_request method. On top of the request any manipulations can be made.

It is worth mentioning here that this is a simple loop iterating over the middleware list, calling each middleware’s process_request method. It is expected that each registered middleware exposes this method and returns a data dictionary in the same format as the one passed in. It also means that the order in which middlewares are registered can matter, even though it is recommended that middlewares are kept associative in nature.

Parameters:req – The request’s data dictionary Returns:The updated data dict - ready to be sent to the API

execute_response_middlewares(resp: Union[mythx_models.response.analysis_input.AnalysisInputResponse, mythx_models.response.analysis_list.AnalysisListResponse, mythx_models.response.analysis_status.AnalysisStatusResponse, mythx_models.response.analysis_submission.AnalysisSubmissionResponse, mythx_models.response.auth_login.AuthLoginResponse, mythx_models.response.auth_logout.AuthLogoutResponse, mythx_models.response.auth_refresh.AuthRefreshResponse, mythx_models.response.detected_issues.DetectedIssuesResponse, mythx_models.response.group_creation.GroupCreationResponse, mythx_models.response.group_list.GroupListResponse, mythx_models.response.group_operation.GroupOperationResponse, mythx_models.response.group_status.GroupStatusResponse, mythx_models.response.project_creation.ProjectCreationResponse, mythx_models.response.project_deletion.ProjectDeletionResponse, mythx_models.response.project_list.ProjectListResponse, mythx_models.response.project_status.ProjectStatusResponse, mythx_models.response.project_update.ProjectUpdateResponse, mythx_models.response.version.VersionResponse]) → Union[mythx_models.response.analysis_input.AnalysisInputResponse, mythx_models.response.analysis_list.AnalysisListResponse, mythx_models.response.analysis_status.AnalysisStatusResponse, mythx_models.response.analysis_submission.AnalysisSubmissionResponse, mythx_models.response.auth_login.AuthLoginResponse, mythx_models.response.auth_logout.AuthLogoutResponse, mythx_models.response.auth_refresh.AuthRefreshResponse, mythx_models.response.detected_issues.DetectedIssuesResponse, mythx_models.response.group_creation.GroupCreationResponse, mythx_models.response.group_list.GroupListResponse, mythx_models.response.group_operation.GroupOperationResponse, mythx_models.response.group_status.GroupStatusResponse, mythx_models.response.project_creation.ProjectCreationResponse, mythx_models.response.project_deletion.ProjectDeletionResponse, mythx_models.response.project_list.ProjectListResponse, mythx_models.response.project_status.ProjectStatusResponse, mythx_models.response.project_update.ProjectUpdateResponse, mythx_models.response.version.VersionResponse]

Sequentially execute the registered response middlewares.

Each middleware gets the serialized response domain model. On top of the request any manipulations can be made. Furthermode, each domain model’s helper methods can be used.

It is worth mentioning here that this is a simple loop iterating over the middleware list, calling each middleware’s process_response method. It is expected that each registered middleware exposes this method and returns a domain model of the same type as the one passed in. It also means that the order in which middlewares are registered can matter, even though it is recommended that middlewares are kept associative in nature.

Parameters:resp – The response domain model Returns:The updated response domain model - ready to be passed on to the user

parse_response(resp: dict, model_cls: Type[Union[mythx_models.response.analysis_input.AnalysisInputResponse, mythx_models.response.analysis_list.AnalysisListResponse, mythx_models.response.analysis_status.AnalysisStatusResponse, mythx_models.response.analysis_submission.AnalysisSubmissionResponse, mythx_models.response.auth_login.AuthLoginResponse, mythx_models.response.auth_logout.AuthLogoutResponse, mythx_models.response.auth_refresh.AuthRefreshResponse, mythx_models.response.detected_issues.DetectedIssuesResponse, mythx_models.response.group_creation.GroupCreationResponse, mythx_models.response.group_list.GroupListResponse, mythx_models.response.group_operation.GroupOperationResponse, mythx_models.response.group_status.GroupStatusResponse, mythx_models.response.project_creation.ProjectCreationResponse, mythx_models.response.project_deletion.ProjectDeletionResponse, mythx_models.response.project_list.ProjectListResponse, mythx_models.response.project_status.ProjectStatusResponse, mythx_models.response.project_update.ProjectUpdateResponse, mythx_models.response.version.VersionResponse]]) → Union[mythx_models.response.analysis_input.AnalysisInputResponse, mythx_models.response.analysis_list.AnalysisListResponse, mythx_models.response.analysis_status.AnalysisStatusResponse, mythx_models.response.analysis_submission.AnalysisSubmissionResponse, mythx_models.response.auth_login.AuthLoginResponse, mythx_models.response.auth_logout.AuthLogoutResponse, mythx_models.response.auth_refresh.AuthRefreshResponse, mythx_models.response.detected_issues.DetectedIssuesResponse, mythx_models.response.group_creation.GroupCreationResponse, mythx_models.response.group_list.GroupListResponse, mythx_models.response.group_operation.GroupOperationResponse, mythx_models.response.group_status.GroupStatusResponse, mythx_models.response.project_creation.ProjectCreationResponse, mythx_models.response.project_deletion.ProjectDeletionResponse, mythx_models.response.project_list.ProjectListResponse, mythx_models.response.project_status.ProjectStatusResponse, mythx_models.response.project_update.ProjectUpdateResponse, mythx_models.response.version.VersionResponse]

Parse the API response into its respective domain model variant.

This method takes the raw HTTP response and a class it should deserialize the responsse data into. As each domain model implements the from_json method, we simply call it on the raw input data and return the resulting model.

If a deserialization or validation error is raised, it is not caught and directly passed on to the user.

Parameters:

• resp – The raw HTTP response JSON payload
• model_cls – The domain model class the data should be deserialized into

Returns:

The domain model holding the response data

static send_request(request_data: Dict[KT, VT], auth_header: Dict[str, str] = None) → Dict[KT, VT]

Send a request to the API.

This method takes a data dictionary holding the request’s method (HTTP verb), any additional headers, the URL to send the request to, its payload, and any URL parameters it requires. This dictionary is generated by the APIHandler.assemble_request method.

An example for getting the detected issues for an analysis job’s UUID:

{
    "method": "GET",
    "headers": {},
    "url": "https://api.mythx.io/v1/analyses/<uuid>/issues",
    "payload": "",
    "params": {}
}

If the action requires authentication, the auth headers are passed in a separate, optional parameter. It holds the user’s JWT access token.

If the request fails (returns a non 200 status code), a MythXAPIError is raised.

Parameters:

• request_data – The request data dictionary
• auth_header – The authorization header carrying the access token

Returns:

The raw response payload string

pythx.api.handler.print_request(req: requests.models.PreparedRequest) → str

Generate a pretty-printed HTTP request string.

Parameters:req – The prepared requests HTTP request Returns:Pretty HTTP request string

pythx.api.handler.print_response(res: requests.models.Response) → str

Generate a pretty-printed HTTP response string.

Parameters:res – The received requests HTTP response Returns:Pretty HTTP response string

Module contents

This package contans the API request handler and Client implementations.