How g0ldencybersec/gungnir works
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.