feat: add Tor exit node and DNSBL (spamlist) resolvers

Author: stuchl4n3k

.cursor/rules/read-before-write.mdc

@@ -0,0 +1,25 @@
+---
+description: LLM must verify file state before writing to avoid overwriting changes
+alwaysApply: true
+---
+
+# Read Before Write
+
+**You MUST check whether a file has been modified before writing to it.**
+
+## Rule
+
+1. **Before any write or search_replace** on an existing file, **read the file** from disk (using the Read tool) to get the current contents.
+2. Do not rely on earlier context, open buffers, or previous tool output for the file’s current state—it may have changed.
+3. Use the freshly read content to construct accurate edits (e.g. correct field names, indentation, and structure).
+
+## Why
+
+- Files can be changed by the user or other tools between your reads and writes.
+- Using stale or assumed content leads to wrong renames, duplicate blocks, or reverted changes.
+- Reading immediately before editing ensures edits match the actual file on disk.
+
+## Applies To
+
+- All edits (StrReplace, Write over existing files).
+- Especially when changing names, types, or structure that might have been updated elsewhere.

DEVELOPMENT.md

@@ -1,5 +1,7 @@
 # Development
 
+## Using udig as a library
+
 ### Basic usage
 
 Import the package:
@@ -10,7 +12,7 @@ go get github.com/netrixone/udig
 
 ```go
 dig := udig.NewUdig()
-for res := range dig.Resolve("example.com") {
+for res := range dig.Resolve(context.Background(), "example.com") {
     fmt.Println(res.Type(), res.Query())
 }
 ```
@@ -31,42 +33,62 @@ dig := udig.NewUdig(
 )
 ```
 
-
-| Option               | Effect                                                    |
-| -------------------- | --------------------------------------------------------- |
-| `WithDebugLogging()` | Enable verbose debug output                               |
-| `WithStrictMode()`   | Only follow domains that share the same TLD               |
-| `WithTimeout(d)`     | Set connection timeout for all resolvers                  |
-| `WithCTSince(t)`     | Only collect CT logs issued after this date               |
-| `WithCTExpired()`    | Include expired CT log entries                             |
+| Option               | Effect                                                          |
+| -------------------- | --------------------------------------------------------------- |
+| `WithDebugLogging()` | Enable verbose debug output                                     |
+| `WithStrictMode()`   | Only follow domains that share the same TLD                     |
+| `WithTimeout(d)`     | Set connection timeout for all resolvers                        |
+| `WithCTSince(t)`     | Only collect CT logs issued after this date                     |
+| `WithCTExpired()`    | Include expired CT log entries                                  |
 | `WithMaxDepth(n)`    | Limit recursive discovery to n hops from seed (-1 = unlimited) |
 
-
 ### Working with resolutions
 
-Each resolver produces a typed resolution. Use a type switch to handle them:
+Each resolver produces typed resolutions. Every resolution carries exactly one result (one type, one query, one record). Use a type switch to handle them:
 
 ```go
-for res := range dig.Resolve("example.com") {
+for res := range dig.Resolve(context.Background(), "example.com") {
     switch res.Type() {
     case udig.TypeDNS:
-        for _, rr := range res.(*udig.DNSResolution).Records {
-            fmt.Printf("DNS %s %s -> %s\n", dns.TypeToString[rr.QueryType], res.Query(), rr.Record)
-        }
+        record := res.(*udig.DNSResolution).Record
+        fmt.Printf("DNS %s %s -> %s\n", dns.TypeToString[record.QueryType], res.Query(), record)
+
     case udig.TypeTLS:
-        for _, cert := range res.(*udig.TLSResolution).Certificates {
-            fmt.Printf("TLS %s -> %s\n", res.Query(), cert.Subject.CommonName)
-        }
+        record := &res.(*udig.TLSResolution).Record
+        fmt.Printf("TLS %s -> %s\n", res.Query(), record.Subject.CommonName)
+
     case udig.TypeBGP:
-        for _, as := range res.(*udig.BGPResolution).Records {
-            fmt.Printf("BGP %s -> AS%d %s\n", res.Query(), as.Number, as.Name)
-        }
-    // ... TypeWHOIS, TypeHTTP, TypeCT, TypeGEO
+        record := &res.(*udig.BGPResolution).Record
+        fmt.Printf("BGP %s -> AS%d %s\n", res.Query(), record.ASN, record.Name)
+
+    case udig.TypeGEO:
+        record := res.(*udig.GeoResolution).Record
+        fmt.Printf("GEO %s -> %s\n", res.Query(), record.CountryCode)
+
+    case udig.TypePTR:
+        record := res.(*udig.PTRResolution).Record
+        fmt.Printf("PTR %s -> %s\n", res.Query(), record.Hostname)
+
+    case udig.TypeRDAP:
+        record := &res.(*udig.RDAPResolution).Record
+        fmt.Printf("RDAP %s -> %s (%s)\n", res.Query(), record.Name, record.Handle)
+
+    case udig.TypeDNSBL:
+        // Emitted only when the IP is listed; record.Zone + record.Meaning describe the listing.
+        record := &res.(*udig.DNSBLResolution).Record
+        fmt.Printf("DNSBL %s -> %s\n", res.Query(), record)
+
+    case udig.TypeTor:
+        // Emitted when the IP is any known Tor relay (exit, guard, middle, …).
+        record := res.(*udig.TorResolution).Record
+        fmt.Printf("TOR %s -> %s (exit=%v)\n", res.Query(), record.Nickname, record.IsExitNode())
+
+    // ... TypeWHOIS, TypeHTTP, TypeCT, TypeDMARC
     }
 }
 ```
 
-Resolution types: `TypeDNS`, `TypeTLS`, `TypeWHOIS`, `TypeHTTP`, `TypeCT`, `TypeBGP`, `TypeGEO`.
+Resolution types: `TypeDNS`, `TypeDMARC`, `TypeTLS`, `TypeWHOIS`, `TypeHTTP`, `TypeCT`, `TypePTR`, `TypeBGP`, `TypeGEO`, `TypeRDAP`, `TypeDNSBL`, `TypeTor`.
 
 ## Architecture
 
@@ -79,67 +101,61 @@ flowchart TB
   subgraph domain["Domain resolvers"]
     DR[DomainResolver]
     DNS[DNSResolver]
+    DMARC[DMARCResolver]
     TLS[TLSResolver]
     HTTP[HTTPResolver]
     WHOIS[WhoisResolver]
     CT[CTResolver]
   end
 
-  subgraph domain_out["Domain resolution types"]
-    DNSRecord[DNSRecord]
-    TLSCert[TLSCertificate]
-    Header[HTTPHeader]
-    Contact[WhoisContact]
-    CTLog[CTLog]
-  end
-
   subgraph ip["IP resolvers"]
     IR[IPResolver]
+    PTR[PTRResolver]
     BGP[BGPResolver]
     Geo[GeoResolver]
+    RDAP[RDAPResolver]
+    DNSBL[DNSBLResolver]
+    Tor[TorResolver]
   end
 
-  subgraph ip_out["IP resolution types"]
-    ASRecord[ASRecord]
-    GeoRecord[GeoipRecord]
-  end
-
-  Udig --> DR
-  Udig --> IR
-  DR --> DNS & TLS & HTTP & WHOIS & CT
-  DNS --> DNSRecord
-  TLS --> TLSCert
-  HTTP --> Header
-  WHOIS --> Contact
-  CT --> CTLog
-  IR --> BGP & Geo
-  BGP --> ASRecord
-  Geo --> GeoRecord
+  Udig --> DR & IR
+  DR --> DNS & DMARC & TLS & HTTP & WHOIS & CT
+  IR --> PTR & BGP & Geo & RDAP & DNSBL & Tor
 ```
 
-
-
 ### Resolution flow
 
 1. A domain enters the processing queue.
 2. All `DomainResolver` instances run **concurrently** (goroutines + `sync.WaitGroup`).
 3. Discovered IPs are enqueued for `IPResolver` processing.
 4. Discovered domains are checked for relatedness and recursively enqueued.
-5. Deduplication ensures each domain and IP is only resolved once.
+5. Deduplication ensures each domain and IP is resolved only once.
 
 ### Resolver overview
 
-
-| File       | Resolver        | Resolves                                     | Data source              |
-| ---------- | --------------- | -------------------------------------------- | ------------------------ |
-| `dns.go`   | `DNSResolver`   | DNS records (A, AAAA, NS, MX, TXT, SOA, ...) | Local/custom nameservers |
-| `tls.go`   | `TLSResolver`   | TLS certificate chains                       | Direct TLS handshake     |
-| `whois.go` | `WhoisResolver` | WHOIS contacts                               | WHOIS protocol           |
-| `http.go`  | `HTTPResolver`  | Security HTTP headers (CSP, CORS, Alt-Svc)   | HTTP/HTTPS requests      |
-| `ct.go`    | `CTResolver`    | Certificate Transparency logs                | crt.sh JSON API          |
-| `bgp.go`   | `BGPResolver`   | BGP AS records                               | Team Cymru DNS           |
-| `geo.go`   | `GeoResolver`   | GeoIP country codes                          | IP2Location LITE DB      |
-
+| Resolver file         | Resolver          | Resolves                                      | Data source                      |
+| --------------------- | ----------------- | --------------------------------------------- | -------------------------------- |
+| `dns_resolver.go`     | `DNSResolver`     | DNS records (A, AAAA, NS, MX, TXT, SOA, ...)  | Local/custom nameservers         |
+| `dmarc_resolver.go`   | `DMARCResolver`   | DMARC policy and reporting addresses          | DNS TXT `_dmarc.{domain}`        |
+| `tls_resolver.go`     | `TLSResolver`     | TLS certificate chains                        | Direct TLS handshake             |
+| `whois_resolver.go`   | `WhoisResolver`   | WHOIS contacts                                | WHOIS protocol                   |
+| `http_resolver.go`    | `HTTPResolver`    | Security HTTP headers, security.txt, robots   | HTTP/HTTPS requests              |
+| `ct_resolver.go`      | `CTResolver`      | Certificate Transparency logs                 | crt.sh JSON API                  |
+| `ptr_resolver.go`     | `PTRResolver`     | Reverse DNS hostnames                         | DNS PTR records                  |
+| `bgp_resolver.go`     | `BGPResolver`     | BGP AS records                                | Team Cymru DNS                   |
+| `geo_resolver.go`     | `GeoResolver`     | GeoIP country codes                           | IP2Location LITE DB              |
+| `rdap_resolver.go`    | `RDAPResolver`    | IP registration metadata                      | RIR RDAP via IANA bootstrap      |
+| `dnsbl_resolver.go`   | `DNSBLResolver`   | DNS blocklist checks (listed zones + meaning) | Barracuda, UCEProtect, DroneBL   |
+| `tor_resolver.go`     | `TorResolver`     | Tor node detection (exit/guard/relay)         | Tor Onionoo HTTPS API            |
+
+### Adding a new resolver
+
+1. Create `{name}.go` — define `{Name}Resolution` embedding `*ResolutionBase` with a single `Record {Name}Record` field, and `{Name}Record` with a `String()` method.
+2. Create `{name}_resolver.go` — implement `ResolveIP(ip string) []Resolution` or `ResolveDomain(domain string) []Resolution`, plus `Type() ResolutionType`.
+3. Add a `Type{Name}` constant to `api.go`.
+4. Register it in `NewUdig()` in `udig.go`.
+5. Handle the new type in the `switch` in `cmd/udig/main.go` and `cmd/udig/graph/graph.go`.
+6. Add tests in `{name}_test.go`.
 
 ## Building
 
@@ -152,23 +168,21 @@ flowchart TB
 
 ### Make targets
 
-
-| Target          | Description                                           |
-| --------------- | ----------------------------------------------------- |
-| `make`          | Build and run tests (default)                         |
-| `make build`    | Compile binary                                        |
-| `make test`     | Run tests                                             |
-| `make test-race`| Run tests with race detector                          |
-| `make install`  | Run tests, install binary, copy GeoIP DB if present   |
-| `make release`  | Stripped + UPX release binary                         |
-| `make clean`    | Remove binaries, GeoIP DB, test cache                  |
-| `make fmt`      | Format code                                           |
-| `make vet`      | Run `go vet`                                          |
-| `make lint`     | Run golangci-lint                                     |
-| `make mod-tidy` | Tidy go.mod / go.sum                                  |
-| `make geoip`    | Download GeoIP database if missing                    |
-| `make help`     | List targets                                          |
-
+| Target           | Description                                           |
+| ---------------- | ----------------------------------------------------- |
+| `make`           | Build and run tests (default)                         |
+| `make build`     | Compile binary                                        |
+| `make test`      | Run tests                                             |
+| `make test-race` | Run tests with race detector                          |
+| `make install`   | Run tests, install binary, copy GeoIP DB if present   |
+| `make release`   | Stripped + UPX release binary                         |
+| `make clean`     | Remove binaries, GeoIP DB, test cache                 |
+| `make fmt`       | Format code                                           |
+| `make vet`       | Run `go vet`                                          |
+| `make lint`      | Run golangci-lint                                     |
+| `make mod-tidy`  | Tidy go.mod / go.sum                                  |
+| `make geoip`     | Download GeoIP database if missing                    |
+| `make help`      | List targets                                          |
 
 ### Running tests
 
@@ -180,13 +194,11 @@ go test -v ./...
 
 ## Key files
 
-
-| File               | Purpose                                                   |
-| ------------------ | --------------------------------------------------------- |
-| `api.go`           | Interfaces, types, resolution structs, functional options |
-| `udig.go`          | Facade implementation, queue processing, domain crawling  |
-| `utils.go`         | Domain/IP regex extraction, domain relation heuristics    |
-| `log.go`           | Colorized logging with log levels                         |
-| `cmd/udig/main.go` | CLI entry point, argument parsing, output formatting      |
-
-
+| File                  | Purpose                                                   |
+| --------------------- | --------------------------------------------------------- |
+| `api.go`              | Interfaces, resolution types, `ResolutionBase`, constants |
+| `udig.go`             | Facade, queue processing, domain crawling, `NewUdig()`    |
+| `utils.go`            | Domain/IP regex extraction, domain relation heuristics    |
+| `log.go`              | Colorized logging with log levels                         |
+| `cmd/udig/main.go`    | CLI entry point, argument parsing, output formatting      |
+| `cmd/udig/graph/`     | Graph output: DOT, JSON, terminal tree                    |

README.md

@@ -7,7 +7,7 @@
 
 **Fast, non-intrusive domain reconnaissance tool written in Go.**
 
-Udig provides a quick overview of a target domain's infrastructure by combining multiple active scanning techniques — DNS enumeration (including CAA, DNSSEC, and DMARC), TLS certificate scraping, WHOIS lookups, HTTP analysis (headers, security.txt and robots.txt), Certificate Transparency log search, BGP ASN mapping, GeoIP resolution, and RDAP (RIR registration data for discovered IPs). Discovered domains are automatically followed and resolved recursively.
+Udig provides a quick overview of a target domain's infrastructure by combining multiple active scanning techniques — DNS enumeration (including CAA, DNSSEC, and DMARC), TLS certificate scraping, WHOIS lookups, HTTP analysis (headers, security.txt and robots.txt), Certificate Transparency log search, BGP ASN mapping, GeoIP resolution, RDAP (RIR registration data for discovered IPs), DNSBL blocklist checks and Tor exit-node detection Discovered domains are automatically followed and resolved recursively.
 
 This is not a full-blown DNS enumerator. There is no brute-forcing, no port scanning, no search engine scraping. udig is designed to be unobtrusive and fast, suitable for long-term experiments with many targets.
 
@@ -24,6 +24,8 @@ This is not a full-blown DNS enumerator. There is no brute-forcing, no port scan
 - **BGP** — maps discovered IPs to autonomous systems via Team Cymru
 - **GeoIP** — resolves country codes for discovered IPs via IP2Location
 - **RDAP** — looks up IP registration metadata (network name, handle, range, abuse contact) via RIR RDAP servers using the IANA bootstrap (no API key)
+- **DNSBL** — checks discovered IPs against DNS blocklists (Barracuda, UCEProtect, DroneBL) and decodes return codes
+- **Tor** — detects Tor nodes (exit, guard, relay) via the Onionoo API; reports nickname, fingerprint, and flags
 - **Recursive crawling** — domains found in any resolution are automatically followed
 - **Output** — colorized human-readable CLI output, JSON or graph as DOT (Graphviz), JSON, or terminal tree (`--graph=dot|json|term`)
 

api.go

@@ -47,6 +47,12 @@ const (
 
 	// TypeRDAP is a type of all RDAP (Registration Data Access Protocol) resolutions.
 	TypeRDAP ResolutionType = "RDAP"
+
+	// TypeDNSBL is a type of all DNSBL (DNS Blocklist) resolutions.
+	TypeDNSBL ResolutionType = "DNSBL"
+
+	// TypeTor is a type of all Tor exit-node resolutions.
+	TypeTor ResolutionType = "TOR"
 )
 
 // Udig is a high-level facade for domain resolution which:

cmd/udig/graph/graph.go

@@ -17,6 +17,8 @@ const (
 	nodeTypeCountry nodeType = "country"
 	nodeTypeWhois   nodeType = "whois"
 	nodeTypeRDAP    nodeType = "rdap"
+	nodeTypeDNSBL   nodeType = "dnsbl"
+	nodeTypeTor     nodeType = "tor"
 )
 
 func (t nodeType) String() string {
@@ -167,6 +169,24 @@ func (g *Graph) Collect(domain string, options []udig.Option) {
 			if nodeID != "" && nodeID != "RDAP/" {
 				g.addEdge(query, nodeID, "RDAP", nodeTypeRDAP)
 			}
+
+		case udig.TypeDNSBL:
+			g.addNode(query, nodeTypeIP)
+			record := res.(*udig.DNSBLResolution).Record
+			zoneNode := fmt.Sprintf("%s (%s)", record.Zone, record.Meaning)
+			g.addEdge(query, zoneNode, "DNSBL", nodeTypeDNSBL)
+
+		case udig.TypeTor:
+			g.addNode(query, nodeTypeIP)
+			record := res.(*udig.TorResolution).Record
+			label := "Tor Relay"
+			if record.IsExitNode() {
+				label = "Tor Exit Node"
+			}
+			if record.Nickname != "" {
+				label = fmt.Sprintf("%s (%s)", label, record.Nickname)
+			}
+			g.addEdge(query, label, "TOR", nodeTypeTor)
 		}
 	}
 }

cmd/udig/graph/graph_dot.go

@@ -37,6 +37,12 @@ func dotEdgeStyle(label string) (color, fontcolor string) {
 	case label == "RDAP":
 		return "#89B4FA", "#89B4FA"
 
+	case label == "DNSBL":
+		return "#F38BA8", "#F38BA8"
+
+	case label == "TOR":
+		return "#F5C2E7", "#F5C2E7"
+
 	default:
 		return "#6C7086", "#9399B2"
 	}
@@ -94,6 +100,12 @@ func (g *Graph) EmitDOT() error {
 		case nodeTypeRDAP:
 			attrs = `fillcolor="#89B4FA", fontcolor="#1B1B1C"`
 
+		case nodeTypeDNSBL:
+			attrs = `fillcolor="#F38BA8", fontcolor="#1B1B1C"`
+
+		case nodeTypeTor:
+			attrs = `fillcolor="#F5C2E7", fontcolor="#1B1B1C"`
+
 		default:
 			attrs = `fillcolor="#313244", fontcolor="#CDD6F4"`
 		}

cmd/udig/graph/graph_term.go

@@ -11,6 +11,7 @@ const (
 	termCyan    = "\033[1;36m"
 	termGreen   = "\033[1;32m"
 	termMagenta = "\033[1;35m"
+	termRed     = "\033[1;31m"
 )
 
 // isSharedLeaf returns true for node types that are shared singletons (country codes,
@@ -27,6 +28,10 @@ func (t nodeType) termColor() string {
 		return termGreen
 	case nodeTypeCountry:
 		return termMagenta
+	case nodeTypeDNSBL:
+		return termRed
+	case nodeTypeTor:
+		return termMagenta
 	default:
 		return termReset
 	}