BitBaan » API Help

You can communicate with the system by using the API. The API input and output format are based on JSON standard. In this section, you will learn how to use this API.

Logging in to the system

You can use https://malab.bitbaan.com/api/v1/user/login to log in to the system. This call has the following parameters:

  • email: User’s email address.
  • password: User’s password.

For example, you can use this call in this way in curl:

curl --request POST \
--header "Content-Type: application/json" \
--data '{"email":"your_email_address", "password":"your_password"}' \
https://malab.bitbaan.com/api/v1/user/login

The output of call will be like this if it is successful:

{"success": true,"apikey": "your_api_key"}

Scanning file

For scanning the file you can use https://malab.bitbaan.com/api/v1/scan This call has the following parameters:

  • apikey: Your API key.
  • filedata: The content of the file.
  • filename: Name of the file.
  • is_private (optional): Should the file be scanned privately?
  • fileorigin (optional): Origin of the file (This parameter should be sent only when you have the necessary permissions to submit the origin of the file.)

For example, you can use this call in this way in curl:

curl -F "[email protected]_file_path" \
-F "apikey=your_api_key" \
-F "filename=your_filename" \
-F "is_private=false" \
-F "fileorigin=https://t.me/sample/10" \
https://malab.bitbaan.com/api/v1/scan

The output of call will be like this if it is successful:

{"success": true,"scan_id":your_scan_id}

Getting the scan result

You can use https://malab.bitbaan.com/api/v1/search/scan/results to get the result of the scan. This call has the following parameters:

For example, you can use this call in this way in curl:

curl --request POST \
--header "Content-Type: application/json" \
--data '{"sha256":"your_sha256", \
"apikey":"your_api_key", \
"scan_id":"your_scan_id"}' \
https://malab.bitbaan.com/api/v1/search/scan/results

The output of call will be like this if it is successful:

{"success": true,"scan_id":your_scan_id, "is_finished": true, \
"clearance":0,"infection":2, "error":0, "file_size":131072, \
"file_name": ["your_file_name_1", "your_file_name_2", …], \
"official_analysis": "official_analysis_in_base64", \
"origins": [{"type":"web", "address": "https://google.com/"}, \
{"type":"telegram", "address": "https://t.me/sample/10"}], \
"md5":"file_md5","sha1":"file_sha1","sha256":"file_sha256", \
"created_at":"2018/11/27 11:19", \
"results": [{"av_id": 0, "av_name": "AhnLab v3", "av_version": "8.0", \
"av_update_date": "2018/12/11", "created_at": "2018/12/11 06:24", \
"result": "Clear", "result_state": 33, "result_state_param": 0}, \
{"av_id": 1, "av_name": "Avast Internet Security", "av_version": "10.1", \
"av_update_date": "2018/12/08" "created_at": "2018/12/11 06:25", \
"result": "Trojan/Win32.MDA", "result_state": 32, "result_state_param": 0} \
]}

Some outputs of this call need to be explained:

  • is_finished: The scan is finished or not?
  • result_state: It specifies the scan status. This output can be equal to one of the following values:
    • 0: Scanning operation has not started yet.
    • 1: Scanning operation has just begun.
    • 2: Scanning is in progress.
    • 3: Scanning is in the queue(In this case, the value of result_state_param specifies the number of the current scan in the queue)
    • 30: The scan has ended with a timeout error.
    • 31: The scan has failed.
    • 32: The scan has been completed and malware has been found. (The name of the malware is placed in the result)
    • 33: The scan is completed and no malware has been found.

Rescanning the file

If the file has already been scanned, the https://malab.bitbaan.com/api/v1/scan call returns the last scan result. You can use https://malab.bitbaan.com/api/v1/rescan to rescan the file. This call has the following parameters:

  • apikey: Your API key.
  • sha256

For example, you can use this call in this way in curl:

curl --request POST \
--header "Content-Type: application/json" \
--data '{"sha256":"your_sha256", \
"apikey":"your_api_key"}' \
https://malab.bitbaan.com/api/v1/rescan

The output of call will be like this if it is successful:

{"success": true,"scan_id":your_scan_id}

