# falconopsllc/goexec architecture

> Architecture diagram of the GitHub repository falconopsllc/goexec, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/falconopsllc/goexec
- Repository: https://github.com/falconopsllc/goexec

## Overview

##### Project Type and Purpose
- GoExec is an open-source, command-line “remote execution multi-tool” written in Go.
- It bundles multiple Windows remote-execution methods (WMI, DCOM, SCMR, TSCH) under a single CLI.
- It’s a library + CLI tool rather than a web or database application.

##### File Structure
- cmd/         ← Cobra-based entrypoint and subcommand definitions (root.go, dcom.go, wmi.go, etc.)
- pkg/goexec/  ← Core library implementing each module: wmi, dcom, scmr, tsch, smb, dce, auth, proxy, io, exec abstractions.
- internal/util/ ← Shared utility code (logging, error handling, JSON output).
- main.go      ← Instantiates the CLI (`goexec` binary).
- Dockerfile, .github/workflows, goreleaser config ← Build, CI/CD, and packaging.

##### README for Additional Insights
- Each subcommand (e.g. `goexec wmi proc`) wires up:
- Authentication (NT-hash, Kerberos, certificates)
- RPC transport (DCERPC over SMB, named pipes, TCP)
- Execution method (WMI Create, DCOM ShellExec, Service Control, Task Scheduler)
- Optional output retrieval via SMB file transfer
- Dependencies: go-msrpc for DCERPC, adauth for Kerberos/LDAP, standard Go libraries.

a. Main Components
- CLI Layer:
– User / Operator
– Cobra command dispatcher (`cmd/`)
- Core Library:
– Execution modules (`pkg/goexec/{wmi,dcom,scmr,tsch}`)
– Networking clients (`pkg/goexec/dce`, `pkg/goexec/smb`, `pkg/goexec/auth`, `pkg/goexec/proxy`)
– I/O and logging (`pkg/goexec/io`, internal/util)
- External Libraries:
– go-msrpc
– adauth
- Build & CI:
– Docker container
– GitHub Actions / goreleaser
- Target Environment:
– Remote Windows Host
– Windows subsystems: WMI service, DCOM objects, Service Control Manager, Task Scheduler
– SMB share for output retrieval

b. Relationships and Data Flows
1. Operator invokes `goexec <module> <method> [flags]`.
2. Cobra CLI parses args → dispatches to the chosen module.
3. Module configures authentication (Kerberos/NTLM/certs).
4. Module selects transport:
- DCE RPC client (`pkg/goexec/dce`)
- SMB client for file transfer (`pkg/goexec/smb`)
5. Module issues RPC calls to the remote host’s Windows service:
- WMI: Win32_Process.Create
- DCOM: ShellExec via MMC20.Application or ShellWindows
- SCMR: CreateService / ChangeServiceConfig
- TSCH: SchRpcRegisterTask, SchRpcRun
6. If `--out` requested: module pipes stdout/stderr to a temp file, then uses SMB client to download.
7. Core util handles logging (plain text / JSON), error formatting.
8. Optional: Docker container wraps the entire binary for packaging and isolation.

c. Architectural Patterns and Principles
- Modular CLI with plug-in style modules (`wmi`, `dcom`, `scmr`, `tsch`).
- Clear separation of concerns:
– CLI parsing (cmd/)
– Core business logic (pkg/goexec/)
– Networking layers (dce, smb, auth, proxy)
– Utility & logging (internal/util)
- Interface abstraction for execution, I/O, authentication to facilitate testing and future modules.
- Dependency injection for transport clients and loggers.

