# g0ldencybersec/gungnir architecture

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

- Interactive diagram: https://gitdiagram.com/g0ldencybersec/gungnir
- Repository: https://github.com/g0ldencybersec/gungnir

## Overview

##### Project Type and Purpose
- Gungnir is a command‐line tool written in Go that monitors certificate transparency (CT) logs in real time.
- Its purpose is to extract and output domains and subdomains from new SSL/TLS certificates as soon as they’re issued, thereby helping security professionals quickly discover potential attack surfaces.
- The emphasis is on continuous monitoring, filtering (with a provided list of root domains), and real-time output via standard output.

##### File Structure
- cmd Directory: Contains the main application entry point (cmd/gungnir/main.go) which sets up the execution of the tool. This is your CLI interface initiating the service.
- pkg Directory:
- pkg/runner: Likely encapsulates the logic for connecting to CT logs, managing options (see options.go), and starting the monitoring process (in runner.go).
- pkg/types: Contains custom data structures used across the application, for instance to map certificate details or logging data.
- pkg/utils: Provides helper functions that could be handling tasks such as parsing or formatting output.

a. Main Components:
- Command-Line Interface (CLI): Represented by cmd/gungnir/main.go, this is where the execution starts.
- Runner/Monitor Service: This component (pkg/runner) encapsulates the core functionality that connects to multiple CT logs, processes incoming certificates, and extracts the domains.
- Data Structures: The custom types in pkg/types represent the domain models, like certificate details, domain names, or any structured data needed by the runner.
- Utility Functions: Located in pkg/utils, these assist in tasks like logging, formatting, or possibly error handling.
- External CT Logs: A component representing external certificate transparency logs that the tool subscribes to.
- Optional Filtering Component: While not necessarily a separate code module, the README emphasizes customizable filtering using a text file (e.g., roots.txt) which can be depicted as a configuration input affecting the runner’s behavior.

b. Relationships & Interactions:
- The main CLI component initializes and passes command-line options (e.g., filters, debug flags) into the runner.
- The Runner continuously connects to external CT log sources, receives new certificate events, and then delegates to utility functions and type handlers to extract domains.
- Filter configuration (e.g., reading roots.txt) is used by the monitoring logic to determine which certificate entries to process or print.
- The output of the tool (i.e., the discovered domains and subdomains) is printed to stdout, making it available for piping to other tools.

c. Architectural Patterns & Design Principles:
- Modularity: Separation between the CLI, runner logic, type definitions, and utilities is clear and adheres to modular design principles.
- Event-Driven/Reactive: The tool’s continuous monitoring of CT logs reflects an event-driven design where new certificate entries trigger domain extraction.
- Lightweight & Efficient: Emphasize the design goal of minimal overhead, making it easy to run continuously on various platforms.

d. Relevant Technologies & Frameworks:
- Go (Golang): The entire project is built in Go with Go modules (go.mod and go.sum).
- CT Logs API/Streams: Although not explicitly listed in the file structure (it would be in the code within pkg/runner), these external APIs or streams are an integral part of the system’s interaction model.
- Command-Line Interface Libraries: The CLI options for flags suggest usage of Go’s flag package (or similar) to handle input, though this is internal to main.go.

##### Instructing the Principal Software Engineer
- From the CLI to the Runner (passing configuration/options).
- From external CT log sources to the Runner (incoming certificate data).
- From the Runner to the Terminal/output (domain information).
- Optionally, highlight configuration elements (like the roots.txt filter file) as a separate input that affects the runner’s behavior.
- Connections with brief explanations such as “reads configuration,” “processes certificate data,” and “outputs domains” for clarity.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI["CLI (Command-Line Interface)"]:::cli
    Options["Options Handler"]:::runner
    Filter["Filter Config (roots.txt)"]:::config
    CTLogs["External CT Logs"]:::external
    Runner["Runner Service"]:::runner
    Terminal["Terminal Output (stdout)"]:::output
    Internal1["Data Structures"]:::types
    Internal2["Utility Functions"]:::utils

    CLI -->|"initiates"| Options
    Options -->|"passesConfig"| Runner
    Filter -->|"providesFilter"| Runner
    CTLogs -->|"certificateEvents"| Runner
    Runner -->|"outputsDomains"| Terminal
    Runner -->|"usesTypes"| Internal1
    Runner -->|"usesUtils"| Internal2

    click CLI "https://github.com/g0ldencybersec/gungnir/blob/main/cmd/gungnir/main.go"
    click Options "https://github.com/g0ldencybersec/gungnir/blob/main/pkg/runner/options.go"
    click Runner "https://github.com/g0ldencybersec/gungnir/blob/main/pkg/runner/runner.go"
    click Internal1 "https://github.com/g0ldencybersec/gungnir/blob/main/pkg/types/types.go"
    click Internal2 "https://github.com/g0ldencybersec/gungnir/blob/main/pkg/utils/utils.go"

    classDef cli fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef runner fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef types fill:#FFFF99,stroke:#000,stroke-width:1px;
    classDef utils fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef external fill:#FFCCCC,stroke:#000,stroke-width:1px;
    classDef config fill:#D8BFD8,stroke:#000,stroke-width:1px;
    classDef output fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
