Development

Structure of EMBA

.
├── config/
├── config/scan-profiles/
├── helpers/
├── installer/
├── modules/
├── external
├── Dockerfile
├── check_project.sh
├── docker-compose.yml
├── emba.sh
└── installer.sh

There are some more files, but for understanding the project structure, these aren't necessary.

config/

Configuration files for different modules with file names, regular expressions or paths. These files are very handy, easy to use and they also keep the modules clean.

helpers/

Some scripts with basic functions for EMBA, e.g. colored and uniform output on the terminal or the creation of log files. All modules can access these functions. To understand how to use them, just look at the existing modules.

installer/

All installation modules. This is quite helpful, because our previous installer was over 1000 lines long and nobody couldn't find anything in there.

modules/

All EMBA features are available as separate modules. They are separated in three categories:

P..: Pre-Modules, they are mostly for the firmware extraction.
S..: Main-Modules
L..: System-mode emulation Modules
F..: Final-Modules, they are collecting all the results from the main modules and aggregating them at the end.

scan-profiles/

A selection of EMBA scan profiles. Learn here how to use them.

emba.sh

Main script of EMBA: Usage.

check_project.sh

Script to run ShellCheck over all shell scripts of EMBA.

installer.sh

Install all dependencies of EMBA: Installation.

Dockerfile and docker-compose.yml

EMBA is able to run itself in a Docker container: Docker usage.

---

Development of modules

To make the development of new modules as easy as possible, we have packed a template file into the repository, which contains most function calls for EMBA. This file is provided with comments.

Mandatory content of a module if it had the file name S42_example_module():

S42_example_module() {
  # Initializes module and creates a log file "S42_example_module.txt" in your log folder
  module_log_init "${FUNCNAME [0]}"
  # Prints title to CLI and into log
  module_title "Example module"
  pre_module_reporter "${FUNCNAME[0]}"

  [...]

  # Ends module and saves status into log - $COUNT_FINDINGS has to be replaced by a number of your findings. 
  # If your module didn't found something, then it isn't needed to be generated in the final report
  module_end_log "${FUNCNAME[0]}" "${#COUNT_FINDINGS[@]}"
}

The function that calls module_log_init, module_title, pre_module_reporterand module_end_log are required. To get a better understanding, how the modules are working, just have a look at the existing ones.

Code quality

We use Shellcheck to check the complete EMBA code. You can install Shellcheck from the package sources (under Kali). However, it can happen that not the latest version is used. With the automatic workflow on Github, we always test the code with the latest release of Shellcheck. Therefore you have to manually check the version of your installed Shellcheck and update it if necessary. Simply download the latest release here, unzip it and copy over the original Shellcheck file.

As second code quality gate all new modules/code needs to pass a semgrep check with the community bash modules.

As additional code quality gate all new modules/code needs to fulfill the bash strict mode (see here and here). EMBA can be run in strict mode with the -S option. Before initiating a PR ensure your code is strict mode compatible.

All of these checks are included in the check_project.sh script. In general let this script check your code before commiting to EMBA.