Searching by hash

You should use https://malab.bitbaan.com/api/v1/search/scan/hash to search by hash.This call has the following parameters:

  • apikey: Your API key.
  • hash: Either a md5/sha1/sha256 hash.
  • ot (optional): It can be one of the following values:
    • 1: Descending order
    • 2: Ascending order
  • ob (optional): It can be one of the following values:
    • 1: Sort by file name
    • 2: Sort by file size..
    • 3: Sort by MD5.
    • 4: Sort by SHA1.
    • 5: Sort by SHA256.
    • 6: Sort by the date added to the database.
    • 7: Sort by detection rate.
  • page (optional) : The page number of the search result
  • per_page (optional): The number of results per page.

For example, you can use this call in this way in curl:

curl --request POST \
--header "Content-Type: application/json" \
--data '{"hash":"your_hash", \
"apikey":"your_api_key", \
"ob":"1", \
"ot":"1", \
"page":"1", \
"per_page":"15"}' \
https://malab.bitbaan.com/api/v1/search/scan/hash

The output of call will be like this if it is successful:

{"success":true, "total_records":1, \
,"records":[{"scan_id":19, \
"clearance":0,"infection":2, "error":0, "file_size":131072, \
"file_name": ["your_file_name_1", "your_file_name_2", …], \
"official_analysis": "official_analysis_in_base64", \
"origins": [{"type":"web", "address": "https://google.com/"}, \
{"type":"telegram", "address": "https://t.me/sample/10"}], \
"md5":"file_md5","sha1":"file_sha1","sha256":"file_sha256", \
"is_finished": true,"created_at":"2018/11/27 11:19", \
"results": [{"av_id": 0, "av_name": "AhnLab v3", "av_version": "8.0", \
"av_update_date": "2018/12/11", "created_at": "2018/12/11 06:24", \
"result": "Clear", "result_state": 33, "result_state_param": 0}, \
{"av_id": 1, "av_name": "Avast Internet Security", "av_version": "10.1", \
"av_update_date": "2018/12/08" "created_at": "2018/12/11 06:25", \
"result": "Trojan/Win32.MDA", "result_state": 32,"result_state_param": 0}] \
}]}

Some outputs of this call need to be explained:

  • is_finished: The scan is finished or not?
  • clearance: The count of antimalware that identified the file as clean.
  • infection: The count of antimalware that detected the file as malware.

Searching by malware name

You should use https://malab.bitbaan.com/api/v1/search/scan/malware-name to search by malware name

This call has the following parameters:

  • apikey: Your API key.
  • malware_name
  • ot (optional): It can be one of the following values:
    • 1: Descending order
    • 2: Ascending order
  • ob (optional): It can be one of the following values:
    • 1: Sort by file name
    • 2: Sort by file size..
    • 3: Sort by MD5.
    • 4: Sort by SHA1.
    • 5: Sort by SHA256.
    • 6: Sort by the date added to the database.
    • 7: Sort by detection rate.
  • page (optional) : The page number of the search result
  • per_page (optional): The number of results per page.

For example, you can use this call in this way in curl:

curl --request POST \
--header "Content-Type: application/json" \
--data '{"malware_name":"your_malware_name", \
"apikey":"your_api_key", \
"ob":"1", \
"ot":"1", \
"page":"1", \
"per_page":"15"}' \
https://malab.bitbaan.com/api/v1/search/scan/malware-name

The output of call will be like this if it is successful:

{"success":true, "total_records":1, \
,"records":[{"scan_id":19, \
"clearance":0,"infection":2, "error":0, "file_size":131072, \
"file_name": ["your_file_name_1", " your_file_name_2", …], \
"official_analysis": "official_analysis_in_base64", \
"origins": [{"type":"web", "address": "https://google.com/"}, \
{"type":"telegram", "address": "https://t.me/sample/10"}], \
"md5":"file_md5","sha1":"file_sha1","sha256":"file_sha256", \
"is_finished": true,"created_at":"2018/11/27 11:19" \
"results": [{"av_id": 0, "av_name": "AhnLab v3", "av_version": "8.0", \
"av_update_date": "2018/12/11", "created_at": "2018/12/11 06:24", \
"result": "Clear", "result_state": 33, "result_state_param": 0}, \
{"av_id": 1, "av_name": "Avast Internet Security", "av_version": "10.1", \
"av_update_date": "2018/12/08" "created_at": "2018/12/11 06:25", \
"result": "Trojan/Win32.MDA", "result_state": 32,"result_state_param": 0}] \
}]}

