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): kubeconfig fake K8s API handler (forbidden response)
CarterPerez-devbd0c6646022e
diff --git a/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/kubeconfig/handler.go b/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/kubeconfig/handler.gonew file mode 100644index 00000000..c2028ece--- /dev/null+++ b/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/kubeconfig/handler.go@@ -0,0 +1,201 @@+// ©AngelaMos | 2026+// handler.go++package kubeconfig++import (+ "context"+ "encoding/json"+ "fmt"+ "net"+ "net/http"+ "path"+ "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"+)++const (+ headerCFConnectingIP = "CF-Connecting-IP"+ headerXForwardedFor = "X-Forwarded-For"+ headerXRealIP = "X-Real-IP"+ headerReferer = "Referer"+ headerUserAgent = "User-Agent"+ headerCacheControl = "Cache-Control"+ headerPragma = "Pragma"++ cacheControlNoStore = "no-store, no-cache, must-revalidate, max-age=0"+ pragmaNoCache = "no-cache"+ contentTypeJSON = "application/json"++ statusKind = "Status"+ statusAPIVersion = "v1"+ statusFailure = "Failure"+ statusReason = "Forbidden"+ statusMessageFmt = `%s is forbidden: User "system:anonymous" cannot %s resource "%s" in API group "" in the namespace "default"`++ defaultResource = "resource"++ verbList = "list"+ verbCreate = "create"+ verbUpdate = "update"+ verbPatch = "patch"+ verbDelete = "delete"++ extraKubectlPath = "kubectl_path"+ extraKubectlMethod = "kubectl_method"+ extraKubectlQuery = "kubectl_query"+ extraKubectlUA = "kubectl_ua"+)++type kubernetesStatus struct {+ Kind string `json:"kind"`+ APIVersion string `json:"apiVersion"`+ Metadata statusMetadata `json:"metadata"`+ Status string `json:"status"`+ Message string `json:"message"`+ Reason string `json:"reason"`+ Code int `json:"code"`+}++type statusMetadata struct{}++func (g *Generator) Trigger(+ _ context.Context,+ t *token.Token,+ r *http.Request,+) (*event.Event, *generators.TriggerResponse, error) {+ resource := resourceFromPath(r.URL.Path)+ verb := verbFromMethod(r.Method)++ body, err := buildForbiddenBody(resource, verb)+ if err != nil {+ return nil, nil, fmt.Errorf(+ "kubeconfig: build forbidden response: %w",+ err,+ )+ }++ resp := &generators.TriggerResponse{+ StatusCode: http.StatusForbidden,+ ContentType: contentTypeJSON,+ Body: body,+ ExtraHeaders: map[string]string{+ headerCacheControl: cacheControlNoStore,+ headerPragma: pragmaNoCache,+ },+ }++ if t == nil {+ return nil, resp, nil+ }++ extra, err := buildKubectlExtra(r)+ if err != nil {+ return nil, nil, fmt.Errorf(+ "kubeconfig: build event extra: %w",+ err,+ )+ }++ evt := &event.Event{+ TokenID: t.ID,+ SourceIP: realIP(r),+ UserAgent: optionalHeader(r.UserAgent()),+ Referer: optionalHeader(r.Header.Get(headerReferer)),+ Extra: extra,+ }+ return evt, resp, nil+}++func buildForbiddenBody(resource, verb string) ([]byte, error) {+ s := kubernetesStatus{+ Kind: statusKind,+ APIVersion: statusAPIVersion,+ Status: statusFailure,+ Message: fmt.Sprintf(statusMessageFmt, resource, verb, resource),+ Reason: statusReason,+ Code: http.StatusForbidden,+ }+ body, err := json.Marshal(s)+ if err != nil {+ return nil, fmt.Errorf("marshal kubernetes status: %w", err)+ }+ return body, nil+}++func buildKubectlExtra(r *http.Request) (json.RawMessage, error) {+ extra := map[string]string{+ extraKubectlPath: r.URL.Path,+ extraKubectlMethod: r.Method,+ extraKubectlQuery: r.URL.RawQuery,+ extraKubectlUA: r.Header.Get(headerUserAgent),+ }+ body, err := json.Marshal(extra)+ if err != nil {+ return nil, fmt.Errorf("marshal kubectl extra: %w", err)+ }+ return body, nil+}++func resourceFromPath(urlPath string) string {+ last := path.Base(urlPath)+ if last == "" || last == "/" || last == "." {+ return defaultResource+ }+ return last+}++func verbFromMethod(method string) string {+ switch method {+ case http.MethodPost:+ return verbCreate+ case http.MethodPut:+ return verbUpdate+ case http.MethodPatch:+ return verbPatch+ case http.MethodDelete:+ return verbDelete+ default:+ return verbList+ }+}++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 := lastNonEmptyXFF(r.Header.Get(headerXForwardedFor)); v != "" {+ return v+ }+ if v := strings.TrimSpace(r.Header.Get(headerXRealIP)); v != "" {+ return v+ }+ if host, _, err := net.SplitHostPort(r.RemoteAddr); err == nil {+ return host+ }+ return r.RemoteAddr+}++func lastNonEmptyXFF(header string) string {+ if header == "" {+ return ""+ }+ parts := strings.Split(header, ",")+ for i := len(parts) - 1; i >= 0; i-- {+ if v := strings.TrimSpace(parts[i]); v != "" {+ return v+ }+ }+ return ""+}diff --git a/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/kubeconfig/handler_test.go b/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/kubeconfig/handler_test.gonew file mode 100644index 00000000..5e29cec9--- /dev/null+++ b/PROJECTS/beginner/canary-token-generator/backend/internal/token/generators/kubeconfig/handler_test.go@@ -0,0 +1,518 @@+// ©AngelaMos | 2026+// handler_test.go++package kubeconfig_test++import (+ "context"+ "encoding/json"+ "net/http"+ "net/http/httptest"+ "testing"++ "github.com/stretchr/testify/require"++ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/token/generators/kubeconfig"+)++const (+ cacheControlNoStoreValue = "no-store, no-cache, must-revalidate, max-age=0"+ pragmaNoCacheValue = "no-cache"+ expectedResponseMIME = "application/json"+)++type k8sStatusResponse struct {+ Kind string `json:"kind"`+ APIVersion string `json:"apiVersion"`+ Metadata map[string]interface{} `json:"metadata"`+ Status string `json:"status"`+ Message string `json:"message"`+ Reason string `json:"reason"`+ Code int `json:"code"`+}++type kubectlExtra struct {+ KubectlPath string `json:"kubectl_path"`+ KubectlMethod string `json:"kubectl_method"`+ KubectlQuery string `json:"kubectl_query"`+ KubectlUA string `json:"kubectl_ua"`+}++func parseStatus(t *testing.T, body []byte) k8sStatusResponse {+ t.Helper()+ var s k8sStatusResponse+ require.NoError(+ t,+ json.Unmarshal(body, &s),+ "response body must be valid Kubernetes Status JSON",+ )+ return s+}++func parseKubectlExtra(t *testing.T, raw json.RawMessage) kubectlExtra {+ t.Helper()+ var k kubectlExtra+ require.NoError(t, json.Unmarshal(raw, &k))+ return k+}++func TestTrigger_ResponseStatusCodeIs403(t *testing.T) {+ g := kubeconfig.New()+ tok := newKubeconfigToken("abc")+ r := httptest.NewRequest(http.MethodGet, "/k/abc/api/v1/pods", nil)++ _, resp, err := g.Trigger(context.Background(), tok, r)+ require.NoError(t, err)+ require.NotNil(t, resp)+ require.Equal(t, http.StatusForbidden, resp.StatusCode)+}++func TestTrigger_ResponseContentTypeIsJSON(t *testing.T) {+ g := kubeconfig.New()+ tok := newKubeconfigToken("abc")+ r := httptest.NewRequest(http.MethodGet, "/k/abc/api/v1/pods", nil)++ _, resp, err := g.Trigger(context.Background(), tok, r)+ require.NoError(t, err)+ require.Equal(t, expectedResponseMIME, resp.ContentType)+}++func TestTrigger_CacheHeadersSet(t *testing.T) {+ g := kubeconfig.New()+ tok := newKubeconfigToken("abc")+ r := httptest.NewRequest(http.MethodGet, "/k/abc/api/v1/pods", nil)++ _, resp, err := g.Trigger(context.Background(), tok, r)+ require.NoError(t, err)+ require.Equal(+ t,+ cacheControlNoStoreValue,+ resp.ExtraHeaders["Cache-Control"],+ )+ require.Equal(t, pragmaNoCacheValue, resp.ExtraHeaders["Pragma"])+}++func TestTrigger_ResponseIsValidKubernetesStatus(t *testing.T) {+ g := kubeconfig.New()+ tok := newKubeconfigToken("abc")+ r := httptest.NewRequest(http.MethodGet, "/k/abc/api/v1/pods", nil)++ _, resp, err := g.Trigger(context.Background(), tok, r)+ require.NoError(t, err)++ s := parseStatus(t, resp.Body)+ require.Equal(t, "Status", s.Kind)+ require.Equal(t, "v1", s.APIVersion)+ require.NotNil(t, s.Metadata)+ require.Empty(t, s.Metadata, "metadata must be empty object {}")+ require.Equal(t, "Failure", s.Status)+ require.Equal(t, "Forbidden", s.Reason)+ require.Equal(t, http.StatusForbidden, s.Code)+}++func TestTrigger_MessageUsesPathLastSegmentAsResource(t *testing.T) {+ g := kubeconfig.New()+ tok := newKubeconfigToken("abc")++ cases := []struct {+ name string+ path string+ wantWord string+ }{+ {+ name: "pods endpoint",+ path: "/k/abc/api/v1/namespaces/default/pods",+ wantWord: "pods",+ },+ {+ name: "secrets endpoint",+ path: "/k/abc/api/v1/secrets",+ wantWord: "secrets",+ },+ {+ name: "single-resource get",+ path: "/k/abc/api/v1/namespaces/default/pods/web-1",+ wantWord: "web-1",+ },+ {+ name: "api version probe",+ path: "/k/abc/api/v1",+ wantWord: "v1",+ },+ {+ name: "trailing slash path falls back to default",+ path: "/k/abc/",+ wantWord: "abc",+ },+ {+ name: "non-resource healthz probe",+ path: "/k/abc/healthz",+ wantWord: "healthz",+ },+ }+ for _, tc := range cases {+ tc := tc+ t.Run(tc.name, func(t *testing.T) {+ r := httptest.NewRequest(http.MethodGet, tc.path, nil)+ _, resp, err := g.Trigger(context.Background(), tok, r)+ require.NoError(t, err)+ s := parseStatus(t, resp.Body)+ require.Contains(+ t,+ s.Message,+ tc.wantWord+` is forbidden`,+ "message must lead with the resource name",+ )+ require.Contains(+ t,+ s.Message,+ `resource "`+tc.wantWord+`"`,+ "message must repeat the resource name in the resource clause",+ )+ })+ }+}++func TestTrigger_MessageVerbDerivedFromHTTPMethod(t *testing.T) {+ g := kubeconfig.New()+ tok := newKubeconfigToken("abc")++ cases := []struct {+ method string+ wantVerb string+ }{+ {http.MethodGet, "list"},+ {http.MethodHead, "list"},+ {http.MethodPost, "create"},+ {http.MethodPut, "update"},+ {http.MethodPatch, "patch"},+ {http.MethodDelete, "delete"},+ {http.MethodOptions, "list"},+ }+ for _, tc := range cases {+ tc := tc+ t.Run(tc.method, func(t *testing.T) {+ r := httptest.NewRequest(+ tc.method,+ "/k/abc/api/v1/pods",+ nil,+ )+ _, resp, err := g.Trigger(context.Background(), tok, r)+ require.NoError(t, err)+ s := parseStatus(t, resp.Body)+ require.Contains(+ t,+ s.Message,+ `cannot `+tc.wantVerb+` resource`,+ "message must use the verb mapped from the HTTP method",+ )+ })+ }+}++func TestTrigger_MessageImpersonatesAnonymousUser(t *testing.T) {+ g := kubeconfig.New()+ tok := newKubeconfigToken("abc")+ r := httptest.NewRequest(http.MethodGet, "/k/abc/api/v1/pods", nil)++ _, resp, err := g.Trigger(context.Background(), tok, r)+ require.NoError(t, err)++ s := parseStatus(t, resp.Body)+ require.Contains(+ t,+ s.Message,+ `User "system:anonymous"`,+ "message must impersonate the anonymous user for verisimilitude",+ )+}++func TestTrigger_RecordsEventWithRequestMetadata(t *testing.T) {+ g := kubeconfig.New()+ tok := newKubeconfigToken("token1")++ t.Run(+ "captures token id, source ip, user agent, referer",+ func(t *testing.T) {+ r := httptest.NewRequest(+ http.MethodGet,+ "/k/token1/api/v1/pods?watch=true",+ nil,+ )+ r.Header.Set("CF-Connecting-IP", "203.0.113.50")+ r.Header.Set(+ "User-Agent",+ "kubectl/v1.30.0 (linux/amd64) kubernetes/9b7f2dd",+ )+ r.Header.Set("Referer", "https://victim.example.com/dashboard")++ 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,+ "kubectl/v1.30.0 (linux/amd64) kubernetes/9b7f2dd",+ *evt.UserAgent,+ )+ require.NotNil(t, evt.Referer)+ require.Equal(+ t,+ "https://victim.example.com/dashboard",+ *evt.Referer,+ )+ },+ )++ t.Run("kubectl_* extra captured", func(t *testing.T) {+ r := httptest.NewRequest(+ http.MethodPost,+ "/k/token1/api/v1/namespaces/default/pods?dryRun=All",+ nil,+ )+ r.Header.Set("CF-Connecting-IP", "203.0.113.50")+ r.Header.Set("User-Agent", "kubectl/v1.30.0")++ evt, _, err := g.Trigger(context.Background(), tok, r)+ require.NoError(t, err)+ require.NotNil(t, evt)++ extra := parseKubectlExtra(t, evt.Extra)+ require.Equal(+ t,+ "/k/token1/api/v1/namespaces/default/pods",+ extra.KubectlPath,+ )+ require.Equal(t, http.MethodPost, extra.KubectlMethod)+ require.Equal(t, "dryRun=All", extra.KubectlQuery)+ require.Equal(t, "kubectl/v1.30.0", extra.KubectlUA)+ })++ t.Run("missing query is empty string in extra", func(t *testing.T) {+ r := httptest.NewRequest(+ http.MethodGet,+ "/k/token1/api/v1/pods",+ nil,+ )+ evt, _, err := g.Trigger(context.Background(), tok, r)+ require.NoError(t, err)+ extra := parseKubectlExtra(t, evt.Extra)+ require.Empty(t, extra.KubectlQuery)+ })++ t.Run("source ip precedence", 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: "XFF trailing-comma falls through to last non-empty",+ headers: map[string]string{+ "X-Forwarded-For": "198.51.100.1, ",+ "X-Real-IP": "192.0.2.99",+ },+ remote: "127.0.0.1:9999",+ wantIP: "198.51.100.1",+ },+ {+ name: "XFF entirely empty entries fall through to XRI",+ headers: map[string]string{+ "X-Forwarded-For": ", ,",+ "X-Real-IP": "192.0.2.99",+ },+ remote: "127.0.0.1:9999",+ wantIP: "192.0.2.99",+ },+ {+ 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 IPv4 strips port",+ headers: nil,+ remote: "127.0.0.1:9999",+ wantIP: "127.0.0.1",+ },+ {+ name: "RemoteAddr IPv6 strips brackets and port",+ headers: nil,+ remote: "[2001:db8::1]:54321",+ wantIP: "2001:db8::1",+ },+ {+ name: "RemoteAddr loopback IPv6 strips brackets and port",+ headers: nil,+ remote: "[::1]:9999",+ wantIP: "::1",+ },+ {+ name: "RemoteAddr without port falls back to raw value",+ headers: nil,+ remote: "127.0.0.1",+ wantIP: "127.0.0.1",+ },+ {+ name: "XFF IPv6 rightmost",+ headers: map[string]string{+ "X-Forwarded-For": "198.51.100.1, 2001:db8::dead",+ },+ remote: "127.0.0.1:9999",+ wantIP: "2001:db8::dead",+ },+ {+ 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,+ "/k/token1/api/v1/pods",+ 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.NotNil(t, evt)+ 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,+ "/k/token1/api/v1/pods",+ 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.NotNil(t, evt)+ 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_TokenNotFound_StillReturns403(t *testing.T) {+ g := kubeconfig.New()+ r := httptest.NewRequest(+ http.MethodGet,+ "/k/does-not-exist/api/v1/pods",+ nil,+ )+ r.Header.Set("CF-Connecting-IP", "203.0.113.100")+ r.Header.Set("User-Agent", "kubectl/v1.30.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)+ require.Equal(+ t,+ http.StatusForbidden,+ resp.StatusCode,+ "nil-token still returns 403 so attackers cannot distinguish valid vs invalid tokens",+ )+ require.Equal(t, expectedResponseMIME, resp.ContentType)+ require.NotEmpty(t, resp.Body)++ s := parseStatus(t, resp.Body)+ require.Equal(t, "Status", s.Kind)+ require.Equal(t, "Failure", s.Status)++ require.Nil(+ t,+ evt,+ "nil-token path returns nil event so the handler cannot persist a row with empty TokenID (FK violation)",+ )+}++func TestTrigger_NilTokenResponseShapeMatchesValidToken(t *testing.T) {+ g := kubeconfig.New()+ tok := newKubeconfigToken("real-token")++ r1 := httptest.NewRequest(+ http.MethodGet,+ "/k/real-token/api/v1/pods",+ nil,+ )+ r2 := httptest.NewRequest(+ http.MethodGet,+ "/k/does-not-exist/api/v1/pods",+ nil,+ )++ _, respValid, err := g.Trigger(context.Background(), tok, r1)+ require.NoError(t, err)+ _, respMissing, err := g.Trigger(context.Background(), nil, r2)+ require.NoError(t, err)++ sValid := parseStatus(t, respValid.Body)+ sMissing := parseStatus(t, respMissing.Body)++ require.Equal(t, sValid.Kind, sMissing.Kind)+ require.Equal(t, sValid.APIVersion, sMissing.APIVersion)+ require.Equal(t, sValid.Status, sMissing.Status)+ require.Equal(t, sValid.Reason, sMissing.Reason)+ require.Equal(t, sValid.Code, sMissing.Code)+ require.Equal(+ t,+ respValid.StatusCode,+ respMissing.StatusCode,+ "HTTP status code must be identical so attackers cannot probe token validity by response code",+ )+}