بیت‌بان » راهنمای API

شما می‏‌توانید با استفاده از API بیت‏‌بان با سامانه ارتباط برقرار نمایید. فرمت ورودی و خروجی API مبتنی بر استاندارد JSON می‏‌باشد. در این بخش با طریقه استفاده از این API آشنا خواهیم شد.

ورود به سامانه

برای ورود به سامانه می‌توانید از فراخوانی https://malab.bitbaan.com/api/v1/user/login استفاده نمایید. این فراخوانی دارای ورودی‌‏های زیر می‏‌باشد:

  • email: آدرس ایمیل کاربر.
  • password: رمز عبور کاربر.

به عنوان مثال در 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

خروجی فراخوانی در صورت موفقیت همانند زیر خواهد بود:

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

پویش فایل

برای پویش فایل می‌‏توانید از فراخوانی https://malab.bitbaan.com/api/v1/scan استفاده نمایید. این فراخوانی دارای ورودی‏‌های زیر می‏‌باشد:

  • apikey: کلید API جهت ارتباط با سامانه.
  • filedata: محتوای فایل.
  • filename: نام فایل.
  • is_private (اختیاری): آیا فایل باید به صورت محرمانه پویش شود؟
  • fileorigin (اختیاری): منشا انتشار فایل. (این پارامتر تنها زمانی باید ارسال شود که شما مجوزهای لازم برای ثبت منشا انتشار فایل را داشته باشید.)

به عنوان مثال در 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

خروجی فراخوانی در صورت موفقیت همانند زیر خواهد بود:

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

دریافت نتیجه پویش

