# aditiya-saputra/brantas-judol architecture

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

- Interactive diagram: https://gitdiagram.com/aditiya-saputra/brantas-judol
- Repository: https://github.com/aditiya-saputra/brantas-judol

## Overview

Brantas-Judol discovers candidate domains from Certificate Transparency logs, enriches candidates with urlscan evidence, and experimentally scores them with Gemini. Its output is explicitly candidate signals, not a human-reviewed blocklist. The CT parsing and cursor details are in one script; the graph separates their domain stages without implying separate modules. Probe scan submission is an optional path. Some relationships and capabilities are documented in the README; unsampled implementation details are not inferred.

Main entry points: [`classify.py`](https://github.com/aditiya-saputra/brantas-judol/blob/main/classify.py) (Candidate classifier), [`probe.py`](https://github.com/aditiya-saputra/brantas-judol/blob/main/probe.py) (Evidence probe), [`grab.py`](https://github.com/aditiya-saputra/brantas-judol/blob/main/grab.py) (CT grabber), [`urlscan-evidence.json`](https://github.com/aditiya-saputra/brantas-judol/blob/main/urlscan-evidence.json) (Evidence ledger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["CT discovery"]
  node_ctgrab["CT grabber<br/>[grab.py]"]
  node_ctfetch["Log fetch<br/>[grab.py]"]
  node_tlsx509["TLS and X.509 parsing<br/>[grab.py]"]
  node_normalize["Domain normalization<br/>[grab.py]"]
  node_keywordfilter["Keyword filter<br/>[grab.py]"]
end

subgraph group_evidence["Evidence probing"]
  node_probe["Evidence probe<br/>[probe.py]"]
  node_scan["Scan submission<br/>[probe.py]"]
end

subgraph group_classification["LLM classification"]
  node_classify["Candidate classifier<br/>[classify.py]"]
  node_buckets["Score buckets"]
end

subgraph group_state["Persistent state"]
  node_candidates["Candidate domains"]
  node_cursors[("CT cursors<br/>[ct.db]")]
  node_evidenceledger["Evidence ledger"]
end

node_operator(("Operator"))
node_registries[("CT registries")]
node_urlscan[("urlscan.io")]
node_gemini{{"Gemini API"}}
node_google{{"Google Search grounding"}}

node_operator -->|"runs scan"| node_ctgrab
node_registries -->|"provides log list"| node_ctgrab
node_ctgrab -->|"dispatches fetch"| node_ctfetch
node_ctfetch -->|"fetches entries"| node_registries
node_ctfetch -->|"parses entries"| node_tlsx509
node_tlsx509 -->|"extracts domains"| node_normalize
node_normalize -->|"filters domains"| node_keywordfilter
node_keywordfilter -->|"appends candidates"| node_candidates
node_ctgrab -->|"reads and updates"| node_cursors
node_operator -->|"runs probe"| node_probe
node_probe -->|"reads candidates"| node_candidates
node_probe -->|"searches scans"| node_urlscan
node_probe -->|"optionally submits"| node_scan
node_scan -->|"submits scan"| node_urlscan
node_probe -->|"writes evidence"| node_evidenceledger
node_operator -->|"runs classifier"| node_classify
node_classify -->|"loads candidates"| node_candidates
node_classify -->|"loads evidence"| node_evidenceledger
node_classify -->|"requests scores"| node_gemini
node_classify -.->|"optionally grounds"| node_google
node_classify -->|"writes score buckets"| node_buckets

click node_ctgrab "https://github.com/aditiya-saputra/brantas-judol/blob/main/grab.py"
click node_ctfetch "https://github.com/aditiya-saputra/brantas-judol/blob/main/grab.py"
click node_tlsx509 "https://github.com/aditiya-saputra/brantas-judol/blob/main/grab.py"
click node_normalize "https://github.com/aditiya-saputra/brantas-judol/blob/main/grab.py"
click node_keywordfilter "https://github.com/aditiya-saputra/brantas-judol/blob/main/grab.py"
click node_cursors "https://github.com/aditiya-saputra/brantas-judol/blob/main/ct.db"
click node_probe "https://github.com/aditiya-saputra/brantas-judol/blob/main/probe.py"
click node_evidenceledger "https://github.com/aditiya-saputra/brantas-judol/blob/main/urlscan-evidence.json"
click node_scan "https://github.com/aditiya-saputra/brantas-judol/blob/main/probe.py"
click node_classify "https://github.com/aditiya-saputra/brantas-judol/blob/main/classify.py"

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_ctgrab,node_ctfetch,node_tlsx509,node_normalize,node_keywordfilter toneBlue
class node_probe,node_scan,node_registries,node_urlscan toneAmber
class node_classify,node_buckets,node_gemini toneMint
class node_candidates,node_cursors,node_evidenceledger toneRose
class node_operator,node_google toneIndigo
```

## Components

### CT discovery

- [CT grabber](https://github.com/aditiya-saputra/brantas-judol/blob/main/grab.py): `grab.py`
- [Log fetch](https://github.com/aditiya-saputra/brantas-judol/blob/main/grab.py): `grab.py`
- [TLS and X.509 parsing](https://github.com/aditiya-saputra/brantas-judol/blob/main/grab.py): `grab.py`
- [Domain normalization](https://github.com/aditiya-saputra/brantas-judol/blob/main/grab.py): `grab.py`
- [Keyword filter](https://github.com/aditiya-saputra/brantas-judol/blob/main/grab.py): `grab.py`

### Evidence probing

- [Evidence probe](https://github.com/aditiya-saputra/brantas-judol/blob/main/probe.py): `probe.py`
- [Scan submission](https://github.com/aditiya-saputra/brantas-judol/blob/main/probe.py): `probe.py`

### LLM classification

- [Candidate classifier](https://github.com/aditiya-saputra/brantas-judol/blob/main/classify.py): `classify.py`
- **Score buckets**

### Persistent state

- **Candidate domains**
- [CT cursors](https://github.com/aditiya-saputra/brantas-judol/blob/main/ct.db): `ct.db`
- [Evidence ledger](https://github.com/aditiya-saputra/brantas-judol/blob/main/urlscan-evidence.json): `urlscan-evidence.json`

### Other components

- **Operator**
- **CT registries**
- **urlscan.io**
- **Gemini API**
- **Google Search grounding**

## Connections

- Operator → CT grabber: runs scan (evidence: `README.md`)
- CT registries → CT grabber: provides log list (evidence: `README.md`)
- CT grabber → Log fetch: dispatches fetch (evidence: `grab.py`)
- Log fetch → CT registries: fetches entries (evidence: `README.md`)
- Log fetch → TLS and X.509 parsing: parses entries (evidence: `README.md`)
- TLS and X.509 parsing → Domain normalization: extracts domains (evidence: `README.md`)
- Domain normalization → Keyword filter: filters domains (evidence: `README.md`)
- Keyword filter → Candidate domains: appends candidates (evidence: `README.md`)
- CT grabber → CT cursors: reads and updates (evidence: `README.md`)
- Operator → Evidence probe: runs probe (evidence: `README.md`)
- Evidence probe → Candidate domains: reads candidates (evidence: `probe.py`)
- Evidence probe → urlscan.io: searches scans (evidence: `probe.py`)
- Evidence probe → Scan submission: optionally submits (evidence: `probe.py`)
- Scan submission → urlscan.io: submits scan (evidence: `probe.py`)
- Evidence probe → Evidence ledger: writes evidence (evidence: `README.md`)
- Operator → Candidate classifier: runs classifier (evidence: `README.md`)
- Candidate classifier → Candidate domains: loads candidates (evidence: `classify.py`)
- Candidate classifier → Evidence ledger: loads evidence (evidence: `README.md`)
- Candidate classifier → Gemini API: requests scores (evidence: `classify.py`)
- Candidate classifier → Google Search grounding: optionally grounds (evidence: `README.md`)
- Candidate classifier → Score buckets: writes score buckets (evidence: `README.md`)
