Harm0niz3r

KO | EN

gitlite — search

#hacktoberfest #ai #typescript #go #golang #android #macos #nodejs #awesome #cli #kubernetes #awesome-list #mcp #openai

(★ 9)

A Harmony OS Next Analysis Tool

Harm0niz3r Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Harm0niz3r

![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)
![HarmonyOS](https://img.shields.io/badge/HarmonyOS-Next%205.0%2B-lightgrey.svg)
![Status](https://img.shields.io/badge/Status-Active-success.svg)
![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)

A powerful security assessment and application interaction framework for HarmonyOS Next (5.0+).
Harm0niz3r enables researchers to interact with and analyze applications from a controlled rogue app, allowing enumeration of internal components and permissions in a simple and extensible way.

# Quickstart

## Setup

Download or clone this Github repo:

```bash
git clone https://github.com/DEKRA-Cybersecurity/Harm0niz3r/
```

### Client Setup

First step is to install Harm0niz3r client in the target device, it can be done through Huawei DevEco Studio (main HOS development tool, like XCode for *OS) or by installing the `.hap` package with hdc command:

```bash
hdc app install harm0niz3r.hap
```

Once installed, the icon will be visible from app menu in HOS.

### Server Setup

In order to use Harm0niz3r, `hdc` command is required to be instaled in the system (and named after `hdc`, if command is spelled in other way, just change config in `Harm0niz3r.py`). Then run the server:

```bash
python3 Harm0niz3r.py
```

## Connection

Client and server must be connected to have its functionality fully available. To connect, first allow port forwarding for `tcp:51337` from server host:

```bash
hdc fport tcp:51337 tcp:51337
```

Then from Harm0niz3r CLI run the `connect` command (ensure the client is listening, 51337 is the default port and can be seen in the GUI). After that, *MARCO-POLO* handshake will be performed and connection should be stablished.

> If status is failed and connection is not stablished, make sure port forwarding is being applied and re-run both client and server.

# Usage

Both client GUI and server CLI can be useg to perform many operations. With `help` command in CLI all possibilities are shown.

## App List

Touching *Get APp List from PC* in client UI will display a list of all instaled apps, allowing the user to query relevant information for each one.

This same functionality is possible through CLI using the `app_list -a` command.

## Get Exposed Abilities

Exposed abilities may contain any sensitive information, so checking all of them may be interesting. In the client UI is possible to list and invoke each one with the *Get Abilities from PC* option.

To perform the same operation in the CLI is possible with the `app_visible_abilities` command.

# Development

This section is meant to be a development guide for anyone contributing.

## Structure

The project is divided in two main parts: Server and Client.

### Server

The server is written in python3 and provides direct interaction with the device via `hdc`. It provides a CLI, however requires the target device to be connected to PC.

### Client (App)

Apart from the server, a native application is provided. This application must be installed in the target device, allowing to perform operations in a simpler way.

## Connection and Communication

When `connect` command is sent from CLI, TCP socket is opened (by default on port `51337`). If successful, *MARCO-POLO* handshake is performed in order to start the session:

1. Server sends `MARCO \n\n` command to client.
2. If client responds with `POLO`, the connection is stablished.

```ts
// Handshake side in client
if (txt === 'MARCO') {
    await cli.send({ data: 'POLO' });
    this.status = `Console connected on ${this.port}`;
    hilog.info(0x0000, 'AppLog', 'Responded with POLO for MARCO handshake.');
    return;
}
```

Once connected, a thread will continuously read from connection so client can send message requests to server or vice-versa.

### Client to server communication

Usually the client will request server to perform operations or just provide some information. For this purpose client implements `sendToPcClient` method which sends a message string.

The messages have generally the following structure: `COMMAND_REQUEST:<command>`, so the first part is the type of message and the second the data itself, separated by a colon.

The server on its side process those messages in `_receive_loop` method, where are declared those message types and actions associated to them.

```ts
if decoded_data.startswith('COMMAND_REQUEST:'):
    command_payload = decoded_data[len('COMMAND_REQUEST:'):].strip()
    self._print_message("INFO", f"Received command request from app: '{command_payload}'")
    # Parse and execute the command from the app
    self._process_app_command_request(command_payload)
```
> Example statement for the `COMMAND_REQUEST` message type in `_receive_loop` method.

### Server to client communication

Sending data from server to client is a similar process than the previous. The method used by the server is `send_data_to_app` and messages have the same structure as seen. However include '` \n\n`' as ending trail.

The inclusion of and ending trail is necessary as responses from server may be longer. So for the cases where a message is sent over more than one TCP package, the client implements a buffered reception which listens until that ending trail is received.

The method used by client to receive raw packets is `handlePacket` which after receive '` \n\n`' calls `processFullMessage` which actually interprets the message.

## Adding features

## Adding New Commands (New Architecture)

In the refactored Harm0nyz3r architecture, commands are implemented as modular classes
under the `commands/` package and registered through a central registry.

Adding a new command usually involves three steps:

1. Create a new `Command` subclass in `commands/`.
2. Register it in `Harm0nyz3r.py`.
3. (Optional) Add a corresponding handler in the HarmonyOS app, if needed.

---

1. Create a New Command Module

Create a new file, for example:

`commands/example_feature.py`

```python
# commands/example_feature.py
from typing import List

from .base import Command, CommandSource

class ExampleFeatureCommand(Command):
    @property
    def name(self) -> str:
        # CLI name: example_feature
        return "example_feature"

@property
    def supports_logging(self) -> bool:
        """
        If True, the console will support:
          example_feature [args...] --log
        and wrap execution with device logging (hilog) start/stop.
        """
        return False  # Set to True if you want --log support

def help(self) -> str:
        return (
            "example_feature [args]\n"
            "  A new example feature in the Harm0nyz3r console.\n"
        )

def execute(self, console, args: List[str], source: CommandSource) -> None:
        """
        Implement the command logic here.

Parameters:
          console: HarmonyOSClientConsole instance
          args: list of CLI arguments (without the command name or --log)
          source: where the command came from ('cli', 'script', etc.)
        """
        console._print_message("INFO", "Executing example_feature...")

# Example: run an hdc command, talk to the app, etc.
        # stdout, stderr, ret = console._get_hdc_shell_output(["bm", "dump", "-a"])
        # console.send_data_to_app("COMMAND_REQUEST:new_feature")

console._print_message("INFO", "Testing 123... done.")

def register(registry_func):
    """
    Called from Harm0nyz3r.py to register this command
    in the global command registry.
    """
    registry_func(ExampleFeatureCommand())
```

2. Register the command in Harm0nyz3r

```python
    from commands import (
        apps_list,
        app_info,
        app_surface,
        apps_visible_abilities,
        app_udmf,
        apps_udmf,
        app_ability,
        app_ability_fuzz,
        app_ability_fuzz_dict,
        run_script,
        example_feature,  # <--- new command
    )
```
> Example to add new command to server command process method.

3. (Optional) Add a New App-Side Command

If the new feature needs to interact with the HarmonyOS app, you can send a
command from the console to the app:

```python
    console.send_data_to_app("COMMAND_REQUEST:new_feature some arguments")
```

4. Use new feature (button in Client, command in CLI...)

> Depending on the functionality implemented the command will be defined in one function or another, the above process is just a simplified view. For instance, if wanted to perform the same `example_feature` command from CLI (which is recommended) should also be specified in `start_console`.
> Or if the feature returns a value back to be displayed on the app, the callback will define a message type and that message should be properly defined in app.

# Authors

- Jorge Wallace Ruiz
- Pablo Cáceres Gaitán

As part of DEKRA's cybersecurity team.

## License

Harm0niz3r is licensed under the **Apache License, Version 2.0**. See the [LICENSE](LICENSE) file for details.

Harm0niz3r

Harm0niz3r Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Harm0niz3r

Harm0niz3r Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README