Building 70 Projects ranging from beginner to advanced so anyone can — learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company đŸ‘‡
Go aicertificationcloud-engineeringcybercybersecuritycybersecurity-analystcybersecurity-certificationcybersecurity-certificationscybersecurity-educationcybersecurity-jobscybersecurity-portfoliocybersecurity-projectscybersecurity-toolsgrchackinglearningpentestingproject-repositoryprojetcspython
feat(canary): geoip wrapper package + config wiring
CarterPerez-devac334b14f92c
diff --git a/PROJECTS/beginner/canary-token-generator/backend/go.mod b/PROJECTS/beginner/canary-token-generator/backend/go.modindex e8b0f2d5..f15a419e 100644--- a/PROJECTS/beginner/canary-token-generator/backend/go.mod+++ b/PROJECTS/beginner/canary-token-generator/backend/go.mod@@ -3,6 +3,8 @@ module github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/go 1.25.7require (+ github.com/alicebob/miniredis/v2 v2.38.0+ github.com/cenkalti/backoff/v5 v5.0.3github.com/go-chi/chi/v5 v5.2.3github.com/go-playground/validator/v10 v10.23.0github.com/go-redis/redis_rate/v10 v10.0.1@@ -13,6 +15,7 @@ require (github.com/knadh/koanf/providers/env v1.1.0github.com/knadh/koanf/providers/file v1.2.1github.com/knadh/koanf/v2 v2.1.2+ github.com/oschwald/geoip2-golang/v2 v2.1.0github.com/pdfcpu/pdfcpu v0.12.1github.com/pressly/goose/v3 v3.27.1github.com/redis/go-redis/v9 v9.7.0@@ -25,15 +28,14 @@ require (go.opentelemetry.io/otel/trace v1.43.0golang.org/x/time v0.14.0google.golang.org/grpc v1.80.0+ gopkg.in/yaml.v3 v3.0.1)require (dario.cat/mergo v1.0.2 // indirectgithub.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c // indirectgithub.com/Microsoft/go-winio v0.6.2 // indirect- github.com/alicebob/miniredis/v2 v2.38.0 // indirectgithub.com/cenkalti/backoff/v4 v4.3.0 // indirect- github.com/cenkalti/backoff/v5 v5.0.3 // indirectgithub.com/cespare/xxhash/v2 v2.3.0 // indirectgithub.com/clipperhouse/uax29/v2 v2.7.0 // indirectgithub.com/containerd/errdefs v1.0.0 // indirect@@ -83,6 +85,7 @@ require (github.com/moby/term v0.5.2 // indirectgithub.com/opencontainers/go-digest v1.0.0 // indirectgithub.com/opencontainers/image-spec v1.1.1 // indirect+ github.com/oschwald/maxminddb-golang/v2 v2.1.1 // indirectgithub.com/pkg/errors v0.9.1 // indirectgithub.com/pmezard/go-difflib v1.0.0 // indirectgithub.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect@@ -110,5 +113,4 @@ require (google.golang.org/genproto/googleapis/rpc v0.0.0-20260420184626-e10c466a9529 // indirectgoogle.golang.org/protobuf v1.36.11 // indirectgopkg.in/yaml.v2 v2.4.0 // indirect- gopkg.in/yaml.v3 v3.0.1 // indirect)diff --git a/PROJECTS/beginner/canary-token-generator/backend/go.sum b/PROJECTS/beginner/canary-token-generator/backend/go.sumindex 23a8c405..4610b1b9 100644--- a/PROJECTS/beginner/canary-token-generator/backend/go.sum+++ b/PROJECTS/beginner/canary-token-generator/backend/go.sum@@ -167,6 +167,10 @@ github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040=github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M=+github.com/oschwald/geoip2-golang/v2 v2.1.0 h1:DjnLhNJu9WHwTrmoiQFvgmyJoczhdnm7LB23UBI2Amo=+github.com/oschwald/geoip2-golang/v2 v2.1.0/go.mod h1:qdVmcPgrTJ4q2eP9tHq/yldMTdp2VMr33uVdFbHBiBc=+github.com/oschwald/maxminddb-golang/v2 v2.1.1 h1:lA8FH0oOrM4u7mLvowq8IT6a3Q/qEnqRzLQn9eH5ojc=+github.com/oschwald/maxminddb-golang/v2 v2.1.1/go.mod h1:PLdx6PR+siSIoXqqy7C7r3SB3KZnhxWr1Dp6g0Hacl8=github.com/pdfcpu/pdfcpu v0.12.1 h1:HwoN72zJCj+pPbfMDChYBTZrT7SY0VwgUzqeaId3I20=github.com/pdfcpu/pdfcpu v0.12.1/go.mod h1:7KPpVLMavcpliPrtN6o7Kuk3cFtYq8nii3SJnnsK7ps=github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=diff --git a/PROJECTS/beginner/canary-token-generator/backend/internal/config/config.go b/PROJECTS/beginner/canary-token-generator/backend/internal/config/config.goindex 068deaa1..0df84e63 100644--- a/PROJECTS/beginner/canary-token-generator/backend/internal/config/config.go+++ b/PROJECTS/beginner/canary-token-generator/backend/internal/config/config.go@@ -28,12 +28,17 @@ type Config struct {MySQL MySQLConfig `koanf:"mysql"`Notify NotifyConfig `koanf:"notify"`Operator OperatorConfig `koanf:"operator"`+ GeoIP GeoIPConfig `koanf:"geoip"`}type OperatorConfig struct {Token string `koanf:"token"`}+type GeoIPConfig struct {+ Path string `koanf:"path"`+}+type NotifyConfig struct {DedupTTL time.Duration `koanf:"dedup_ttl"`SendTimeout time.Duration `koanf:"send_timeout"`@@ -262,6 +267,8 @@ func loadDefaults(k *koanf.Koanf) error {"notify.fingerprint_window": "5m","operator.token": "",++ "geoip.path": "/data/GeoLite2-City.mmdb",}for key, value := range defaults {@@ -313,6 +320,7 @@ var envKeyMap = map[string]string{"NOTIFY_TELEGRAM_API_BASE": "notify.telegram_api_base","NOTIFY_FINGERPRINT_WINDOW": "notify.fingerprint_window","OPERATOR_TOKEN": "operator.token",+ "GEOLITE_PATH": "geoip.path",}func envKeyReplacer(s string) string {diff --git a/PROJECTS/beginner/canary-token-generator/backend/internal/geoip/service.go b/PROJECTS/beginner/canary-token-generator/backend/internal/geoip/service.gonew file mode 100644index 00000000..37e43ca0--- /dev/null+++ b/PROJECTS/beginner/canary-token-generator/backend/internal/geoip/service.go@@ -0,0 +1,99 @@+// ©AngelaMos | 2026+// service.go++package geoip++import (+ "errors"+ "fmt"+ "net/netip"++ "github.com/oschwald/geoip2-golang/v2"+)++type Lookup struct {+ Country string+ Region string+ City string+ ASNOrg string+ ASN int+}++type Lookuper interface {+ Lookup(ip string) Lookup+}++type cityReader interface {+ City(netip.Addr) (*geoip2.City, error)+ Close() error+}++type Service struct {+ reader cityReader+}++func Open(path string) (*Service, error) {+ if path == "" {+ return nil, errors.New("geoip: path is empty")+ }+ r, err := geoip2.Open(path)+ if err != nil {+ return nil, fmt.Errorf("geoip open %q: %w", path, err)+ }+ return &Service{reader: r}, nil+}++func (s *Service) Lookup(ip string) Lookup {+ if s == nil || s.reader == nil || ip == "" {+ return Lookup{}+ }+ addr, err := netip.ParseAddr(ip)+ if err != nil {+ return Lookup{}+ }+ rec, err := s.reader.City(addr)+ if err != nil || rec == nil || !rec.HasData() {+ return Lookup{}+ }+ return extractLookup(rec)+}++func (s *Service) Close() error {+ if s == nil || s.reader == nil {+ return nil+ }+ return s.reader.Close()+}++type nopService struct{}++func NopService() Lookuper {+ return nopService{}+}++func (nopService) Lookup(string) Lookup {+ return Lookup{}+}++func extractLookup(rec *geoip2.City) Lookup {+ if rec == nil {+ return Lookup{}+ }+ return Lookup{+ Country: rec.Country.ISOCode,+ Region: firstSubdivisionName(rec.Subdivisions),+ City: rec.City.Names.English,+ }+}++func firstSubdivisionName(subs []geoip2.CitySubdivision) string {+ for _, s := range subs {+ if s.Names.English != "" {+ return s.Names.English+ }+ if s.ISOCode != "" {+ return s.ISOCode+ }+ }+ return ""+}diff --git a/PROJECTS/beginner/canary-token-generator/backend/internal/geoip/service_test.go b/PROJECTS/beginner/canary-token-generator/backend/internal/geoip/service_test.gonew file mode 100644index 00000000..bbf252d8--- /dev/null+++ b/PROJECTS/beginner/canary-token-generator/backend/internal/geoip/service_test.go@@ -0,0 +1,216 @@+// ©AngelaMos | 2026+// service_test.go++package geoip++import (+ "errors"+ "net/netip"+ "path/filepath"+ "testing"++ "github.com/oschwald/geoip2-golang/v2"+ "github.com/stretchr/testify/require"+)++type fakeCityReader struct {+ rec *geoip2.City+ err error+ calls int+ closeCalls int+ closeErr error+}++func (f *fakeCityReader) City(netip.Addr) (*geoip2.City, error) {+ f.calls+++ return f.rec, f.err+}++func (f *fakeCityReader) Close() error {+ f.closeCalls+++ return f.closeErr+}++func newServiceWithFake(r *fakeCityReader) *Service {+ return &Service{reader: r}+}++func TestNopService_AlwaysReturnsEmpty(t *testing.T) {+ t.Parallel()+ n := NopService()+ require.Equal(t, Lookup{}, n.Lookup("203.0.113.1"))+ require.Equal(t, Lookup{}, n.Lookup(""))+ require.Equal(t, Lookup{}, n.Lookup("not-an-ip"))+}++func TestNopService_SatisfiesLookuper(t *testing.T) {+ t.Parallel()+ var _ Lookuper = NopService()+}++func TestServiceImplementsLookuper(t *testing.T) {+ t.Parallel()+ var _ Lookuper = (*Service)(nil)+}++func TestOpen_EmptyPathReturnsError(t *testing.T) {+ t.Parallel()+ s, err := Open("")+ require.Error(t, err)+ require.Nil(t, s)+}++func TestOpen_NonexistentPathReturnsError(t *testing.T) {+ t.Parallel()+ missing := filepath.Join(t.TempDir(), "nonexistent.mmdb")+ s, err := Open(missing)+ require.Error(t, err)+ require.Nil(t, s)+}++func TestService_Lookup_NilReceiverReturnsEmpty(t *testing.T) {+ t.Parallel()+ var s *Service+ require.Equal(t, Lookup{}, s.Lookup("203.0.113.1"))+}++func TestService_Lookup_NilReaderReturnsEmpty(t *testing.T) {+ t.Parallel()+ s := &Service{}+ require.Equal(t, Lookup{}, s.Lookup("203.0.113.1"))+}++func TestService_Lookup_EmptyIPReturnsEmpty(t *testing.T) {+ t.Parallel()+ fake := &fakeCityReader{}+ s := newServiceWithFake(fake)+ require.Equal(t, Lookup{}, s.Lookup(""))+ require.Equal(t, 0, fake.calls,+ "empty IP must short-circuit before reader call")+}++func TestService_Lookup_MalformedIPReturnsEmpty(t *testing.T) {+ t.Parallel()+ fake := &fakeCityReader{}+ s := newServiceWithFake(fake)+ for _, bad := range []string{"not-an-ip", "999.999.999.999", "::xyz", " "} {+ require.Equal(t, Lookup{}, s.Lookup(bad), "input=%q", bad)+ }+ require.Equal(t, 0, fake.calls,+ "malformed IP must short-circuit before reader call")+}++func TestService_Lookup_ReaderErrorReturnsEmpty(t *testing.T) {+ t.Parallel()+ fake := &fakeCityReader{err: errors.New("boom")}+ s := newServiceWithFake(fake)+ require.Equal(t, Lookup{}, s.Lookup("203.0.113.1"))+ require.Equal(t, 1, fake.calls)+}++func TestService_Lookup_NoDataReturnsEmpty(t *testing.T) {+ t.Parallel()+ fake := &fakeCityReader{rec: &geoip2.City{}}+ s := newServiceWithFake(fake)+ require.Equal(t, Lookup{}, s.Lookup("203.0.113.1"))+}++func TestService_Lookup_NilRecordReturnsEmpty(t *testing.T) {+ t.Parallel()+ fake := &fakeCityReader{rec: nil}+ s := newServiceWithFake(fake)+ require.Equal(t, Lookup{}, s.Lookup("203.0.113.1"))+}++func TestService_Lookup_PopulatesAllAvailableFields(t *testing.T) {+ t.Parallel()+ rec := &geoip2.City{}+ rec.Country.ISOCode = "US"+ rec.Country.Names.English = "United States"+ rec.City.Names.English = "Mountain View"+ rec.Subdivisions = []geoip2.CitySubdivision{+ {Names: geoip2.Names{English: "California"}, ISOCode: "CA"},+ }+ fake := &fakeCityReader{rec: rec}+ s := newServiceWithFake(fake)++ got := s.Lookup("203.0.113.1")+ require.Equal(t, "US", got.Country)+ require.Equal(t, "California", got.Region)+ require.Equal(t, "Mountain View", got.City)+ require.Equal(t, 0, got.ASN,+ "City db carries no ASN; field is reserved for ASN-db extension")+ require.Empty(t, got.ASNOrg,+ "City db carries no ASNOrg; field is reserved for ASN-db extension")+}++func TestService_Lookup_AcceptsIPv6(t *testing.T) {+ t.Parallel()+ rec := &geoip2.City{}+ rec.Country.ISOCode = "DE"+ rec.City.Names.English = "Berlin"+ fake := &fakeCityReader{rec: rec}+ s := newServiceWithFake(fake)++ got := s.Lookup("2001:db8::1")+ require.Equal(t, "DE", got.Country)+ require.Equal(t, "Berlin", got.City)+}++func TestExtractLookup_NilReturnsEmpty(t *testing.T) {+ t.Parallel()+ require.Equal(t, Lookup{}, extractLookup(nil))+}++func TestExtractLookup_PicksFirstSubdivisionEnglishName(t *testing.T) {+ t.Parallel()+ rec := &geoip2.City{}+ rec.Subdivisions = []geoip2.CitySubdivision{+ {Names: geoip2.Names{English: "England"}, ISOCode: "ENG"},+ {Names: geoip2.Names{English: "Oxfordshire"}, ISOCode: "OXF"},+ }+ require.Equal(t, "England", extractLookup(rec).Region)+}++func TestExtractLookup_FallsBackToISOCodeWhenEnglishMissing(t *testing.T) {+ t.Parallel()+ rec := &geoip2.City{}+ rec.Subdivisions = []geoip2.CitySubdivision{+ {ISOCode: "CA"},+ }+ require.Equal(t, "CA", extractLookup(rec).Region)+}++func TestExtractLookup_NoSubdivisionsLeavesRegionEmpty(t *testing.T) {+ t.Parallel()+ rec := &geoip2.City{}+ rec.Country.ISOCode = "JP"+ got := extractLookup(rec)+ require.Empty(t, got.Region)+ require.Equal(t, "JP", got.Country)+}++func TestService_Close_NilReceiverIsNoOp(t *testing.T) {+ t.Parallel()+ var s *Service+ require.NoError(t, s.Close())+}++func TestService_Close_NilReaderIsNoOp(t *testing.T) {+ t.Parallel()+ require.NoError(t, (&Service{}).Close())+}++func TestService_Close_DelegatesToReader(t *testing.T) {+ t.Parallel()+ fake := &fakeCityReader{}+ require.NoError(t, newServiceWithFake(fake).Close())+ require.Equal(t, 1, fake.closeCalls)+}++func TestService_Close_PropagatesReaderError(t *testing.T) {+ t.Parallel()+ wantErr := errors.New("close failed")+ fake := &fakeCityReader{closeErr: wantErr}+ require.ErrorIs(t, newServiceWithFake(fake).Close(), wantErr)+}