# edxeth/shai-hulud-open-source architecture

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

- Interactive diagram: https://gitdiagram.com/edxeth/shai-hulud-open-source
- Repository: https://github.com/edxeth/shai-hulud-open-source

## Overview

This is a CI-oriented credential-harvesting, exfiltration, and propagation program, not a general-purpose library. Its documented workflow starts at the runtime entry point, gathers local and cloud/CI data, streams results through a collector, encrypts them for fallback-capable delivery, then uses discovered tokens for package or repository mutations. The README describes additional provider capabilities whose implementation files are absent from the supplied tree; those are represented only where a supported path exists, and uncertain internal links are omitted.

Main entry points: [`src/index.ts`](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/index.ts) (Runtime entry), [`src/sender/github/githubSender.ts`](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/sender/github/githubSender.ts) (GitHub sender), [`src/sender/base.ts`](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/sender/base.ts) (Encrypt results), [`src/dispatcher/dispatcher.ts`](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/dispatcher/dispatcher.ts) (Sender dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_entry["Runtime entry<br/>[index.ts]"]
  node_collector["Result collector<br/>[collector.ts]"]
  node_dispatcher["Sender dispatcher<br/>[dispatcher.ts]"]
end

subgraph group_harvest["Credential harvesting"]
  node_filesystem["Filesystem scan<br/>[filesystem.ts]"]
  node_shell["Shell harvest<br/>[devtool.ts]"]
  node_runner["CI runner scan<br/>[runner.ts]"]
  node_actions["GitHub Actions scan<br/>[actions.ts]"]
  node_aws["AWS secrets<br/>[ssm.ts]"]
  node_kubernetes["Kubernetes secrets<br/>[kubernetes.ts]"]
  node_vault["Vault secrets"]
  node_githubvalidation["GitHub token check<br/>[tokenCheck.ts]"]
end

subgraph group_delivery["Encrypted delivery"]
  node_envelope["Encrypt results<br/>[base.ts]"]
  node_domainfactory["Domain sender"]
  node_githubsender["GitHub sender<br/>[githubSender.ts]"]
end

subgraph group_spread["Propagation"]
  node_npm["npm token mutation<br/>[index.ts]"]
  node_oidc["npm OIDC mutation<br/>[index.ts]"]
  node_branch["Branch mutation<br/>[index.ts]"]
  node_actionsworkflow["Workflow enumeration<br/>[pipeline.ts]"]
end

subgraph group_support["Runtime support"]
  node_daemon["Persistence daemon<br/>[daemon.ts]"]
  node_config["Runtime configuration<br/>[config.ts]"]
end

node_ci(("CI environment"))
node_c2["C2 endpoint"]
node_githubapi["GitHub API"]

node_ci -->|"starts"| node_entry
node_entry -->|"executes"| node_filesystem
node_entry -->|"executes"| node_shell
node_entry -->|"executes"| node_runner
node_entry -->|"checks target"| node_oidc
node_entry -->|"runs providers"| node_aws
node_entry -->|"runs providers"| node_kubernetes
node_entry -->|"runs providers"| node_vault
node_entry -->|"adds on token"| node_actions
node_entry -->|"validates tokens"| node_githubvalidation
node_entry -->|"ingests results"| node_collector
node_entry -->|"configures dispatch"| node_dispatcher
node_collector -->|"dispatches batches"| node_dispatcher
node_dispatcher -->|"creates envelope"| node_envelope
node_envelope -->|"sends through"| node_domainfactory
node_envelope -->|"falls back to"| node_githubsender
node_domainfactory -->|"posts payload"| node_c2
node_githubsender -->|"commits payload"| node_githubapi
node_entry -->|"selects fallback"| node_githubsender
node_entry -->|"runs on token"| node_branch
node_entry -->|"mutates packages"| node_npm
node_oidc -->|"publishes package"| node_npm
node_entry -->|"daemonizes"| node_daemon
node_githubsender -->|"installs monitor"| node_daemon
node_actions -->|"uses pipeline"| node_actionsworkflow
node_actionsworkflow -->|"queries repositories"| node_githubapi
node_branch -.->|"mutates branches"| node_githubapi
node_npm -.->|"checks token"| node_githubapi
node_entry -->|"checks environment"| node_config

click node_entry "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/index.ts"
click node_collector "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/collector/collector.ts"
click node_dispatcher "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/dispatcher/dispatcher.ts"
click node_filesystem "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/providers/filesystem/filesystem.ts"
click node_shell "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/providers/devtool/devtool.ts"
click node_runner "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/providers/ghrunner/runner.ts"
click node_actions "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/providers/actions/actions.ts"
click node_aws "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/providers/aws/ssm.ts"
click node_kubernetes "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/providers/kubernetes/kubernetes.ts"
click node_githubvalidation "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/github_utils/tokenCheck.ts"
click node_envelope "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/sender/base.ts"
click node_domainfactory "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/sender/domain/domainSenderFactory.ts"
click node_githubsender "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/sender/github/githubSender.ts"
click node_npm "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/mutator/npm/index.ts"
click node_oidc "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/mutator/npmoidc/index.ts"
click node_branch "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/mutator/branch/index.ts"
click node_actionsworkflow "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/providers/actions/pipeline.ts"
click node_daemon "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/utils/daemon.ts"
click node_config "https://github.com/edxeth/shai-hulud-open-source/blob/main/src/utils/config.ts"

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_entry,node_collector,node_dispatcher toneBlue
class node_filesystem,node_shell,node_runner,node_actions,node_aws,node_kubernetes,node_vault,node_githubvalidation toneAmber
class node_envelope,node_domainfactory,node_githubsender,node_githubapi toneMint
class node_npm,node_oidc,node_branch,node_actionsworkflow toneRose
class node_daemon,node_config,node_ci,node_c2 toneIndigo
```

## Components

### Runtime orchestration

- [Runtime entry](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/index.ts): `src/index.ts`
- [Result collector](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/collector/collector.ts): `src/collector/collector.ts`
- [Sender dispatcher](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/dispatcher/dispatcher.ts): `src/dispatcher/dispatcher.ts`

### Credential harvesting

- [Filesystem scan](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/providers/filesystem/filesystem.ts): `src/providers/filesystem/filesystem.ts`
- [Shell harvest](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/providers/devtool/devtool.ts): `src/providers/devtool/devtool.ts`
- [CI runner scan](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/providers/ghrunner/runner.ts): `src/providers/ghrunner/runner.ts`
- [GitHub Actions scan](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/providers/actions/actions.ts): `src/providers/actions/actions.ts`
- [AWS secrets](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/providers/aws/ssm.ts): `src/providers/aws/ssm.ts`
- [Kubernetes secrets](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/providers/kubernetes/kubernetes.ts): `src/providers/kubernetes/kubernetes.ts`
- **Vault secrets**
- [GitHub token check](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/github_utils/tokenCheck.ts): `src/github_utils/tokenCheck.ts`

### Encrypted delivery

- [Encrypt results](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/sender/base.ts): `src/sender/base.ts`
- [Domain sender](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/sender/domain/domainSenderFactory.ts): `src/sender/domain/domainSenderFactory.ts`
- [GitHub sender](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/sender/github/githubSender.ts): `src/sender/github/githubSender.ts`

### Propagation

- [npm token mutation](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/mutator/npm/index.ts): `src/mutator/npm/index.ts`
- [npm OIDC mutation](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/mutator/npmoidc/index.ts): `src/mutator/npmoidc/index.ts`
- [Branch mutation](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/mutator/branch/index.ts): `src/mutator/branch/index.ts`
- [Workflow enumeration](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/providers/actions/pipeline.ts): `src/providers/actions/pipeline.ts`

### Runtime support

- [Persistence daemon](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/utils/daemon.ts): `src/utils/daemon.ts`
- [Runtime configuration](https://github.com/edxeth/shai-hulud-open-source/blob/main/src/utils/config.ts): `src/utils/config.ts`

### Other components

- **CI environment**
- **C2 endpoint**
- **GitHub API**

## Connections

- CI environment → Runtime entry: starts (evidence: `README.md`)
- Runtime entry → Filesystem scan: executes (evidence: `src/index.ts`)
- Runtime entry → Shell harvest: executes (evidence: `src/index.ts`)
- Runtime entry → CI runner scan: executes (evidence: `src/index.ts`)
- Runtime entry → npm OIDC mutation: checks target (evidence: `src/index.ts`)
- Runtime entry → AWS secrets: runs providers (evidence: `src/index.ts`)
- Runtime entry → Kubernetes secrets: runs providers (evidence: `src/index.ts`)
- Runtime entry → Vault secrets: runs providers (evidence: `src/index.ts`)
- Runtime entry → GitHub Actions scan: adds on token (evidence: `src/index.ts`)
- Runtime entry → GitHub token check: validates tokens (evidence: `src/index.ts`)
- Runtime entry → Result collector: ingests results (evidence: `src/index.ts`)
- Runtime entry → Sender dispatcher: configures dispatch (evidence: `src/index.ts`)
- Result collector → Sender dispatcher: dispatches batches (evidence: `src/collector/collector.ts`)
- Sender dispatcher → Encrypt results: creates envelope (evidence: `src/dispatcher/dispatcher.ts`)
- Encrypt results → Domain sender: sends through (evidence: `README.md`)
- Encrypt results → GitHub sender: falls back to (evidence: `README.md`)
- Domain sender → C2 endpoint: posts payload (evidence: `README.md`)
- GitHub sender → GitHub API: commits payload (evidence: `src/sender/github/githubSender.ts`)
- Runtime entry → GitHub sender: selects fallback (evidence: `src/index.ts`)
- Runtime entry → Branch mutation: runs on token (evidence: `src/index.ts`)
- Runtime entry → npm token mutation: mutates packages
- npm OIDC mutation → npm token mutation: publishes package (evidence: `src/mutator/npmoidc/index.ts`)
- Runtime entry → Persistence daemon: daemonizes (evidence: `src/index.ts`)
- GitHub sender → Persistence daemon: installs monitor (evidence: `src/sender/github/githubSender.ts`)
- GitHub Actions scan → Workflow enumeration: uses pipeline (evidence: `src/providers/actions/actions.ts`)
- Workflow enumeration → GitHub API: queries repositories (evidence: `src/providers/actions/pipeline.ts`)
- Branch mutation → GitHub API: mutates branches (evidence: `README.md`)
- npm token mutation → GitHub API: checks token (evidence: `src/mutator/npm/index.ts`)
- Runtime entry → Runtime configuration: checks environment (evidence: `src/index.ts`)