# kung-foo/certgrep architecture

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

- Interactive diagram: https://gitdiagram.com/kung-foo/certgrep
- Repository: https://github.com/kung-foo/certgrep

## Overview

certgrep is a command-line TLS/SSL certificate extractor for live network captures and local PCAP files. Its main workflow opens and filters a capture, assembles TCP streams, identifies TLS handshakes, and uses its bundled TLS client implementation to obtain peer certificates. The reader passes certificates to an asynchronous output component, which writes selected JSON, DER, and/or PEM files and a certificate log. Interface listing is a separate CLI capability. TLS implementation boundaries are summarized from sampled files; packet assembly and some subsystem wiring are inferred only where the excerpts support them.

Main entry points: [`cmd/certgrep/main.go`](https://github.com/kung-foo/certgrep/blob/develop/cmd/certgrep/main.go) (Capture setup), [`reader.go`](https://github.com/kung-foo/certgrep/blob/develop/reader.go) (Stream reader), [`tls_clone/tls.go`](https://github.com/kung-foo/certgrep/blob/develop/tls_clone/tls.go) (TLS client API), [`tls_clone/handshake_client.go`](https://github.com/kung-foo/certgrep/blob/develop/tls_clone/handshake_client.go) (Client handshake)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and capture"]
  node_capture["Capture setup<br/>[main.go]"]
  node_listing["Interface listing<br/>[extractor.go]"]
  node_extractor["Capture loop<br/>[extractor.go]"]
  node_options["Output options<br/>[options.go]"]
end

subgraph group_streams["TCP stream processing"]
  node_assembly["Packet and TCP assembly<br/>[extractor.go]"]
  node_reader["Stream reader<br/>[reader.go]"]
end

subgraph group_tls["TLS extraction"]
  node_tlsclient["TLS client API<br/>[tls.go]"]
  node_tlsconn["TLS record layer<br/>[conn.go]"]
  node_handshake["Client handshake"]
  node_messages["Handshake messages"]
  node_keyagreement["Key agreement<br/>[key_agreement.go]"]
end

subgraph group_results["Certificate output"]
  node_output["Certificate persistence<br/>[output.go]"]
end

node_user(("Operator"))
node_pcap["PCAP file"]
node_iface(("Network interface"))
node_files["Certificate files and log"]

node_user -->|"runs"| node_capture
node_pcap -->|"opens offline"| node_capture
node_iface -->|"opens live"| node_capture
node_capture -->|"lists devices"| node_listing
node_capture -->|"configures and runs"| node_extractor
node_options -->|"configures"| node_extractor
node_extractor -->|"supplies packets"| node_assembly
node_assembly -->|"dispatches streams"| node_reader
node_reader -->|"starts handshake"| node_tlsclient
node_tlsclient -->|"creates connection"| node_tlsconn
node_tlsconn -->|"dispatches handshake"| node_handshake
node_handshake -->|"encodes and parses"| node_messages
node_handshake -->|"negotiates keys"| node_keyagreement
node_tlsclient -->|"returns peer certificates"| node_reader
node_reader -->|"persists certificates"| node_output
node_output -->|"writes formats and log"| node_files

click node_capture "https://github.com/kung-foo/certgrep/blob/develop/cmd/certgrep/main.go"
click node_listing "https://github.com/kung-foo/certgrep/blob/develop/extractor.go"
click node_extractor "https://github.com/kung-foo/certgrep/blob/develop/extractor.go"
click node_options "https://github.com/kung-foo/certgrep/blob/develop/options.go"
click node_assembly "https://github.com/kung-foo/certgrep/blob/develop/extractor.go"
click node_reader "https://github.com/kung-foo/certgrep/blob/develop/reader.go"
click node_tlsclient "https://github.com/kung-foo/certgrep/blob/develop/tls_clone/tls.go"
click node_tlsconn "https://github.com/kung-foo/certgrep/blob/develop/tls_clone/conn.go"
click node_handshake "https://github.com/kung-foo/certgrep/blob/develop/tls_clone/handshake_client.go"
click node_messages "https://github.com/kung-foo/certgrep/blob/develop/tls_clone/handshake_messages.go"
click node_keyagreement "https://github.com/kung-foo/certgrep/blob/develop/tls_clone/key_agreement.go"
click node_output "https://github.com/kung-foo/certgrep/blob/develop/output.go"

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_capture,node_listing,node_extractor,node_options toneBlue
class node_assembly,node_reader toneAmber
class node_tlsclient,node_tlsconn,node_handshake,node_messages,node_keyagreement toneMint
class node_output toneRose
class node_user,node_pcap,node_iface,node_files toneIndigo
```

## Components

### CLI and capture

- [Capture setup](https://github.com/kung-foo/certgrep/blob/develop/cmd/certgrep/main.go): `cmd/certgrep/main.go`
- [Interface listing](https://github.com/kung-foo/certgrep/blob/develop/extractor.go): `extractor.go`
- [Capture loop](https://github.com/kung-foo/certgrep/blob/develop/extractor.go): `extractor.go`
- [Output options](https://github.com/kung-foo/certgrep/blob/develop/options.go): `options.go`

### TCP stream processing

- [Packet and TCP assembly](https://github.com/kung-foo/certgrep/blob/develop/extractor.go): `extractor.go`
- [Stream reader](https://github.com/kung-foo/certgrep/blob/develop/reader.go): `reader.go`

### TLS extraction

- [TLS client API](https://github.com/kung-foo/certgrep/blob/develop/tls_clone/tls.go): `tls_clone/tls.go`
- [TLS record layer](https://github.com/kung-foo/certgrep/blob/develop/tls_clone/conn.go): `tls_clone/conn.go`
- [Client handshake](https://github.com/kung-foo/certgrep/blob/develop/tls_clone/handshake_client.go): `tls_clone/handshake_client.go`
- [Handshake messages](https://github.com/kung-foo/certgrep/blob/develop/tls_clone/handshake_messages.go): `tls_clone/handshake_messages.go`
- [Key agreement](https://github.com/kung-foo/certgrep/blob/develop/tls_clone/key_agreement.go): `tls_clone/key_agreement.go`

### Certificate output

- [Certificate persistence](https://github.com/kung-foo/certgrep/blob/develop/output.go): `output.go`

### Other components

- **Operator**
- **PCAP file**
- **Network interface**
- **Certificate files and log**

## Connections

- Operator → Capture setup: runs
- PCAP file → Capture setup: opens offline
- Network interface → Capture setup: opens live
- Capture setup → Interface listing: lists devices
- Capture setup → Capture loop: configures and runs
- Output options → Capture loop: configures
- Capture loop → Packet and TCP assembly: supplies packets
- Packet and TCP assembly → Stream reader: dispatches streams
- Stream reader → TLS client API: starts handshake
- TLS client API → TLS record layer: creates connection
- TLS record layer → Client handshake: dispatches handshake
- Client handshake → Handshake messages: encodes and parses
- Client handshake → Key agreement: negotiates keys
- TLS client API → Stream reader: returns peer certificates
- Stream reader → Certificate persistence: persists certificates
- Certificate persistence → Certificate files and log: writes formats and log