Skip to content
HAL – The Hardware Analyzer
Branch: master
Clone or download
Latest commit 7f90f59 Jul 15, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.githooks Initial Commit after move to Github Apr 20, 2019
.github Fixed static lint issues Jun 25, 2019
cmake Added codecov support in gitlab ci Jun 18, 2019
deps Move to spdlog 1.3.1 (#80) May 20, 2019
documentation Fixed correct python binding of data container and added documentatio… May 29, 2019
examples Initial Commit after move to Github Apr 20, 2019
include Merge branch 'master' into feature/python-editor-file-modified Jul 14, 2019
installer Fixed conflict with hal-plugins (<= 0.0.22) Jun 28, 2019
plugins Add hint to gate_libraries to README.md Jun 28, 2019
resources recent-files-items now keep track of their files and are removeable. … Jul 4, 2019
src Remember py path for last 'saved as' Jul 15, 2019
test_files New graph views code added to master Jul 2, 2019
tests initial commit for issue #143 Jun 27, 2019
tools adjusted plugin generator for new EXPORT definition Jun 18, 2019
.clang-format Initial Commit after move to Github Apr 20, 2019
.gitignore Cleanup .gitignore and .gitattributes May 8, 2019
.gitlab-ci.yml Update Changelog Jun 21, 2019
.mergify.yml Fixed mergify configuration Jun 19, 2019
Brewfile Fix build instructions for macOS and import of OpenMP May 28, 2019
CMakeLists.txt Fix build instructions for macOS and import of OpenMP May 28, 2019
CURRENT_VERSION Added Changelog for v1.1.0 Jun 27, 2019
Changelog Update Changelog v1.1.4 Jul 15, 2019
Dockerfile Typo in Dockerfile Jun 28, 2019
FindHal.cmake Fix in install buddy header Apr 25, 2019
LICENSE Deploy ppa (#37) Apr 25, 2019
LICENSE.header Deploy ppa (#37) Apr 25, 2019
README.md Typo in README.md Jun 28, 2019
docker-compose.yml Initial Commit after move to Github Apr 20, 2019
hal.pc.in Initial Commit after move to Github Apr 20, 2019
hal_screenshot.png updated readme, fixed gui log not showing multiple spaces, added pyth… May 6, 2019
install_dependencies.sh Fixed static lint issues Jun 25, 2019
requirements.txt Initial Commit after move to Github Apr 20, 2019

README.md

pipeline status coverage report Slack CodeFactor Codacy Badge

Welcome to HAL!

HAL [/hel/] is a comprehensive reverse engineering and manipulation framework for gate-level netlists focusing on efficiency, extendability and portability. HAL comes with a fully-fledged plugin system, allowing to introduce arbitrary functionalities to the core.

HAL Screenshot

Apart from multiple research projects, HAL is also used in our university lecture Introduction to Hardware Reverse Engineering.

Features

  • Natural directed graph representation of netlist elements and their connections
  • Support for custom gate libraries
  • High performance thanks to optimized C++ core
  • Modularity: write your own C++ Plugins for efficient netlist analysis and manipulation (e.g. via graph algorithms)
  • A feature-rich GUI allowing for visual netlist inspection and interactive analysis
  • An integrated Python shell to exploratively interact with netlist elements and to interface plugins from the GUI
  • Update v1.1.0 Support for Xilinx Unisim, Xilinx Simprim, Synopsys 90nm, GSCLIB 3.0 and UMC 0.18µm libraries is now added

API Documentation

The C++ documentation is available here. The Python documentation can be found here.

Quick Start

Install or build HAL and start the GUI via hal -g. You can list all available options via hal [--help|-h]. We included some example netlists in examples together with the implementation of the respective example gate library in plugins/example_gate_library. For instructions to create your own gate library and other useful tutorials, take a look at the wiki.

Load a library from the examples directory and start exploring the graphical representation. Use the integrated Python shell or the Python script window to interact. Both feature (limited) autocomplete functionality.

Let's list all lookup tables and print their Boolean functions:

from hal_plugins import libquine_mccluskey

qm_plugin = libquine_mccluskey.quine_mccluskey()

for gate in netlist.get_gates():
    if "LUT" in gate.type:
        print(gate.name + " (id "+str(gate.id) + ", type " + gate.type + ")")
        print("  " + str(len(gate.input_pin_types)) + "-to-" + str(len(gate.output_pin_types)) + " LUT")
        boolean_functions = qm_plugin.get_boolean_function_str(gate, False)
        for pin in boolean_functions:
            print("  " + pin + ": "+boolean_functions[pin])
        print("")

For the example netlist fsm.vhd this prints:

FSM_sequential_STATE_REG_1_i_2_inst (id 5, type LUT6)
  6-to-1 LUT
  O: (~I0 I1 ~I2 I3 I4 ~I5) + (I0 ~I2 I3 I4 I5)

FSM_sequential_STATE_REG_0_i_2_inst (id 3, type LUT6)
  6-to-1 LUT
  O: (I2 I3 I4 ~I5) + (I1 I2) + (I0 I1) + (I1 ~I3) + (I1 ~I4) + (I1 ~I5)

FSM_sequential_STATE_REG_0_i_3_inst (id 4, type LUT6)
  6-to-1 LUT
  O: (~I1 ~I2 I3 ~I4 I5) + (I0 I5) + (I0 I4) + (I0 I3) + (I0 I1) + (I0 ~I2)

OUTPUT_BUF_0_inst_i_1_inst (id 18, type LUT1)
  1-to-1 LUT
  O: (~I0)

OUTPUT_BUF_1_inst_i_1_inst (id 20, type LUT2)
  2-to-1 LUT
  O: (~I0 I1) + (I0 ~I1)

FSM_sequential_STATE_REG_1_i_3_inst (id 6, type LUT6)
  6-to-1 LUT
  O: (I0 I2 I4) + (~I1 I2 I4) + (I0 ~I3 I4) + (~I1 ~I3 I4) + (I0 I4 ~I5) + (~I1 I4 ~I5) + (I2 I5) + (I2 I3) + (I1 I5) + (I1 I3) + (I0 I1) + (~I0 I5) + (~I0 I3) + (~I0 ~I1) + (I1 ~I2) + (~I0 ~I2) + (~I3 I5) + (~I2 ~I3) + (~I4 I5) + (I3 ~I4) + (I1 ~I4)

Citation

If you use HAL in an academic context, please cite the framework using the reference below:

@misc{hal,
    author = {{EmSec Chair for Embedded Security}},
    publisher = {{Ruhr University Bochum}},
    title = {{HAL - The Hardware Analyzer}},
    year = {2019},
    howpublished = {\url{https://github.com/emsec/hal}},
}

Feel free to also include the original paper

@article{2018:Fyrbiak:HAL,
      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},
  title     	= {{HAL-} The Missing Piece of the Puzzle for Hardware Reverse Engineering,
               	  Trojan Detection and Insertion},
  journal	= {IEEE Transactions on Dependable and Secure Computing},
  year		= {2018},
  publisher	= {IEEE},
  howpublished 	= {\url{https://github.com/emsec/hal}}
}

Contact and Support

Please contact us via our Slack workspace. Get your invite here: Slack

Install Instructions

Ubuntu

HAL releases are available via it's own ppa. You can find it here: ppa:sebastian-wallat/hal

macOS

Use the following commands to install hal via homebrew.

brew tap emsec/hal
brew install hal

Build Instructions

Run the following commands to download and install HAL.

  1. git clone https://github.com/emsec/hal.git && cd hal
  2. To install all neccessary dependencies execute ./install_dependencies.sh
  3. mkdir build && cd build
  4. cmake ..
  5. make

Optionally you can install HAL:

make install

Build on macOS

Please make sure to use a compiler that supports OpenMP. You can install one from e.g. Homebrew via: brew install llvm.

To let cmake know of the custom compiler use following command.

cmake .. -DCMAKE_C_COMPILER=/usr/local/opt/llvm/bin/clang -DCMAKE_CXX_COMPILER=/usr/local/opt/llvm/bin/clang++

Contributing

You are very welcome to contribute to the development of HAL. Feel free to submit a new pull request via github. Please consider running the static checks + clang format before that. You can also install these checks as git hooks before any commit.

Run static checks and clang format locally

To install clang-format hook install git-hooks and run:

git hooks --install

Start Docker build via: docker-compose run --rm hal-build

Generate Changelog

git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"%s" --no-merges

Licensing

HAL 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.

Disclaimer

HAL is at most alpha-quality software. Use at your own risk. We do not encourage any malicious use of our toolkit.

You can’t perform that action at this time.