Some outputs of this call need to be explained:

  • is_finished: The scan is finished or not?
  • clearance: The count of antimalware that identified the file as clean.
  • infection: The count of antimalware that detected the file as malware.

Downloading file

To download the file, use https://malab.bitbaan.com/api/v1/file/download This call has the following parameters:

  • apikey: Your API key.
  • hash: Either a md5/sha1/sha256 hash.

The output of call will be like this if it is successful:

{"success":true, "file_data":"your_file_data_in_base64"}

Viewing comments

You should use https://malab.bitbaan.com/api/v1/comment call to view comments. This call has the following parameters:

  • apikey: Your API key.
  • sha256
  • page (optional): Page number.
  • per_page (optional): The number of comments per page.

For example, you can use this call in this way in curl:

curl --request POST \
--header "Content-Type: application/json" \
--data '{"apikey":"your_api_key", \
"sha256":"your_sha256", \
"page":"1", \
"per_page":"15"}' \
https://malab.bitbaan.com/api/v1/three

The output of call will be like this if it is successful:

{"success": true, "total_comments":2, \
"comments":[{"comment_id":41,"description":"your_comment_descrption1", \
"user_id":4,"created_at":"2018/11/27 06:10","is_reviewed": false}, \
{"comment_id":42,"description":" your_comment_descrption2", \
"user_id":3,"created_at":"2018/11/27 06:10","is_reviewed": true}]}

Adding comment

You should use https://malab.bitbaan.com/api/v1/comment/add call to add a comment. This call has the following parameters:

  • apikey: Your API key.
  • sha256
  • description

For example, you can use this call in this way in curl:

curl --request POST \
--header "Content-Type: application/json" \
--data '{"apikey":"your_api_key", \
"description":"your_description", \
"sha256":"your_sha256"}' \
https://malab.bitbaan.com/api/v1/comment/add

The output of call will be like this if it is successful:

{"success": true, "comment_id":"your_comment_id"}

Editing comment

You should use https://malab.bitbaan.com/api/v1/comment/edit call to edit a comment. This call has the following parameters:

  • apikey: Your API key.
  • comment_id
  • description

For example, you can use this call in this way in curl:

curl --request POST \
--header "Content-Type: application/json" \
--data '{"apikey":"your_api_key", \
"comment_id":"your_comment_id", \
"description":"your_description"}' \
https://malab.bitbaan.com/api/v1/comment/edit

The output of call will be like this if it is successful:

{"success": true}

Deleting comment

You should use https://malab.bitbaan.com/api/v1/comment/delete call to delete a comment. This call has the following parameters:

  • apikey: Your API key.
  • comment_id

For example, you can use this call in this way in curl:

curl --request POST \
--header "Content-Type: application/json" \
--data '{"apikey":"your_api_key", \
"comment_id":"your_comment_id"}' \
https://malab.bitbaan.com/api/v1/comment/delete

The output of call will be like this if it is successful:

{"success": true}

Approving comment

You should use https://malab.bitbaan.com/api/v1/comment/approve call to approve a comment. This call has the following parameters:

  • apikey: Your API key.
  • comment_id

For example, you can use this call in this way in curl:

curl --request POST \
--header "Content-Type: application/json" \
--data '{"apikey":"your_api_key", \
"comment_id":"your_comment_id"}' \
https://malab.bitbaan.com/api/v1/comment/approve

The output of call will be like this if it is successful:

{"success": true}

You should use https://malab.bitbaan.com/api/v1/search/scan/advanced call for advanced search in the database of the system.

Note: This call can only be used by commercial and verified users of the system.

