AppResolver.hpp

1. Overview

Application identity resolver that maps process command names, executable paths, and argument vectors to human-readable application names and themed icons using desktop application metadata and conservative fallbacks.

File role: Header Interface. The file contains 56 lines and belongs to the util/AppResolver.hpp path.

The companion file is util/AppResolver.cpp.

2. Component Responsibilities

  • Declare the component API, owned state, callbacks, and data structures.
  • Build an index from installed Gio desktop applications
  • Generate normalized lookup aliases from executable names and command lines
  • Match exact aliases and known browser/process variants
  • Reject unreliable or synthetic process identities
  • Return a safe fallback label and icon when no desktop metadata matches
  • Special-case safe local-address connections

3. Dependencies and Integration

System and library dependencies:

  • string
  • vector

4. Declared Types

AppMetadata

Declares a struct.

5. Owned State and UI Members

Data and configuration state

  • std::string display_name;
  • std::string icon_name;

6. Functions and Methods

The file exposes or implements 9 detected function or method signatures.

1. resolve_app_metadata

AppMetadata resolve_app_metadata(const std::string& app_comm, const std::string& app_path, const std::vector<std::string>& app_args = {})

Resolves app metadata into normalized metadata or runtime data.

2. best_app_display_name

std::string best_app_display_name(const std::string& app_comm, const std::string& app_path, const std::vector<std::string>& app_args = {})

Implements the best app display name operation declared by this component.

3. best_app_icon_name

std::string best_app_icon_name(const std::string& app_comm, const std::string& app_path, const std::vector<std::string>& app_args = {})

Implements the best app icon name operation declared by this component.

4. is_safe_local_address

bool is_safe_local_address(const std::string& address)

Returns whether safe local address satisfies the tested condition.

5. is_safe_local_connection

bool is_safe_local_connection(const std::string& dst_ip, const std::string& src_ip = {})

Returns whether safe local connection satisfies the tested condition.

6. safe_local_process_label

std::string safe_local_process_label()

Implements the safe local process label operation declared by this component.

7. safe_local_process_icon_name

std::string safe_local_process_icon_name()

Implements the safe local process icon name operation declared by this component.

8. best_connection_display_name

std::string best_connection_display_name(const std::string& app_comm, const std::string& app_path, const std::vector<std::string>& app_args, const std::string& dst_ip, const std::string& src_ip = {})

Implements the best connection display name operation declared by this component.

9. best_connection_icon_name

std::string best_connection_icon_name(const std::string& app_comm, const std::string& app_path, const std::vector<std::string>& app_args, const std::string& dst_ip, const std::string& src_ip = {})

Implements the best connection icon name operation declared by this component.

7. Runtime Flow

  1. Build an index from installed Gio desktop applications
  2. Generate normalized lookup aliases from executable names and command lines
  3. Match exact aliases and known browser/process variants
  4. Reject unreliable or synthetic process identities
  5. Return a safe fallback label and icon when no desktop metadata matches
  6. Special-case safe local-address connections

8. Runtime and Security Considerations

  • Avoids presenting untrusted process strings as authoritative application identities.
  • Classifies loopback and private local traffic separately.
  • Uses generic icons and labels for unknown identities rather than inventing attribution.
  • Socket lifecycle and framing errors are handled without performing GTK operations directly from the I/O thread.

9. Error Handling and Operational Notes

  • Errors are propagated through the return type, callbacks, or the owning controller.

10. Source Integrity

Relative source path: util/AppResolver.hpp

SHA-256:

be070d584eeee4c7df9f9c798524aabacfef89ce3d0ca7ab6b4f744b8f5fdfe6

11. Licensing

The source header identifies this component as distributed under the GNU General Public License version 3. BastionGuard branding and trademarks remain subject to the notices stated in the source file.

Published on:
Last updated on: