docs/quick_start.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Quick start"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook gives an example on how to use this SDK to upload, start analysis and get the analysis result of a file."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initialize\n",
    "\n",
    "To initialize the SDK, please prepare your Secret ID and Secret Key. Please [apply from us](https://www.binaryai.cn/doc/) if\n",
    "you don't have one.\n",
    "\n",
    "The Secret ID & Key is the *only* credential to access API, so please keep it safely. We recommend you read your keys to\n",
    "environment variable, instead of saving in your code:\n",
    "\n",
    "```bash\n",
    "$ read BINARYAI_SECRET_ID\n",
    "#(enter your secret id)\n",
    "$ read BINARYAI_SECRET_KEY\n",
    "#(enter your secret key)\n",
    "$ export BINARYAI_SECRET_ID\n",
    "$ export BINARYAI_SECRET_KEY\n",
    "```\n",
    "\n",
    "Once those environment variables are set, our SDK can read them directly.\n",
    "\n",
    "To initialize the SDK:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Uncomment to get more logs\n",
    "# import logging\n",
    "# logging.basicConfig(stream=sys.stdout, level=logging.INFO)\n",
    "# logger = logging.getLogger(\"binaryai_sdk\")\n",
    "\n",
    "from binaryai import BinaryAI\n",
    "\n",
    "bai = BinaryAI() # Initialize the client"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Great! If no exceptions raised, the client is initialized."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Upload and analyze file\n",
    "\n",
    "Note: file upload might be rejected if file is too big or upload is too quick.\n",
    "\n",
    "Now you can upload by the file path:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "analysis succeed\n"
     ]
    }
   ],
   "source": [
    " # if upload succeed, file hash is returned\n",
    "sha256 = bai.upload(\"/bin/echo\")\n",
    "\n",
    "# wait until done. timeout=-1 means wait forever\n",
    "bai.wait_until_analysis_done(sha256, timeout=-1)\n",
    "\n",
    "print(\"analysis succeed\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get analysis result\n",
    "\n",
    "You can get analysis result by giving hash of a file for each method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'fileType': 'ELF64',\n",
       " 'machine': 'AMD64',\n",
       " 'platform': 'LINUX',\n",
       " 'endian': 'LITTLE_ENDIAN',\n",
       " 'loader': 'x86:LE:64:default',\n",
       " 'entryPoint': 1059200,\n",
       " 'baseAddress': 1048576}"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "bai.get_overview(sha256)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1: _DT_INIT]\n",
      "[2: FUN_00102020]\n",
      "[3: <EXTERNAL>::getenv]\n",
      "[4: <EXTERNAL>::free]\n",
      "[5: <EXTERNAL>::abort]\n",
      "[6: <EXTERNAL>::__errno_location]\n",
      "[7: <EXTERNAL>::strncmp]\n",
      "[8: <EXTERNAL>::_exit]\n",
      "[9: <EXTERNAL>::__fpending]\n",
      "[10: <EXTERNAL>::textdomain]\n",
      "[11: <EXTERNAL>::fclose]\n",
      "[12: <EXTERNAL>::bindtextdomain]\n"
     ]
    }
   ],
   "source": [
    "funcs = bai.list_funcs(sha256)\n",
    "for i, f in enumerate(funcs):\n",
    "    print(\"[{}: {}]\".format(i+1, f.name))\n",
    "    if i > 10:\n",
    "        break"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or initialize a file object and call it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "reptile\n",
      "----\n",
      "tsh\n",
      "----\n"
     ]
    }
   ],
   "source": [
    "from binaryai import BinaryAIFile\n",
    "# This pair of hash is the same file\n",
    "sha256 = \"289616b59a145e2033baddb8a8a9b5a8fb01bdbba1b8cf9acadcdd92e6cc0562\"\n",
    "md5 = \"c3366c6b688a5b5fa4451fec09930e06\"\n",
    "bai_file = BinaryAIFile(bai, md5=md5)\n",
    "for component in bai_file.get_sca_result():\n",
    "    print(component.name)\n",
    "    print(\"----\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As shown above, you can always give a file hash (md5 or sha256) to get its analysis result.\n",
    "\n",
    "Read `examples/` in SDK repository or read the SDK API document for more info."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "binaryai-YJgBNhjL-py3.9",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.18"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}