# markmental/hss architecture

> Architecture diagram of the GitHub repository markmental/hss, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/markmental/hss
- Repository: https://github.com/markmental/hss

## Overview

hss emulates a socket table by collecting candidate ports, probing a chosen host, and (for local targets) heuristically matching open ports to processes. The main program coordinates these stages and prints ss-style rows. The graph preserves the documented port sources, interface-address display, remote-target limitation, and process controls. Relationships are based on the sampled C source and README; detailed documentation files are present in the tree but were not sampled.

Main entry points: [`hss.c`](https://github.com/markmental/hss/blob/main/hss.c) (Scan coordinator), [`hss-ports.h`](https://github.com/markmental/hss/blob/main/hss-ports.h) (Gather candidates), [`hss-probe.h`](https://github.com/markmental/hss/blob/main/hss-probe.h) (Probe and format), [`hss-proc.h`](https://github.com/markmental/hss/blob/main/hss-proc.h) (Enumerate processes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Scan workflow"]
  node_hss_main["Scan coordinator<br/>[hss.c]"]
  node_output["Socket table output"]
end

subgraph group_ports["Port discovery"]
  node_port_gather["Gather candidates<br/>[hss-ports.h]"]
  node_port_insert["Sorted deduplication<br/>[hss-ports.h]"]
  node_modern_ports["Built-in ports<br/>[hss-ports.h]"]
end

subgraph group_probe["Network probing"]
  node_probe_port["Probe and format<br/>[hss-probe.h]"]
  node_try_connect["Nonblocking connect<br/>[hss-probe.h]"]
  node_interfaces["Interface addresses<br/>[hss-probe.h]"]
end

subgraph group_process["Process lookup"]
  node_find_pids["Enumerate processes<br/>[hss-proc.h]"]
  node_match_process["Heuristic matching<br/>[hss-proc.h]"]
  node_process_args["Process arguments<br/>[hss-proc.h]"]
end

node_user(("User"))
node_target(("Target host"))
node_services_file["System services"]
node_config_file["User port config"]
node_network(("TCP network"))
node_proc_server["Hurd proc server"]

node_user -->|"runs with options"| node_hss_main
node_user -.->|"configures ports"| node_config_file
node_hss_main -->|"parses services"| node_port_gather
node_services_file -->|"provides entries"| node_port_gather
node_port_gather -->|"adds candidates"| node_port_insert
node_hss_main -->|"adds built-ins"| node_modern_ports
node_hss_main -->|"adds built-ins"| node_port_insert
node_hss_main -->|"parses config"| node_port_gather
node_config_file -->|"provides ports"| node_port_gather
node_port_gather -->|"adds config ports"| node_port_insert
node_hss_main -->|"enumerates addresses"| node_interfaces
node_interfaces -->|"queries interfaces"| node_network
node_hss_main -->|"selects host"| node_target
node_hss_main -->|"probes each port"| node_probe_port
node_probe_port -->|"tests connection"| node_try_connect
node_try_connect -->|"connects to host"| node_network
node_probe_port -->|"checks local addresses"| node_interfaces
node_hss_main -->|"gets local server"| node_proc_server
node_hss_main -->|"looks up owners"| node_find_pids
node_find_pids -->|"enumerates PIDs and args"| node_proc_server
node_find_pids -->|"tests command lines"| node_match_process
node_proc_server -->|"returns process args"| node_process_args
node_match_process -->|"matches port heuristics"| node_process_args
node_hss_main -->|"prints scan rows"| node_output

click node_hss_main "https://github.com/markmental/hss/blob/main/hss.c"
click node_port_gather "https://github.com/markmental/hss/blob/main/hss-ports.h"
click node_port_insert "https://github.com/markmental/hss/blob/main/hss-ports.h"
click node_modern_ports "https://github.com/markmental/hss/blob/main/hss-ports.h"
click node_probe_port "https://github.com/markmental/hss/blob/main/hss-probe.h"
click node_try_connect "https://github.com/markmental/hss/blob/main/hss-probe.h"
click node_interfaces "https://github.com/markmental/hss/blob/main/hss-probe.h"
click node_find_pids "https://github.com/markmental/hss/blob/main/hss-proc.h"
click node_match_process "https://github.com/markmental/hss/blob/main/hss-proc.h"
click node_process_args "https://github.com/markmental/hss/blob/main/hss-proc.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hss_main,node_output,node_user,node_config_file toneBlue
class node_port_gather,node_port_insert,node_modern_ports toneAmber
class node_probe_port,node_try_connect,node_interfaces,node_proc_server toneMint
class node_find_pids,node_match_process,node_process_args toneRose
class node_target,node_services_file,node_network toneIndigo
```

## Components

### Scan workflow

- [Scan coordinator](https://github.com/markmental/hss/blob/main/hss.c): `hss.c`
- **Socket table output**

### Port discovery

- [Gather candidates](https://github.com/markmental/hss/blob/main/hss-ports.h): `hss-ports.h`
- [Sorted deduplication](https://github.com/markmental/hss/blob/main/hss-ports.h): `hss-ports.h`
- [Built-in ports](https://github.com/markmental/hss/blob/main/hss-ports.h): `hss-ports.h`

### Network probing

- [Probe and format](https://github.com/markmental/hss/blob/main/hss-probe.h): `hss-probe.h`
- [Nonblocking connect](https://github.com/markmental/hss/blob/main/hss-probe.h): `hss-probe.h`
- [Interface addresses](https://github.com/markmental/hss/blob/main/hss-probe.h): `hss-probe.h`

### Process lookup

- [Enumerate processes](https://github.com/markmental/hss/blob/main/hss-proc.h): `hss-proc.h`
- [Heuristic matching](https://github.com/markmental/hss/blob/main/hss-proc.h): `hss-proc.h`
- [Process arguments](https://github.com/markmental/hss/blob/main/hss-proc.h): `hss-proc.h`

### Other components

- **User**
- **Target host**
- **System services**
- **User port config**
- **TCP network**
- **Hurd proc server**

## Connections

- User → Scan coordinator: runs with options
- User → User port config: configures ports
- Scan coordinator → Gather candidates: parses services
- System services → Gather candidates: provides entries
- Gather candidates → Sorted deduplication: adds candidates
- Scan coordinator → Built-in ports: adds built-ins
- Scan coordinator → Sorted deduplication: adds built-ins
- Scan coordinator → Gather candidates: parses config
- User port config → Gather candidates: provides ports
- Gather candidates → Sorted deduplication: adds config ports
- Scan coordinator → Interface addresses: enumerates addresses
- Interface addresses → TCP network: queries interfaces
- Scan coordinator → Target host: selects host
- Scan coordinator → Probe and format: probes each port
- Probe and format → Nonblocking connect: tests connection
- Nonblocking connect → TCP network: connects to host
- Probe and format → Interface addresses: checks local addresses
- Scan coordinator → Hurd proc server: gets local server
- Scan coordinator → Enumerate processes: looks up owners
- Enumerate processes → Hurd proc server: enumerates PIDs and args
- Enumerate processes → Heuristic matching: tests command lines
- Hurd proc server → Process arguments: returns process args
- Heuristic matching → Process arguments: matches port heuristics
- Scan coordinator → Socket table output: prints scan rows