This call has the following parameters:

  • apikey: Your API key.
  • scan_id (optional): Scan identification number.
  • filename (optional): Filename for searching.
  • malware_name (optional): The name of the malware to search.
  • hash (optional): Either a md5/sha1/sha256 hash.
  • origin (optional): Origin of the file to search.
  • analyzed (optional): Has the file been officially analyzed?
  • has_origin (optional): Has the origin of the file been specified?
  • ot (optional): It can be one of the following values:
    • 1: Descending order
    • 2: Ascending order
  • ob (optional): It can be one of the following values:
    • 1: Sort by file name
    • 2: Sort by file size..
    • 3: Sort by MD5.
    • 4: Sort by SHA1.
    • 5: Sort by SHA256.
    • 6: Sort by the date added to the database.
    • 7: Sort by detection rate.
  • page (optional) : The page number of the search result
  • per_page (optional): The number of results per page.

For example, you can use this call in this way in curl:

curl --request POST \
--header "Content-Type: application/json" \
--data '{"apikey":"your_api_key", \
"scan_id":"your_scan_id", \
"filename":"your_filename", \
"malware_name":"your_malware_name", \
"hash":"your_hash", \
"origin": [{"type": "web", "address": "https://google.com/"}], \
"analyzed": true, \
"has_origin": true, \
"ot":"1", \
"ob":"1", \
"page":"1",
"per_page":"15"}' \
https://malab.bitbaan.com/api/v1/search/scan/advanced

The output of call will be like this if it is successful:

{"success":true, "total_records":1, \
,"records":[{"scan_id":19, \
"clearance":0,"infection":2, "error":0, "file_size":131072, \
"file_name": ["your_file_name_1", " your_file_name_2", …], \
"official_analysis": "official_analysis_in_base64", \
"origins": [{"type":"web", "address": "https://google.com/"}, \
{"type":"telegram", "address": "https://t.me/sample/10"}], \
"md5":"file_md5","sha1":"file_sha1","sha256":"file_sha256", \
"is_finished": true,"created_at":"2018/11/27 11:19", \
"results": [{"av_id": 0, "av_name": "AhnLab v3", "av_version": "8.0", \
"av_update_date": "2018/12/11", "created_at": "2018/12/11 06:24", \
"result": "Clear", "result_state": 33, "result_state_param": 0}, \
{"av_id": 1, "av_name": "Avast Internet Security", "av_version": "10.1", \
"av_update_date": "2018/12/08" "created_at": "2018/12/11 06:25", \
"result": "Trojan/Win32.MDA", "result_state": 32,"result_state_param": 0}] \
}]}

Getting the captcha

For doing some tasks, like signing up into the system, you need to get a captcha. To get a new captcha https://malab.bitbaan.com/api/v1/captcha is used.

For example, you can use this call in this way in curl:

curl --request POST \
--header "Content-Type: application/json" \
https://malab.bitbaan.com/api/v1/captcha

The output of call will be like this if it is successful:

{"success": true, "captcha": "your_captcha_in_base64"}

Signing up into the system

You should use https://malab.bitbaan.com/api/v1/user/register call to sign up into the system. This call has the following parameters:

  • firstname
  • lastname
  • username
  • email
  • password
  • captcha: Captcha response

For example, you can use this call in this way in curl:

curl --request POST \
--header "Content-Type: application/json" \
--data '{"firstname":"your_firstname", \
"lastname":"your_lastname", \
"username":"your_username", \
"email":"your_email_address", \
"password":"your_password", \
"captcha":"your_captcha_response"}' \
https://malab.bitbaan.com/api/v1/user/register

The output of call will be like this if it is successful:

{"success": true}

Getting antimalware list

You should use https://malab.bitbaan.com/api/v1/search/av_list call to get the list of offline and online antimalware.

For example, you can use this call in this way in curl:

curl --request POST \
--header "Content-Type: application/json" \
https://malab.bitbaan.com/api/v1/search/av_list

The output of call will be like this if it is successful:

{"success": true, "av_names": ["Baidu Antivirus", "Comodo Antivirus"]}

Errors

If any of the API calls fail, the following output will be returned:

{"success": false, "error_code": "your_error_code", "error_description": "your_error_description"}