This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
LinkGuard is a Go library for entropy-based detection of suspicious URLs. It analyzes links across multiple dimensions to identify phishing attempts, homoglyph attacks, obfuscation techniques, and other malicious patterns.
The library uses a flexible, extensible analyzer architecture that supports custom analysis methods and configurable weights.
The library is built around the Analyzer type and AnalysisMethod interface:
- Analyzer: Manages a collection of analysis methods and coordinates their execution
- AnalysisMethod Interface: Defines the contract for all analysis methods (built-in or custom)
- Built-in Methods: EntropyAnalysis, UnicodeAnalysis, StructureAnalysis
Users can:
- Use the default analyzer via
Analyze()(backward compatible) - Create custom analyzers with
NewAnalyzer(methods...) - Implement custom analysis methods by implementing
AnalysisMethod - Adjust weights to prioritize different detection strategies
The library includes three built-in analysis modules that can be used together or independently:
-
Entropy Analysis (
entropy.go): Calculates Shannon entropy to detect randomness/obfuscation- Normal URLs: ~3.0-4.5 entropy
- Suspicious URLs: >4.5 entropy
-
Unicode Analysis (
unicode.go): Detects Unicode-based attacks- Homoglyphs: Characters from non-Latin scripts that visually resemble ASCII (e.g., Cyrillic 'а' vs Latin 'a')
- Invisible characters: Zero-width spaces, joiners, and other hidden Unicode
- Mixed scripts: Unusual combinations of writing systems
-
Structure Analysis (
structure.go): Examines URL construction patterns- IP addresses instead of domains
- Non-standard ports
- Excessive subdomains (>3)
- Path depth (>5 segments)
- Double encoding (%2520)
- Suspicious TLDs (.tk, .ml, .ga, etc.)
- @ sign in authority section
- Excessive length (>200 chars)
The main analyzer (analyzer.go) combines scores using weighted averages:
- Entropy: 35%
- Unicode: 35%
- Structure: 30%
Final scores map to risk levels:
- 0.0-0.15: None
- 0.15-0.30: Low
- 0.30-0.55: Medium
- 0.55-0.80: High
- 0.80-1.0: Critical
URLs with Medium risk or above are considered suspicious (Result.IsSuspicious()).
# Run all tests
go test
# Run tests with verbose output
go test -v
# Run tests with coverage
go test -cover
# Run specific test
go test -run TestAnalyze_HomoglyphDomain
# Run with race detection
go test -race# Build (library doesn't produce binary, but verifies build)
go build
# Verify module dependencies
go mod verify
# Tidy dependencies
go mod tidy# Run all benchmarks
go test -bench=.
# Run benchmarks with memory statistics
go test -bench=. -benchmem
# Run specific benchmark
go test -bench=BenchmarkAnalyze_Simple
# Run benchmarks for longer duration (more accurate)
go test -bench=. -benchtime=5sNewAnalyzer(methods ...AnalysisMethod) *Analyzer: Create analyzer with specified methodsDefaultMethods() []AnalysisMethod: Get default analysis methods (entropy, unicode, structure)(*Analyzer) Analyze(rawURL string) Result: Analyze single URL(*Analyzer) AnalyzeMultiple(urls []string) []Result: Batch analysisShannonEntropy(s string) float64: Calculate Shannon entropyNormalizedEntropy(s string) float64: Entropy normalized to [0,1]
Tests in linkguard_test.go are organized by module:
- Entropy tests:
TestShannonEntropy_* - Unicode tests:
TestAnalyzeUnicode_* - Structure tests:
TestAnalyzeStructure_* - Integration tests:
TestAnalyze_*
Each analysis function has both unit tests (testing individual components) and integration tests (testing full Analyze() flow).
When modifying thresholds, be aware of these constants in structure.go:
maxNormalSubdomains = 3maxNormalPathDepth = 5maxNormalLength = 200
Entropy thresholds are in the entropyScore() function in entropy.go.
To add new patterns to existing methods:
- Add detection logic to the appropriate analysis function (
analyzeUnicode,analyzeStructure, etc.) - Add the flag to the corresponding report struct in
linkguard.go - Update the scoring function (
unicodeScore,structureScore, etc.) to weight the new signal - Add human-readable reason in
buildReasons()inanalyzer.go - Add test cases in
linkguard_test.go
Create a new type implementing AnalysisMethod:
type MyCustomAnalysis struct {
WeightValue float64
// Custom configuration fields
}
func (m *MyCustomAnalysis) Analyze(rawURL string, result *Result) float64 {
// Your detection logic
// Return score 0.0 (safe) to 1.0 (suspicious)
}
func (m *MyCustomAnalysis) Weight() float64 {
return m.WeightValue
}
func (m *MyCustomAnalysis) Name() string {
return "My Custom Analysis"
}Then use it:
analyzer := linkguard.NewAnalyzer(
&linkguard.EntropyAnalysis{WeightValue: 0.3},
&linkguard.UnicodeAnalysis{WeightValue: 0.3},
&MyCustomAnalysis{WeightValue: 0.4},
)See the "Custom Analyzers" section in README.md for comprehensive examples and analyzer_test.go for reference implementations.