برای دریافت نتیجه پویش می‏‌توانید از فراخوانی https://malab.bitbaan.com/api/v1/search/scan/results استفاده نمایید. این فراخوانی دارای ورودی‏های زیر است:

  • apikey: کلید API جهت ارتباط با سامانه.
  • scan_id: شماره شناسایی پویش. (خروجی فراخوانی https://malab.bitbaan.com/api/v1/scan)
  • sha256: مقدار SHA256 فایل.

به عنوان مثال در 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

خروجی فراخوانی در صورت موفقیت همانند زیر خواهد بود:

{"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} \
]}

برخی از خروجی‏‌های این فراخوانی نیاز به توضیح دارند:

  • is_finished: مشخص می‏‌کند که آیا روال پویش به اتمام رسیده است یا خیر؟
  • result_state: وضعیت پویش را مشخص می‏‌کند. این خروجی می‏تواند برابر با یکی از مقادیر زیر باشد:
    • 0: عملیات پویش هنوز شروع نشده است.
    • 1: عملیات پویش تازه شروع شده است.
    • 2: پویش در حال انجام می‏‌باشد.
    • 3: پویش در صف می‏‌باشد. (در این حالت مقدار result_state_param مشخص می‌‏کند که پویش فعلی، نفر چندم در صف می‏‌باشد.)
    • 30: پویش با خطای «عدم پاسخگویی در بازه زمان مورد انتظار» پایان یافته است.
    • 31: پویش به خطا خورده است.
    • 32: پویش به اتمام رسیده است و یک بدافزار یافت شده است. (نام بدافزار در result قرار می‏‌گیرد.)
    • 33: پویش به اتمام رسیده است و هیچ بدافزاری یافت نشده است.

پویش دوباره فایل

فراخوانی https://malab.bitbaan.com/api/v1/scan چنانچه فایل قبلا پویش شده باشد، آخرین نتیجه پویش را برمی‏‌گرداند. برای پویش دوباره فایل می‏‌توانید از فراخوانی https://malab.bitbaan.com/api/v1/rescan استفاده نمایید. این فراخوانی دارای ورودی‏‌های زیر است:

  • apikey: کلید API جهت ارتباط با سامانه.
  • sha256: مقدار SHA256 فایل.

به عنوان مثال در curl می‌‏توانید به این صورت از این فراخوانی استفاده نمایید:

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

خروجی فراخوانی در صورت موفقیت همانند زیر خواهد بود:

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

جستجو بر حسب چکیده

برای جستجو بر حسب چکیده از فراخوانی https://malab.bitbaan.com/api/v1/search/scan/hash استفاده می‌‏شود. این فراخوانی دارای ورودی‏‌های زیر است:

  • apikey: کلید API جهت ارتباط با سامانه.
  • hash: مقدار MD5 یا SHA1 یا SHA256 فایل.
  • ot (اختیاری): طریقه مرتب‏‌سازی که برابر با یکی از مقادیر زیر است:
    • 1: مرتب‏‌سازی نزولی.
    • 2: مرتب‏‌سازی صعودی.
  • ob (اختیاری): نوع مرتب‏‌سازی که برابر با یکی از مقادیر زیر است:
    • 1: مرتب‏‌سازی بر حسب نام فایل.
    • 2: مرتب‏‌سازی بر حسب اندازه فایل.
    • 3: مرتب‏‌سازی بر حسب مقدار MD5.
    • 4: مرتب‏‌سازی بر حسب مقدار SHA1.
    • 5: مرتب‏‌سازی بر حسب مقدار SHA256.
    • 6: مرتب‏‌سازی بر حسب تاریخ اضافه‏‌شدن به پایگاه داده
    • 7: مرتب‏‌سازی بر اساس نرخ شناسایی.
  • page (اختیاری): شماره صفحه نتیجه جستجو.
  • per_page(اختیاری): تعداد نتیجه در هر صفحه.

به عنوان مثال در 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

خروجی فراخوانی در صورت موفقیت همانند زیر خواهد بود:

{"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}] \
}]}

برخی از خروجی‏‌های این فراخوانی نیاز به توضیح دارند:

  • is_finished: مشخص می‏‌کند که آیا روال پویش به اتمام رسیده است یا خیر؟
  • clearance: تعداد ضدویروس‏‌هایی که فایل را پاک شناخته‏‌اند.
  • infection: تعداد ضدویروس‏‌هایی که فایل را بدافزار شناخته‌‏اند.

جستجو بر حسب نام بدافزار

برای جستجو بر حسب نام بدافزار از فراخوانی https://malab.bitbaan.com/api/v1/search/scan/malware-name استفاده می‏شود.

این فراخوانی دارای ورودی‏‌ های زیر است:

  • apikey: کلید API جهت ارتباط با سامانه.
  • malware_name: نام بدافزار برای جستجو.
  • ot (اختیاری): طریقه مرتب‏‌سازی که برابر با یکی از مقادیر زیر است:
    • 1: مرتب‏‌سازی نزولی.
    • 2: مرتب‏‌سازی صعودی.
  • ob (اختیاری): نوع مرتب‏‌سازی که برابر با یکی از مقادیر زیر است:
    • 1: مرتب‏‌سازی بر حسب نام فایل.
    • 2: مرتب‏‌سازی بر حسب اندازه فایل.
    • 3: مرتب‏‌سازی بر حسب مقدار MD5.
    • 4: مرتب‏‌سازی بر حسب مقدار SHA1.
    • 5: مرتب‏‌سازی بر حسب مقدار SHA256.
    • 6: مرتب‏‌سازی بر حسب تاریخ اضافه‏‌شدن به پایگاه داده
    • 7: مرتب‏‌سازی بر اساس نرخ شناسایی.
  • page (اختیاری): شماره صفحه نتیجه جستجو.
  • per_page(اختیاری): تعداد نتیجه در هر صفحه.

به عنوان مثال در 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

خروجی فراخوانی در صورت موفقیت همانند زیر خواهد بود:

{"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}] \
}]}

برخی از خروجی‏‌های این فراخوانی نیاز به توضیح دارند:

  • is_finished: مشخص می‏‌کند که آیا روال پویش به اتمام رسیده است یا خیر؟
  • clearance: تعداد ضدویروس‏‌هایی که فایل را پاک شناخته‏‌اند.
  • infection: تعداد ضدویروس‏‌هایی که فایل را بدافزار شناخته‌‏اند.

دانلود فایل

برای دانلود فایل از فراخوانی https://malab.bitbaan.com/api/v1/file/download استفاده می‌‏شود. این فراخوانی دارای ورودی‏‌های زیر است:

  • apikey: کلید API جهت ارتباط با سامانه.
  • hash: مقدار MD5 یا SHA1 یا SHA256 فایل.

خروجی فراخوانی در صورت موفقیت همانند زیر خواهد بود:

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

مشاهده دیدگاه‏‌ها

برای مشاهده دیدگاه‏‌ها از فراخوانی https://malab.bitbaan.com/api/v1/comment استفاده می‏‌شود. این فراخوانی دارای ورودی‏‌های زیر است:

  • apikey: کلید API جهت ارتباط با سامانه.
  • sha256: مقدار SHA256 فایل.
  • page (اختیاری): شماره صفحه.
  • per_page (اختیاری): تعداد خروجی در هر صفحه.

به عنوان مثال در 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

خروجی فراخوانی در صورت موفقیت همانند زیر خواهد بود:

{"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}]}

اضافه کردن دیدگاه

برای اضافه کردن دیدگاه از فراخوانی https://malab.bitbaan.com/api/v1/comment/add استفاده می‌‏شود. این فراخوانی دارای ورودی‏‌های زیر است:

  • apikey: کلید API جهت ارتباط با سامانه.
  • sha256: مقدار SHA256 فایل.
  • description: متن دیدگاه.

به عنوان مثال در 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

خروجی فراخوانی در صورت موفقیت همانند زیر خواهد بود:

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

ویرایش دیدگاه

برای ویرایش دیدگاه از فراخوانی https://malab.bitbaan.com/api/v1/comment/edit استفاده می‏‌شود. این فراخوانی دارای ورودی‏‌های زیر است:

  • apikey: کلید API جهت ارتباط با سامانه.
  • comment_id: شماره شناسایی دیدگاه.
  • description: متن جدید دیدگاه.

به عنوان مثال در 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

خروجی فراخوانی در صورت موفقیت همانند زیر خواهد بود:

{"success": true}

حذف دیدگاه

برای حذف دیدگاه از فراخوانی https://malab.bitbaan.com/api/v1/comment/delete استفاده می‌‏شود. این فراخوانی دارای ورودی‏‌های زیر است:

  • apikey: کلید API جهت ارتباط با سامانه.
  • comment_id: شماره شناسایی دیدگاه.

به عنوان مثال در 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

خروجی فراخوانی در صورت موفقیت همانند زیر خواهد بود:

{"success": true}

تایید دیدگاه

برای تایید دیدگاه از فراخوانی https://malab.bitbaan.com/api/v1/comment/approve استفاده می‏‌شود. این فراخوانی دارای ورودی‏‌های زیر است:

  • apikey: کلید API جهت ارتباط با سامانه.
  • comment_id: شماره شناسایی دیدگاه.

به عنوان مثال در 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

خروجی فراخوانی در صورت موفقیت همانند زیر خواهد بود:

{"success": true}

برای جستجوی پیشرفته در پایگاه داده سامانه از فراخوانی https://malab.bitbaan.com/api/v1/search/scan/advanced استفاده می‌‏شود.

نکته: این فراخوانی تنها توسط کاربران تجاری و تاییدشده سامانه قابل استفاده است.

این فراخوانی دارای ورودی‏‌ های زیر است:

  • apikey: کلید API جهت ارتباط با سامانه.
  • scan_id(اختیاری): شماره شناسایی پویش.
  • filename (اختیاری): نام فایل جهت جستجو.
  • malware_name (اختیاری): نام بدافزار جهت جستجو.
  • hash (اختیاری): مقدار MD5 یا SHA1 یا SHA256 فایل جهت جستجو.
  • origin (اختیاری): منشا انتشار فایل جهت جستجو.
  • analyzed (اختیاری): آیا فایل قبلا به صورت رسمی تحلیل شده است؟
  • has_origin(اختیاری): آیا منشا انتشار فایل مشخص شده‌است؟
  • ot (اختیاری): طریقه مرتب‏‌سازی که برابر با یکی از مقادیر زیر است:
    • 1: مرتب‏‌سازی نزولی.
    • 2: مرتب‏‌سازی صعودی.
  • ob (اختیاری): نوع مرتب‏‌سازی که برابر با یکی از مقادیر زیر است:
    • 1: مرتب‏‌سازی بر حسب نام فایل.
    • 2: مرتب‏‌سازی بر حسب اندازه فایل.
    • 3: مرتب‏‌سازی بر حسب مقدار MD5.
    • 4: مرتب‏‌سازی بر حسب مقدار SHA1.
    • 5: مرتب‏‌سازی بر حسب مقدار SHA256.
    • 6: مرتب‏‌سازی بر حسب تاریخ اضافه‏‌شدن به پایگاه داده
    • 7: مرتب‏‌سازی بر اساس نرخ شناسایی.
  • page (اختیاری): شماره صفحه نتیجه جستجو.
  • per_page(اختیاری): تعداد نتیجه در هر صفحه.

به عنوان مثال در 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", \
"origins": [{"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

خروجی فراخوانی در صورت موفقیت همانند زیر خواهد بود:

{"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}] \
}]}

دریافت تصویر‌‌ امنیتی

برای برخی کارها همانند ثبت‏‌نام در سیستم نیاز است که یک تصویر امنیتی از سامانه دریافت نمایید. برای دریافت تصویر امنیتی جدید از https://malab.bitbaan.com/api/v1/captcha استفاده می‌‏شود.

به عنوان مثال در curl می‌‏توانید به این صورت از این فراخوانی استفاده نمایید:

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

خروجی فراخوانی در صورت موفقیت همانند زیر خواهد بود:

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

ثبت‏‌‌نام در سامانه

برای ثبت‏‌نام در سامانه از فراخوانی https://malab.bitbaan.com/api/v1/user/register استفاده نمایید. این فراخوانی دارای ورودی‏‌های زیر است:

  • firstname: نام.
  • lastname: نام خانوادگی.
  • username: نام کاربری.
  • email: آدرس پست الکترونیکی.
  • password: رمز عبور.
  • captcha: پاسخ تصویر امنیتی.

به عنوان مثال در 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

خروجی فراخوانی در صورت موفقیت همانند زیر خواهد بود:

{"success": true}

لیست ضدبدافزارها

برای گرفتن لیست ضدبدافزارهای سامانه از فراخوانی https://malab.bitbaan.com/api/v1/search/av_list استفاده نمایید.

به عنوان مثال در curl می‌‏توانید به این صورت از این فراخوانی استفاده نمایید:

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

خروجی فراخوانی در صورت موفقیت همانند زیر خواهد بود:

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

رخداد خطا

در صورت عدم موفقیت هر کدام از فراخوانی‏‌های API یک خروجی همانند زیر برگردانده می‌‏شود:

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

API نمونه کدهای

برای زبان های مشهور چند نمونه کد برای استفاده از API ارائه شده است: