{"id":13529936,"url":"https://github.com/emsec/hal","last_synced_at":"2025-05-15T04:04:24.329Z","repository":{"id":38242725,"uuid":"169076171","full_name":"emsec/hal","owner":"emsec","description":"HAL – The Hardware Analyzer","archived":false,"fork":false,"pushed_at":"2025-05-06T21:38:32.000Z","size":3307869,"stargazers_count":664,"open_issues_count":24,"forks_count":85,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-05-06T21:39:44.569Z","etag":null,"topics":["embedded-security","fpga","hal","hardware","integrated-circuits","netlist","reverse-engineering","security"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emsec.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-02-04T12:37:20.000Z","updated_at":"2025-05-06T20:57:08.000Z","dependencies_parsed_at":"2023-10-21T15:32:39.310Z","dependency_job_id":"76b56c14-ee3c-4ad0-92d6-f462f1f6ffc9","html_url":"https://github.com/emsec/hal","commit_stats":{"total_commits":4253,"total_committers":59,"mean_commits":72.08474576271186,"dds":0.798024923583353,"last_synced_commit":"fb9af43628edc45dfb8003e5a8c2e3ecd8b535ed"},"previous_names":[],"tags_count":66,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emsec%2Fhal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emsec%2Fhal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emsec%2Fhal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emsec%2Fhal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emsec","download_url":"https://codeload.github.com/emsec/hal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254270641,"owners_count":22042858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["embedded-security","fpga","hal","hardware","integrated-circuits","netlist","reverse-engineering","security"],"created_at":"2024-08-01T07:00:41.032Z","updated_at":"2025-05-15T04:04:24.262Z","avatar_url":"https://github.com/emsec.png","language":"C++","readme":"# Welcome to HAL! \n[![Ubuntu 22.04](https://github.com/emsec/hal/actions/workflows/ubuntu22.04.yml/badge.svg)](https://github.com/emsec/hal/actions/workflows/ubuntu22.04.yml)  [![Ubuntu 24.04](https://github.com/emsec/hal/actions/workflows/ubuntu24.04.yml/badge.svg)](https://github.com/emsec/hal/actions/workflows/ubuntu24.04.yml)  [![macOS](https://github.com/emsec/hal/actions/workflows/macOS.yml/badge.svg)](https://github.com/emsec/hal/actions/workflows/macOS.yml) [![Deploy Documentation](https://github.com/emsec/hal/actions/workflows/releaseDoc.yml/badge.svg)](https://github.com/emsec/hal/actions/workflows/releaseDoc.yml) [![Doc: C++](https://img.shields.io/badge/doc-c%2B%2B-orange)](https://emsec.github.io/hal/doc/) [![Doc: Python](https://img.shields.io/badge/doc-python-red)](https://emsec.github.io/hal/pydoc/)\n\n\nHAL \\[/hel/\\] is a comprehensive netlist reverse engineering and manipulation framework.\n\n![HAL Screenshot](https://raw.githubusercontent.com/emsec/hal/master/hal_screenshot.png \"HAL Screenshot\")\n\n\n\n\n# Navigation\n1. [Introduction](#introduction)\n2. [Build Instructions](#build-instructions)\n3. [Quickstart Guide](#quickstart)\n4. [Academic Context](#academic-context)\n\n\u003ca name=\"introduction\"\u003e\u003c/a\u003e\n# Introduction\n\n## What the hell is HAL?\nVirtually all available research on netlist analysis operates on a graph-based representation of the netlist under inspection.\nAt its core, HAL provides exactly that: A framework to parse netlists of arbitrary sources, e.g., FPGAs or ASICs, into a graph-based netlist representation and to provide the necessary built-in tools for traversal and analysis of the included gates and nets.\n\nOur vision is that HAL becomes the hardware-reverse-engineering-equivalent of tools like IDA or Ghidra.\nWe want HAL to enable a common baseline for researchers and analysts to improve reproducibility of research results and abstract away recurring basic tasks such as netlist parsing etc.\n- **High performance** thanks to the optimized C++ core\n- **Flexibility** through built-in Python bindings\n- **Modularity** via a C++ plugin system\n- **Stability** is ensured via a rich test suite\n\nHAL is actively developed by the Embedded Security group of the [Max Planck Institute for Security and Privacy](https://www.mpi-sp.org).\nApart from multiple research projects, it is also used in our university lecture \"Einführung ins Hardware Reverse Engineering\" (Introduction to Hardware Reverse Engineering) at Ruhr University Bochum (RUB).\n\nNote that we also have a set of **modern** state-of-the-art benchmark circuits for the evaluation of netlist reverse engineering techniques available in a seperate [repository](https://github.com/emsec/hal-benchmarks).\n\n## Shipped Plugins\nThis repository contains a selection of curated plugins:\n- **GUI:** A feature-rich GUI allowing for visual netlist inspection and interactive analysis\n  - Native integration of a Python shell with access to the HAL Python bindings\n  - Isolation of specific gates or modules for clutter-free inspection\n  - Interactive traversal of netlists\n  - Detailed widgets with information on all aspects of the inspected netlist\n- **Netlist Simulator:** A simulator for arbitrary parts of a loaded netlist\n- **Dataflow Analysis:** Our dataflow analysis plugin [DANA](https://eprint.iacr.org/2020/751.pdf) that recovers high-level registers in an unstructured netlist\n- **Graph Algorithms:** [igraph](https://igraph.org) integration for direct access to common algorithms from graph-theory\n- **Python Shell:** A command-line plugin to spawn a Python shell preloaded with the HAL Python bindings\n- **VHDL \u0026 Verilog Parsers:** Adds support for parsing VHDL and Verilog files as netlist input formats\n- **Liberty Parser:** Adds support for arbitrary gate libraries in the standard `liberty` gate library format\n- **VHDL \u0026 Verilog Writers:** Adds support for serializing a (modified) netlist to synthesizable VHDL or Verilog files\n- **Gate Libraries:** Adds support for the XILINX Unisim and Simprim gate libraries\n\n\n## Documentation\nA comprehensive documentation of HAL's features from a user perspective is available in our [Wiki](https://github.com/emsec/hal/wiki). In addition, we provide a full [C++ API](https://emsec.github.io/hal/doc/) and [Python API](https://emsec.github.io/hal/pydoc/) documentation.\n\n\u003ca name=\"build-instructions\"\u003e\u003c/a\u003e\n# Build Instructions \n\nFor instructions on how to build HAL, please refer to the dedicated page in our [Wiki](https://github.com/emsec/hal/wiki/Building-HAL).\n\n\u003ca name=\"quickstart\"\u003e\u003c/a\u003e\n# Quickstart Guide \n\nInstall HAL or build HAL and start the GUI via `hal -g`. You can list all available options via `hal [--help|-h]`.\nWe included some example netlists in `examples` together with the implementation of the respective example gate library in `plugins/example_gate_library`.\nFor instructions to create your own gate library and other useful tutorials, take a look at the [wiki](https://github.com/emsec/hal/wiki).\n\nLoad a library from the `examples` directory and start exploring the graphical representation.\nUse the integrated Python shell or the Python script window to interact. Both feature (limited) autocomplete functionality.\n\nLet's list all lookup tables and print their Boolean functions:\n```python\nfor gate in netlist.get_gates():\n    if \"LUT\" in gate.type.name:\n        print(\"{} (id {}, type {})\".format(gate.name, gate.id, gate.type.name))\n        print(\"  {}-to-{} LUT\".format(len(gate.type.input_pins), len(gate.type.output_pins)))\n        boolean_functions = gate.boolean_functions\n        for name in boolean_functions:\n            print(\"  {}: {}\".format(name, boolean_functions[name]))\n        print(\"\")\n```\nFor the example netlist `fsm.vhd` this prints:\n```text\nFSM_sequential_STATE_REG_0_i_3_inst (id 4, type LUT6)\n  6-to-1 LUT\n  O: (!I1 \u0026 !I2 \u0026 I3 \u0026 !I4 \u0026 I5) | (I0 \u0026 !I2) | (I0 \u0026 I1) | (I0 \u0026 I3) | (I0 \u0026 I4) | (I0 \u0026 I5)\n\nFSM_sequential_STATE_REG_0_i_2_inst (id 3, type LUT6)\n  6-to-1 LUT\n  O: (I2 \u0026 I3 \u0026 I4 \u0026 !I5) | (I1 \u0026 !I5) | (I1 \u0026 !I4) | (I1 \u0026 !I3) | (I0 \u0026 I1) | (I1 \u0026 I2)\n\nFSM_sequential_STATE_REG_1_i_3_inst (id 6, type LUT6)\n  6-to-1 LUT\n  O: (!I1 \u0026 I4 \u0026 !I5) | (!I1 \u0026 !I3 \u0026 I4) | (I0 \u0026 I4 \u0026 !I5) | (I0 \u0026 !I3 \u0026 I4) | (!I1 \u0026 I2 \u0026 I4) | (I0 \u0026 I2 \u0026 I4) | (!I2 \u0026 !I5) | (!I2 \u0026 !I4) | (!I2 \u0026 !I3) | (!I0 \u0026 !I4) | (!I0 \u0026 !I2) | (!I0 \u0026 !I1) | (I1 \u0026 !I4) | (I1 \u0026 !I2) | (I0 \u0026 I1) | (I3 \u0026 !I5) | (I3 \u0026 !I4) | (!I0 \u0026 I3) | (I1 \u0026 I3) | (I2 \u0026 I3) | (!I4 \u0026 I5) | (!I3 \u0026 I5) | (!I0 \u0026 I5) | (I1 \u0026 I5) | (I2 \u0026 I5)\n\nFSM_sequential_STATE_REG_1_i_2_inst (id 5, type LUT6)\n  6-to-1 LUT\n  O: (!I0 \u0026 I1 \u0026 !I2 \u0026 I3 \u0026 I4 \u0026 !I5) | (I0 \u0026 !I2 \u0026 I3 \u0026 I4 \u0026 I5)\n\nOUTPUT_BUF_0_inst_i_1_inst (id 18, type LUT1)\n  1-to-1 LUT\n  O: !I0\n\nOUTPUT_BUF_1_inst_i_1_inst (id 20, type LUT2)\n  2-to-1 LUT\n  O: (I0 \u0026 !I1) | (!I0 \u0026 I1)\n```\n\n# Contributing\n\nYou are welcome to contribute to the development of HAL. Feel free to submit a new pull request via github.\nPlease consider running the static checks + `clang format` before that.\nYou can also install these checks as git hooks before any commit.\n\n## Run static checks and clang format locally\nTo install clang-format hook install [git-hooks](https://github.com/icefox/git-hooks) and run:\n\n`git hooks --install`\n\nStart Docker build via:\n`docker-compose run --rm hal-build`\n\n## Generate Changelog\n\n`git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:\"%s\" --no-merges`\n\n\u003ca name=\"academic-context\"\u003e\u003c/a\u003e\n# Academic Context \n\nIf you use HAL in an academic context, please cite the framework using the reference below:\n```latex\n@misc{hal,\n    author = {{Embedded Security Group}},\n    publisher = {{Max Planck Institute for Security and Privacy}},\n    title = {{HAL - The Hardware Analyzer}},\n    year = {2019},\n    howpublished = {\\url{https://github.com/emsec/hal}},\n}\n```\n\nFeel free to also include the original [paper](http://eprint.iacr.org/2017/783). However, we note that HAL has massively changed since its original prototype that was described in the paper.\nHence, we prefer citing the above entry.\n```latex\n@article{2018:Fyrbiak:HAL,\n    author = {Marc Fyrbiak and Sebastian Wallat and Pawel Swierczynski and Max Hoffmann and Sebastian Hoppach and Matthias Wilhelm and Tobias Weidlich and Russell Tessier and Christof Paar},\n    title = {{HAL-} The Missing Piece of the Puzzle for Hardware Reverse Engineering, Trojan Detection and Insertion},\n    journal = {IEEE Transactions on Dependable and Secure Computing},\n    year = {2018},\n    publisher = {IEEE},\n    howpublished = {\\url{https://github.com/emsec/hal}}\n}\n```\n\nTo get an overview on the challenges we set out to solve with HAL, feel free to watch our [talk](https://media.ccc.de/v/36c3-10879-hal_-_the_open-source_hardware_analyzer) at 36C3.\n\n\n# Licensing\nHAL is licensed under MIT License to encourage collaboration with other research groups and contributions from the industry. Please refer to the license file for further information.\n\n# Disclaimer\nHAL is at most alpha-quality software.\nUse at your own risk.\nWe do not encourage any malicious use of our toolkit.\n","funding_links":[],"categories":["C++","Tools","Software Tools"],"sub_categories":["Hardware Tools","Analysis Frameworks"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femsec%2Fhal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femsec%2Fhal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femsec%2Fhal/lists"}