d. Key Technologies and Libraries
- Go (1.23+)
- Cobra (CLI framework)
- go-msrpc (DCERPC)
- adauth (Kerberos / LDAP)
- Docker for containerized builds
- goreleaser + GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        User["Operator / User"]:::external
        Main["main.go"]:::cli
        Cobra["Cobra Command Dispatcher"]:::cli
    end

    %% Core Library Modules
    subgraph "Core Library - Execution Abstractions" 
        direction TB
        ExecAbs["Execution Abstractions"]:::core
    end

    subgraph "Core Library - Modules"
        direction TB
        WMI["WMI Module"]:::core
        DCOM["DCOM Module"]:::core
        SCMR["SCMR Module"]:::core
        TSCH["TSCH Module"]:::core
    end

    %% Networking & Transport
    subgraph "Networking & Transport Clients"
        direction TB
        DCE["DCE RPC Client"]:::network
        SMB["SMB Client"]:::network
    end

    %% Authentication & Proxy
    subgraph "Authentication & Proxy"
        direction TB
        Auth["Auth Module"]:::network
        Proxy["Proxy Module"]:::network
    end

    %% I/O & Utilities
    subgraph "I/O & Util"
        direction TB
        IO["I/O Abstractions"]:::core
        Util["Shared Utilities"]:::util
    end

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        MSRPC["go-msrpc"]:::external
        ADAUTH["adauth"]:::external
    end

    %% Build & CI/CD
    subgraph "Build & CI/CD"
        direction TB
        Docker["Dockerfile"]:::ci
        Goreleaser[".goreleaser.yaml"]:::ci
        Actions["GitHub Actions"]:::ci
    end

    %% Remote Host
    subgraph "Remote Windows Host"
        direction TB
        WMIsvc["WMI Service"]:::remote
        DCOMsvc["DCOM Objects"]:::remote
        SCMRsvc["Service Control Manager"]:::remote
        TSCHsvc["Task Scheduler"]:::remote
        SMBshare["SMB Share"]:::remote
    end

    %% Flows
    User -->|"invoke goexec"| Main
    Main -->|"dispatch"| Cobra
    Cobra -->|"select module"| ExecAbs
    ExecAbs -->|"load module"| WMI
    ExecAbs -->|"load module"| DCOM
    ExecAbs -->|"load module"| SCMR
    ExecAbs -->|"load module"| TSCH

    WMI -->|"authenticate"| Auth
    DCOM -->|"authenticate"| Auth
    SCMR -->|"authenticate"| Auth
    TSCH -->|"authenticate"| Auth

    WMI -->|"use transport"| DCE
    DCOM -->|"use transport"| DCE
    SCMR -->|"use transport"| DCE
    TSCH -->|"use transport"| DCE

    WMI -->|"optional output"| SMB
    DCOM -->|"optional output"| SMB
    SCMR -->|"optional output"| SMB
    TSCH -->|"optional output"| SMB

    Auth -->|"calls into"| MSRPC
    DCE -->|"uses"| MSRPC
    Auth -->|"calls into"| ADAUTH

    SMB -->|"fetch output"| SMBshare
    SMBshare -->|"return file"| IO

    WMI -->|"RPC CreateProcess"| WMIsvc
    DCOM -->|"ShellExec"| DCOMsvc
    SCMR -->|"CreateService"| SCMRsvc
    TSCH -->|"Register & Run Task"| TSCHsvc

    IO -->|"log & format"| Util

    Docker --> Actions
    Actions --> Goreleaser
    Goreleaser --> Docker

    %% Click Events
    click Main "https://github.com/falconopsllc/goexec/blob/main/main.go"
    click Cobra "https://github.com/falconopsllc/goexec/blob/main/cmd/root.go"
    click ExecAbs "https://github.com/falconopsllc/goexec/blob/main/pkg/goexec/client.go"
    click WMI "https://github.com/falconopsllc/goexec/blob/main/pkg/goexec/wmi/wmi.go"
    click DCOM "https://github.com/falconopsllc/goexec/blob/main/pkg/goexec/dcom/dcom.go"
    click SCMR "https://github.com/falconopsllc/goexec/blob/main/pkg/goexec/scmr/scmr.go"
    click TSCH "https://github.com/falconopsllc/goexec/blob/main/pkg/goexec/tsch/tsch.go"
    click DCE "https://github.com/falconopsllc/goexec/blob/main/pkg/goexec/dce/client.go"
    click SMB "https://github.com/falconopsllc/goexec/blob/main/pkg/goexec/smb/client.go"
    click Auth "https://github.com/falconopsllc/goexec/blob/main/pkg/goexec/auth.go"
    click Proxy "https://github.com/falconopsllc/goexec/blob/main/pkg/goexec/proxy.go"
    click IO "https://github.com/falconopsllc/goexec/blob/main/pkg/goexec/io.go"
    click Util "https://github.com/falconopsllc/goexec/blob/main/internal/util/util.go"
    click Docker "https://github.com/falconopsllc/goexec/tree/main/Dockerfile"
    click Goreleaser "https://github.com/falconopsllc/goexec/blob/main/.goreleaser.yaml"
    click Actions "https://github.com/falconopsllc/goexec/blob/main/.github/workflows/go.yml"

    %% Styles
    classDef cli fill:#D0E6FF,stroke:#0366D6;
    classDef core fill:#E6FFEA,stroke:#28A745;
    classDef network fill:#FFF4E5,stroke:#D69D00;
    classDef external fill:#F0E5FF,stroke:#6F42C1;
    classDef util fill:#F2F2F2,stroke:#6A737D;
    classDef ci fill:#FFEFEF,stroke:#D73A49;
    classDef remote fill:#FFEFE5,stroke:#CB2431;
```
