{ "info": { "author": "Red Balloon Security", "author_email": "quack-tech@redballoonsecurity.com", "bugtrack_url": null, "classifiers": [], "description": "# BAL Xilinx Overview\n\nThe BAL Xilinx package is an implementation of the \n[Binary Abstraction Layer (BAL)](https://github.com/ballon-rouge/bal) framework for Xilinx FPGA.\nIt supports packing/unpacking of most of the bitstream, target device/encryption detection and \npin modification (force the pin high/low).\nIt is supposed to be a dependency of a project, not a boilerplate project to be customized.\nIt was first introduced at Black Hat 2019 ([presentation](https://redballoonsecurity.com/files/CycIhULVL5FS6VNM/100_seconds_of_solitude.pdf), [research paper](https://www.usenix.org/conference/woot19/presentation/kataria)).\n\nThe full api documentation is available [here](https://RedBalloonShenanigans.github.io/bal-xilinx/).\n\n## Contributors:\n\n\n - Jatin Kataria (Researcher)\n - Rick Housley (Researcher)\n - Alex Massonneau (Developer)\n - Andrew O'Brien (Developer)\n\n## Installation\n\nThe BAL Xilinx package can be installed from PyPi with the following command:\n```\npip install bal-xilinx\n```\n\nThe BAL Xilinx package can also be installed from the repository. It requires the BAL package. See the [installation instructions](https://github.com/ballon-rouge/bal).\n\nTo install the BAL Xilinx package from source, run:\n\n```\ngit clone https://github.com/RedBalloonShenanigans/bal-xilinx.git\ncd bal-xilinx\npip install .\n```\n\nTo generate the documentation, run:\n```\npip install .[docs]\nmake html-docs\n```\n\n## Tools\n\nWhile this module is meant to be used as a dependency for another project, it currently offers a \nsingle tool called `pin`. It turns on/off a given pin for an existing Xilinx FPGA bitstream. It is\naccessible by running:\n\n```python\npython -m bal_xilinx.tools.pin \n``` \n\nThe documentation for the pin tool can be accessed by running it with the `-h` flag.\n\n## Methodology\n\nThe Xilinx converters rely heavily on format definitions contained in [bal_xilinx/configs](bal_xilinx/configs). The methodology used to create these JSON files will be published shortly.\n\n## Guide\n\nThis guide assumes familiarity with the [BAL framework](https://github.com/ballon-rouge/bal).\nAs the name of the project implies, this is an implementation of it for Xilinx FPGA bitstreams.\nComplete examples are available under [./example](./example).\n\n### Analyzers\n\nThere are 3 analyzers available:\n\n - `bal_xilinx.analyzers.device_analyzer.XilinxDeviceAnalyzer` Determines the type of device \n targeted by the bitstream.\n - `bal_xilinx.analyzers.encryption_analyzer.XilinxEncryptionAnalyzer` Determines if the FDRI \n packets are encrypted.\n - `bal_xilinx.analyzers.visualizer_analyzer.XilinxVisualizerAnalyzer` Generate the configuration\n data for the [BAL visualizer](https://github.com/ballon-rouge/bal-visualizer/).\n\n### Modifiers\n\nThere is currently a single analyzer:\n\n- `bal_xilinx.modifiers.pin_modifier.XilinxPinModifer` Force a pin to be low/high regardless of \nthe logic executed by the FPGA.\n\n### Examples\n\nHere is an example that puts together all the analyzers and modifiers available.\n\n```python\n# Configure the default converters\nxilinx_context_factory = default_xilinx_context(XilinxContextFactory(\n # Register the formats for the LX9 and LX45T\n default_xilinx_formats(XilinxFormatBuilder()).build()\n))\n\nlx9_bin = wget.download('https://redballoonsecurity.com/files/JwfEU4veQSNFao8h/lx9.bin')\nwith open(lx9_bin, \"rb\") as f:\n data = f.read()\n\nbitstream_context = xilinx_context_factory.create(data)\n\n# Get the device type targeted by the bitstream\ndevice_type = bitstream_context.create_analyzer(XilinxDeviceAnalyzer)\\\n .analyze()\nprint(\"Device info: {}\".format(device_type))\n\n# Determine if the FDRI packets are encrypted.\nis_encrypted = bitstream_context.create_analyzer(XilinxEncryptionAnalyzer)\\\n .analyze()\nprint(\"Is encrypted: {}\".format(is_encrypted))\n\n# Unpack the entire bitstream to make sure the visualization includes everything\nbitstream_context.get_data().unpack_all()\n\nprint(\"Writing the visualizer config to {}\".format(os.path.abspath(\"data.json\")))\nwith open(\"data.json\", \"w\") as f:\n # Generate the visualization config file\n visualizer_config = bitstream_context.create_analyzer(VisualizerAnalyzer) \\\n .analyze()\n json.dump(visualizer_config, f)\n\nprint(\"Pulling the pins low\")\npin_modifier = bitstream_context.create_modifier(XilinxPinModifer)\nfor pin in [\"P134\", \"P133\", \"P132\", \"P131\", \"P127\", \"P126\", \"P124\", \"P123\"]:\n pin_modifier.modify(pin, False)\n\n\nprint(\"Analysis and modifications done!\")\n\n```\n\nThat is it for the guide. Have fun!\n\n\n\n\n", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "", "keywords": "", "license": "", "maintainer": "", "maintainer_email": "", "name": "bal-xilinx", "package_url": "https://pypi.org/project/bal-xilinx/", "platform": "", "project_url": "https://pypi.org/project/bal-xilinx/", "project_urls": null, "release_url": "https://pypi.org/project/bal-xilinx/0.1/", "requires_dist": [ "bal", "six", "typing ; python_version < \"3.5\"" ], "requires_python": "", "summary": "An implementation of the BAL framework for Xilinx FPGAs", "version": "0.1" }, "last_serial": 5652909, "releases": { "0.1": [ { "comment_text": "", "digests": { "md5": "aa7aae5a4d729d64cc320dbe9fbd2467", "sha256": "7542ebb1e4d83ef58cf83f7037914588f52f718c88ad996172dd207470ac8902" }, "downloads": -1, "filename": "bal_xilinx-0.1-py3-none-any.whl", "has_sig": false, "md5_digest": "aa7aae5a4d729d64cc320dbe9fbd2467", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": null, "size": 30459, "upload_time": "2019-08-09T01:06:20", "url": "https://files.pythonhosted.org/packages/f9/2c/ce258d81ec8c6adf1954b64eab2d4a23cf23710a540360d9dfbb67abb87b/bal_xilinx-0.1-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "f4598cbcd3222a056848bf63040d459e", "sha256": "584155a6f5dce218c0b16107e24c48b01b5ac4f1d2e9d9fe341f8a3d7d2880b5" }, "downloads": -1, "filename": "bal-xilinx-0.1.tar.gz", "has_sig": false, "md5_digest": "f4598cbcd3222a056848bf63040d459e", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 24686, "upload_time": "2019-08-09T01:06:22", "url": "https://files.pythonhosted.org/packages/ac/00/e19da93991e98ffba086bec02a8df7c959bbee50932d0ab4320736174a5e/bal-xilinx-0.1.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "aa7aae5a4d729d64cc320dbe9fbd2467", "sha256": "7542ebb1e4d83ef58cf83f7037914588f52f718c88ad996172dd207470ac8902" }, "downloads": -1, "filename": "bal_xilinx-0.1-py3-none-any.whl", "has_sig": false, "md5_digest": "aa7aae5a4d729d64cc320dbe9fbd2467", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": null, "size": 30459, "upload_time": "2019-08-09T01:06:20", "url": "https://files.pythonhosted.org/packages/f9/2c/ce258d81ec8c6adf1954b64eab2d4a23cf23710a540360d9dfbb67abb87b/bal_xilinx-0.1-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "f4598cbcd3222a056848bf63040d459e", "sha256": "584155a6f5dce218c0b16107e24c48b01b5ac4f1d2e9d9fe341f8a3d7d2880b5" }, "downloads": -1, "filename": "bal-xilinx-0.1.tar.gz", "has_sig": false, "md5_digest": "f4598cbcd3222a056848bf63040d459e", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 24686, "upload_time": "2019-08-09T01:06:22", "url": "https://files.pythonhosted.org/packages/ac/00/e19da93991e98ffba086bec02a8df7c959bbee50932d0ab4320736174a5e/bal-xilinx-0.1.tar.gz" } ] }