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): webbug generator (Generate + Trigger)
CarterPerez-dev9c0ad74973cf
diff --git a/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/webbug/generator.go b/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/webbug/generator.gonew file mode 100644index 00000000..c833a5e0--- /dev/null+++ b/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/webbug/generator.go@@ -0,0 +1,87 @@+// ©AngelaMos | 2026+// generator.go++package webbug++import (+ "context"+ "net/http"+ "strings"++ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/event"+ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/token"+ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/token/generators"+ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/token/generators/pixel"+)++const (+ headerCFConnectingIP = "CF-Connecting-IP"+ headerXForwardedFor = "X-Forwarded-For"+ headerXRealIP = "X-Real-IP"+ headerReferer = "Referer"+ headerCacheControl = "Cache-Control"+ headerPragma = "Pragma"++ cacheControlNoStore = "no-store, no-cache, must-revalidate, max-age=0"+ pragmaNoCache = "no-cache"++ triggerPathPrefix = "/c/"+)++type Generator struct{}++func New() *Generator { return &Generator{} }++func (g *Generator) Type() token.Type { return token.TypeWebbug }++func (g *Generator) Generate(_ context.Context, t *token.Token, baseURL string) (generators.Artifact, error) {+ return generators.Artifact{+ Kind: generators.KindURL,+ URL: strings.TrimRight(baseURL, "/") + triggerPathPrefix + t.ID,+ }, nil+}++func (g *Generator) Trigger(_ context.Context, t *token.Token, r *http.Request) (*event.Event, *generators.TriggerResponse, error) {+ tokenID := ""+ if t != nil {+ tokenID = t.ID+ }+ evt := &event.Event{+ TokenID: tokenID,+ SourceIP: realIP(r),+ UserAgent: optionalHeader(r.UserAgent()),+ Referer: optionalHeader(r.Header.Get(headerReferer)),+ }+ resp := &generators.TriggerResponse{+ StatusCode: http.StatusOK,+ ContentType: pixel.ContentType,+ Body: pixel.TransparentGIF,+ ExtraHeaders: map[string]string{+ headerCacheControl: cacheControlNoStore,+ headerPragma: pragmaNoCache,+ },+ }+ return evt, resp, nil+}++func optionalHeader(v string) *string {+ v = strings.TrimSpace(v)+ if v == "" {+ return nil+ }+ return &v+}++func realIP(r *http.Request) string {+ if v := strings.TrimSpace(r.Header.Get(headerCFConnectingIP)); v != "" {+ return v+ }+ if v := r.Header.Get(headerXForwardedFor); v != "" {+ parts := strings.Split(v, ",")+ return strings.TrimSpace(parts[len(parts)-1])+ }+ if v := strings.TrimSpace(r.Header.Get(headerXRealIP)); v != "" {+ return v+ }+ return r.RemoteAddr+}diff --git a/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/webbug/generator_test.go b/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/webbug/generator_test.gonew file mode 100644index 00000000..fc77d632--- /dev/null+++ b/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/webbug/generator_test.go@@ -0,0 +1,212 @@+// ©AngelaMos | 2026+// generator_test.go++package webbug_test++import (+ "context"+ "net/http"+ "net/http/httptest"+ "testing"++ "github.com/stretchr/testify/require"++ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/token"+ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/token/generators"+ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/token/generators/pixel"+ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/token/generators/webbug"+)++const (+ cacheControlNoStore = "no-store, no-cache, must-revalidate, max-age=0"+ pragmaNoCache = "no-cache"+ gifByteLength = 43+)++func newWebbugToken(id string) *token.Token {+ return &token.Token{+ ID: id,+ ManageID: "manage-" + id,+ Type: token.TypeWebbug,+ Memo: "unit test webbug",+ AlertChannel: token.ChannelWebhook,+ Enabled: true,+ }+}++func TestGenerator_TypeIsWebbug(t *testing.T) {+ g := webbug.New()+ require.Equal(t, token.TypeWebbug, g.Type())+}++func TestGenerate_ReturnsURLArtifact(t *testing.T) {+ cases := []struct {+ name string+ baseURL string+ id string+ wantURL string+ }{+ {+ name: "no trailing slash",+ baseURL: "https://canary.example.com",+ id: "abc123",+ wantURL: "https://canary.example.com/c/abc123",+ },+ {+ name: "trailing slash trimmed",+ baseURL: "https://canary.example.com/",+ id: "xyz999",+ wantURL: "https://canary.example.com/c/xyz999",+ },+ {+ name: "subpath base URL preserved",+ baseURL: "https://example.com/canary",+ id: "p7",+ wantURL: "https://example.com/canary/c/p7",+ },+ }++ g := webbug.New()+ for _, tc := range cases {+ tc := tc+ t.Run(tc.name, func(t *testing.T) {+ art, err := g.Generate(context.Background(), newWebbugToken(tc.id), tc.baseURL)+ require.NoError(t, err)+ require.Equal(t, generators.KindURL, art.Kind)+ require.Equal(t, tc.wantURL, art.URL)+ })+ }+}++func TestTrigger_RecordsEventWithRequestMetadata(t *testing.T) {+ g := webbug.New()+ tok := newWebbugToken("token1")++ t.Run("captures token id, source ip, user agent, referer", func(t *testing.T) {+ r := httptest.NewRequest(http.MethodGet, "/c/token1", nil)+ r.Header.Set("CF-Connecting-IP", "203.0.113.50")+ r.Header.Set("User-Agent", "Mozilla/5.0 (X11; Linux x86_64)")+ r.Header.Set("Referer", "https://victim.example.com/inbox")++ evt, _, err := g.Trigger(context.Background(), tok, r)+ require.NoError(t, err)+ require.NotNil(t, evt)+ require.Equal(t, "token1", evt.TokenID)+ require.Equal(t, "203.0.113.50", evt.SourceIP)+ require.NotNil(t, evt.UserAgent)+ require.Equal(t, "Mozilla/5.0 (X11; Linux x86_64)", *evt.UserAgent)+ require.NotNil(t, evt.Referer)+ require.Equal(t, "https://victim.example.com/inbox", *evt.Referer)+ })++ t.Run("source ip precedence CF > XFF (last) > XRI > RemoteAddr", func(t *testing.T) {+ cases := []struct {+ name string+ headers map[string]string+ remote string+ wantIP string+ }{+ {+ name: "CF wins over XFF and XRI",+ headers: map[string]string{+ "CF-Connecting-IP": "203.0.113.10",+ "X-Forwarded-For": "198.51.100.1, 198.51.100.2",+ "X-Real-IP": "192.0.2.99",+ },+ remote: "127.0.0.1:9999",+ wantIP: "203.0.113.10",+ },+ {+ name: "XFF rightmost wins over XRI when no CF",+ headers: map[string]string{+ "X-Forwarded-For": "198.51.100.1, 198.51.100.7",+ "X-Real-IP": "192.0.2.99",+ },+ remote: "127.0.0.1:9999",+ wantIP: "198.51.100.7",+ },+ {+ name: "XRI when no CF or XFF",+ headers: map[string]string{+ "X-Real-IP": "192.0.2.99",+ },+ remote: "127.0.0.1:9999",+ wantIP: "192.0.2.99",+ },+ {+ name: "RemoteAddr when no proxy headers",+ headers: nil,+ remote: "127.0.0.1:9999",+ wantIP: "127.0.0.1:9999",+ },+ {+ name: "CF value is trimmed of whitespace",+ headers: map[string]string{+ "CF-Connecting-IP": " 203.0.113.10 ",+ },+ remote: "127.0.0.1:9999",+ wantIP: "203.0.113.10",+ },+ }+ for _, tc := range cases {+ tc := tc+ t.Run(tc.name, func(t *testing.T) {+ r := httptest.NewRequest(http.MethodGet, "/c/token1", nil)+ for k, v := range tc.headers {+ r.Header.Set(k, v)+ }+ r.RemoteAddr = tc.remote+ evt, _, err := g.Trigger(context.Background(), tok, r)+ require.NoError(t, err)+ require.Equal(t, tc.wantIP, evt.SourceIP)+ })+ }+ })++ t.Run("missing user agent and referer record as nil pointers", func(t *testing.T) {+ r := httptest.NewRequest(http.MethodGet, "/c/token1", nil)+ r.Header.Del("User-Agent")+ r.Header.Del("Referer")+ r.Header.Set("CF-Connecting-IP", "203.0.113.5")++ evt, _, err := g.Trigger(context.Background(), tok, r)+ require.NoError(t, err)+ require.Nil(t, evt.UserAgent, "absent user agent must map to nil, not empty string")+ require.Nil(t, evt.Referer, "absent referer must map to nil, not empty string")+ })+}++func TestTrigger_ResponseIs43ByteGIF(t *testing.T) {+ g := webbug.New()+ tok := newWebbugToken("abc")+ r := httptest.NewRequest(http.MethodGet, "/c/abc", nil)++ _, resp, err := g.Trigger(context.Background(), tok, r)+ require.NoError(t, err)+ require.NotNil(t, resp)+ require.Equal(t, http.StatusOK, resp.StatusCode)+ require.Equal(t, pixel.ContentType, resp.ContentType)+ require.Len(t, resp.Body, gifByteLength)+ require.Equal(t, pixel.TransparentGIF, resp.Body)+ require.Equal(t, cacheControlNoStore, resp.ExtraHeaders["Cache-Control"])+ require.Equal(t, pragmaNoCache, resp.ExtraHeaders["Pragma"])+}++func TestTrigger_TokenNotFound_StillReturnsGIF(t *testing.T) {+ g := webbug.New()+ r := httptest.NewRequest(http.MethodGet, "/c/does-not-exist", nil)+ r.Header.Set("CF-Connecting-IP", "203.0.113.100")+ r.Header.Set("User-Agent", "curl/8.0.0")++ evt, resp, err := g.Trigger(context.Background(), nil, r)+ require.NoError(t, err, "nil-token path must not error (spec §8.5 defense-in-depth)")+ require.NotNil(t, resp, "nil-token path must still return GIF response")+ require.Equal(t, http.StatusOK, resp.StatusCode)+ require.Equal(t, pixel.ContentType, resp.ContentType)+ require.Equal(t, pixel.TransparentGIF, resp.Body)+ require.NotNil(t, evt, "event value still produced for forensic continuity")+ require.Empty(t, evt.TokenID, "empty TokenID signals nil token; persistence layer decides what to do")+ require.Equal(t, "203.0.113.100", evt.SourceIP, "source IP still captured for forensics")+ require.NotNil(t, evt.UserAgent)+ require.Equal(t, "curl/8.0.0", *evt.UserAgent)+}